Merge branch 'main' into pseudo-protocols

Author: srittau

.flake8

@@ -30,4 +30,4 @@ max-complexity = 12
 noqa-require-code = true
 per-file-ignores =
   *.py: B905, B907, B950, E203, E501, W503, W291, W293
-  *.pyi: B, E301, E302, E305, E501, E701, E704, W503
+  *.pyi: B, E301, E302, E305, E501, E701, E704, F821, W503

.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
     hooks:
       - id: validate-pyproject
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.33.0
+    rev: 0.33.2
     hooks:
       - id: check-github-workflows
   - repo: https://github.com/rhysd/actionlint

CHANGELOG.md

@@ -2,7 +2,14 @@
 
 ## Unreleased
 
+* **Breaking change:** Previously, flake8-pyi monkey patched flake8's F821
+  (undefined name) check to avoid false positives in stub files. This monkey
+  patch has been removed. Instead, we now recommend to disable F821 when running flake8
+  on stub files.
+* Remove the now unnecessary `--no-pyi-aware-file-checker` option.
+
 New error codes:
+* Y068: Don't use `@override` in stub files.
 * Y092: Pseudo-protocols should not be used as argument types.
 
 ## 5.5.0

ERRORCODES.md

@@ -80,8 +80,8 @@ The following warnings are currently emitted by default:
 | <a id="Y064" href="#Y064">Y064</a> | Use simpler syntax to define final literal types. For example, use `x: Final = 42` instead of `x: Final[Literal[42]]`. | Style
 | <a id="Y065" href="#Y065">Y065</a> | Don't use bare `Incomplete` in argument and return annotations. Instead, leave them unannotated. Omitting an annotation entirely from a function will cause some type checkers to view the parameter or return type as "untyped"; this may result in stricter type-checking on code that makes use of the stubbed function. | Style
 | <a id="Y066" href="#Y066">Y066</a> | When using if/else with `sys.version_info`, put the code for new Python versions first. | Style
-| <a id="Y067" href="#Y067">Y067</a> | Don't use `Incomplete | None = None` in
-argument annotations. Instead, just use `=None`. | Style
+| <a id="Y067" href="#Y067">Y067</a> | Don't use `Incomplete \| None = None` in argument annotations. Instead, just use `=None`. | Style
+| <a id="Y068" href="#Y068">Y068</a> | Don't use `@override` in stub files. Problems with a function signature deviating from its superclass are inherited from the implementation, and other tools such as stubtest are better placed to recognize deviations between stubs and the implementation. | Understanding stubs
 
 ## Warnings disabled by default
 

flake8_pyi/checker.py

@@ -1,106 +1,18 @@
 from __future__ import annotations
 
-import argparse
 import ast
 import logging
 import re
 from dataclasses import dataclass
-from typing import Any, ClassVar, Iterator, Literal
+from typing import ClassVar, Iterator
 
-from flake8 import checker
 from flake8.options.manager import OptionManager
-from flake8.plugins.finder import LoadedPlugin
-from flake8.plugins.pyflakes import FlakesChecker
-from pyflakes.checker import ModuleScope
 
 from . import errors, visitor
 
 LOG = logging.getLogger("flake8.pyi")
 
 
-class PyflakesPreProcessor(ast.NodeTransformer):
-    """Transform AST prior to passing it to pyflakes.
-
-    This reduces false positives on recursive class definitions.
-    """
-
-    def visit_ClassDef(self, node: ast.ClassDef) -> ast.ClassDef:
-        self.generic_visit(node)
-        node.bases = [
-            # Remove the subscript to prevent F821 errors from being emitted
-            # for (valid) recursive definitions: Foo[Bar] --> Foo
-            base.value if isinstance(base, ast.Subscript) else base
-            for base in node.bases
-        ]
-        return node
-
-
-class PyiAwareFlakesChecker(FlakesChecker):
-    def __init__(self, tree: ast.AST, *args: Any, **kwargs: Any) -> None:
-        super().__init__(PyflakesPreProcessor().visit(tree), *args, **kwargs)
-
-    @property
-    def annotationsFutureEnabled(self) -> Literal[True]:
-        """Always allow forward references in `.pyi` files.
-
-        Pyflakes can already handle forward refs for annotations,
-        but only via `from __future__ import annotations`.
-        In a stub file, `from __future__ import annotations` is unnecessary,
-        so we pretend to pyflakes that it's always present when linting a `.pyi` file.
-        """
-        return True
-
-    @annotationsFutureEnabled.setter
-    def annotationsFutureEnabled(self, value: bool) -> None:
-        """Does nothing, as we always want this property to be `True`."""
-
-    def ASSIGN(
-        self, tree: ast.Assign, omit: str | tuple[str, ...] | None = None
-    ) -> None:
-        """Defer evaluation of assignments in the module scope.
-
-        This is a custom implementation of ASSIGN, originally derived from
-        handleChildren() in pyflakes 1.3.0.
-
-        This reduces false positives for:
-          - TypeVars bound or constrained to forward references
-          - Assignments to forward references that are not explicitly
-            demarcated as type aliases.
-        """
-        if not isinstance(self.scope, ModuleScope):
-            super().ASSIGN(tree)
-            return
-
-        for target in tree.targets:
-            self.handleNode(target, tree)
-
-        self.deferFunction(lambda: self.handleNode(tree.value, tree))
-
-    def handleNodeDelete(self, node: ast.AST) -> None:
-        """Null implementation.
-
-        Lets users use `del` in stubs to denote private names.
-        """
-        return
-
-
-class PyiAwareFileChecker(checker.FileChecker):
-    def run_check(self, plugin: LoadedPlugin, **kwargs: Any) -> Any:
-        if plugin.obj is FlakesChecker:
-            if self.filename == "-":
-                filename = self.options.stdin_display_name
-            else:
-                filename = self.filename
-
-            if filename.endswith(".pyi"):
-                LOG.info(
-                    f"Replacing FlakesChecker with PyiAwareFlakesChecker while "
-                    f"checking {filename!r}"
-                )
-                plugin = plugin._replace(obj=PyiAwareFlakesChecker)
-        return super().run_check(plugin, **kwargs)
-
-
 _TYPE_COMMENT_REGEX = re.compile(r"#\s*type:\s*(?!\s?ignore)([^#]+)(\s*#.*?)?$")
 
 
@@ -136,18 +48,5 @@ def run(self) -> Iterator[errors.Error]:
 
     @staticmethod
     def add_options(parser: OptionManager) -> None:
-        """This is brittle, there's multiple levels of caching of defaults."""
         parser.parser.set_defaults(filename="*.py,*.pyi")
         parser.extend_default_ignore(errors.DISABLED_BY_DEFAULT)
-        parser.add_option(
-            "--no-pyi-aware-file-checker",
-            default=False,
-            action="store_true",
-            parse_from_config=True,
-            help="don't patch flake8 with .pyi-aware file checker",
-        )
-
-    @staticmethod
-    def parse_options(options: argparse.Namespace) -> None:
-        if not options.no_pyi_aware_file_checker:
-            checker.FileChecker = PyiAwareFileChecker

flake8_pyi/errors.py

@@ -127,6 +127,8 @@ class Error(NamedTuple):
     'put the code for new Python versions first, e.g. "{new_syntax}"'
 )
 Y067 = 'Y067 Use "=None" instead of "Incomplete | None = None"'
+Y068 = 'Y068 Do not use "@override" in stub files.'
+
 Y090 = (
     'Y090 "{original}" means '
     '"a tuple of length 1, in which the sole element is of type {typ!r}". '

flake8_pyi/visitor.py

@@ -235,6 +235,7 @@ def _is_object(node: ast.AST | None, name: str, *, from_: Container[str]) -> boo
 )
 _is_Generic = partial(_is_object, name="Generic", from_=_TYPING_MODULES)
 _is_Unpack = partial(_is_object, name="Unpack", from_=_TYPING_MODULES)
+_is_override = partial(_is_object, name="override", from_=_TYPING_MODULES)
 
 
 def _is_union(node: ast.expr | None) -> TypeIs[ast.BinOp]:
@@ -2044,6 +2045,12 @@ def check_protocol_param_kinds(
                 pos_or_kw, errors.Y091.format(arg=pos_or_kw.arg, method=node.name)
             )
 
+    def check_for_override(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        for deco in node.decorator_list:
+            if _is_override(deco):
+                self.error(deco, errors.Y068)
+                return
+
     @staticmethod
     def _is_positional_pre_570_argname(name: str) -> bool:
         # https://peps.python.org/pep-0484/#positional-only-arguments
@@ -2106,6 +2113,7 @@ def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
             self.check_self_typevars(node, decorator_names)
             if self.enclosing_class_ctx.is_protocol_class:
                 self.check_protocol_param_kinds(node, decorator_names)
+            self.check_for_override(node)
 
     def visit_arg(self, node: ast.arg) -> None:
         if _is_NoReturn(node.annotation):

tests/forward_refs.pyi

@@ -0,0 +1,24 @@
+import typing
+import typing as t
+from typing import override, override as over
+
+import typing_extensions
+
+class Foo:
+    def f(self) -> None: ...
+    def g(self) -> None: ...
+    def h(self) -> None: ...
+    def j(self) -> None: ...
+    def k(self) -> None: ...
+
+class Bar(Foo):
+    @override  # Y068 Do not use "@override" in stub files.
+    def f(self) -> None: ...
+    @typing.override  # Y068 Do not use "@override" in stub files.
+    def g(self) -> None: ...
+    @t.override  # Ideally we'd catch this too, but the infrastructure is not in place.
+    def h(self) -> None: ...
+    @over  # Ideally we'd catch this too, but the infrastructure is not in place.
+    def j(self) -> None: ...
+    @typing_extensions.override  # Y068 Do not use "@override" in stub files.
+    def k(self) -> None: ...