Add --prefer-stubs=y option

Author: jacobtylerwalls

doc/whatsnew/fragments/9626.bugfix

@@ -0,0 +1,9 @@
+Add `--prefer-stubs=yes` option to opt-in to the astroid 3.2 feature
+that prefers `.pyi` stubs over same-named `.py` files. This has the
+potential to reduce `no-member` errors but at the cost of more errors
+such as `not-an-iterable` from function bodies appearing as `...`.
+
+Defaults to `no`.
+
+Closes #9626
+Closes #9623

examples/pylintrc

@@ -87,6 +87,10 @@ load-plugins=
 # Pickle collected data for later comparisons.
 persistent=yes
 
+# Resolve imports to .pyi stubs if available. May reduce no-member messages
+# and increase not-an-iterable messages.
+prefer-stubs=no
+
 # Minimum Python version to use for version dependent checks. Will default to
 # the version used to run pylint.
 py-version=3.10

examples/pyproject.toml

@@ -77,6 +77,10 @@ limit-inference-results = 100
 # Pickle collected data for later comparisons.
 persistent = true
 
+# Resolve imports to .pyi stubs if available. May reduce no-member messages
+# and increase not-an-iterable messages.
+prefer-stubs = false
+
 # Minimum Python version to use for version dependent checks. Will default to the
 # version used to run pylint.
 py-version = "3.10"

pylint/lint/base_options.py

@@ -415,6 +415,17 @@ def _make_linter_options(linter: PyLinter) -> Options:
                 "Useful if running pylint in a server-like mode.",
             },
         ),
+        (
+            "prefer-stubs",
+            {
+                "default": False,
+                "type": "yn",
+                "metavar": "<y or n>",
+                "help": "Resolve imports to .pyi stubs if available. May "
+                "reduce no-member messages and increase not-an-iterable "
+                "messages.",
+            },
+        ),
     )
 
 

pylint/lint/pylinter.py

@@ -1074,6 +1074,7 @@ def open(self) -> None:
         MANAGER.max_inferable_values = self.config.limit_inference_results
         MANAGER.extension_package_whitelist.update(self.config.extension_pkg_allow_list)
         MANAGER.module_denylist.update(self.config.ignored_modules)
+        MANAGER.prefer_stubs = self.config.prefer_stubs
         if self.config.extension_pkg_whitelist:
             MANAGER.extension_package_whitelist.update(
                 self.config.extension_pkg_whitelist

pylint/utils/utils.py

@@ -52,6 +52,7 @@
     "suggestion-mode",
     "analyse-fallback-blocks",
     "allow-global-unused-variables",
+    "prefer-stubs",
 ]
 GLOBAL_OPTION_INT = Literal["max-line-length", "docstring-min-length"]
 GLOBAL_OPTION_LIST = Literal["ignored-modules"]

tests/functional/i/iterable_context_without_stub.py

@@ -0,0 +1,5 @@
+"""If .pyi stubs are NOT preferred, no diagnostics emitted."""
+import more_itertools
+
+for val in more_itertools.chunked([1, 2, 3], n=1):
+    print(val)

tests/lint/test_pylinter.py

@@ -59,3 +59,12 @@ def test_open_pylinter_denied_modules(linter: PyLinter) -> None:
         assert MANAGER.module_denylist == {"mod1", "mod2", "mod3"}
     finally:
         MANAGER.module_denylist = set()
+
+
+def test_open_pylinter_prefer_stubs(linter: PyLinter) -> None:
+    try:
+        linter.config.prefer_stubs = True
+        linter.open()
+        assert MANAGER.prefer_stubs
+    finally:
+        MANAGER.prefer_stubs = False

tests/test_functional.py

@@ -51,6 +51,7 @@ def revert_stateful_config_changes(linter: PyLinter) -> Iterator[PyLinter]:
     yield linter
     # Revert any stateful configuration changes.
     MANAGER.brain["module_denylist"] = set()
+    MANAGER.brain["prefer_stubs"] = False
 
 
 @pytest.mark.usefixtures("revert_stateful_config_changes")