Fix used-before-assignment false positive for names shadowed by a later method (#11493)

Signed-off-by: Gaurav Jadhav <gaurav.vjadhav01@gmail.com>
Co-authored-by: Pierre Sassoulas <pierre.sassoulas@gmail.com>

Author: jadhavgaurav

doc/whatsnew/fragments/9134.false_positive

@@ -0,0 +1,3 @@
+Fix a false positive for ``used-before-assignment`` when a class body uses a module-level or builtin name that a method or nested class defined later in the same class body shadows.
+
+Closes #9134

pylint/checkers/variables.py

@@ -128,6 +128,56 @@ def _get_unpacking_extra_info(node: nodes.Assign, inferred: InferenceResult) ->
     return more
 
 
+def _is_bound_before_class(
+    class_node: nodes.ClassDef,
+    lookup_scope: nodes.LocalsDictNodeNG,
+    bindings: list[nodes.NodeNG],
+) -> bool:
+    """Whether a module-level or builtin binding exists when the class body runs."""
+    if not bindings:
+        return False
+    if lookup_scope is not class_node.root():
+        return True
+    if any(
+        isinstance(ancestor, (nodes.FunctionDef, nodes.Lambda))
+        for ancestor in class_node.node_ancestors()
+    ):
+        # The class body runs when the function is called, which can be after
+        # the module-level binding.
+        return True
+    return any(
+        binding.lineno is not None and binding.lineno < class_node.lineno
+        for binding in bindings
+    )
+
+
+def _is_def_in_class_body(
+    defstmt: _base_nodes.Statement, frame: nodes.LocalsDictNodeNG
+) -> bool:
+    """Whether ``defstmt`` is a def or class statement directly in the class body frame.
+
+    Such a statement is its own frame, but it binds its name in the class body.
+    """
+    return (
+        isinstance(defstmt, (nodes.FunctionDef, nodes.ClassDef))
+        and isinstance(frame, nodes.ClassDef)
+        and defstmt.parent.frame() is frame
+    )
+
+
+def _has_outer_binding(
+    name: str, defframe: nodes.LocalsDictNodeNG, class_node: nodes.ClassDef | None
+) -> bool:
+    """Whether name has a module-level or builtin binding.
+
+    When class_node is given, the binding must also exist when its body runs.
+    """
+    lookup_scope, bindings = defframe.root().lookup(name)
+    if class_node is None:
+        return bool(bindings)
+    return _is_bound_before_class(class_node, lookup_scope, bindings)
+
+
 def _detect_global_scope(
     node: nodes.Name,
     frame: nodes.LocalsDictNodeNG,
@@ -2374,6 +2424,9 @@ def _is_variable_violation(
         maybe_before_assign = True
         annotation_return = False
         use_outer_definition = False
+        def_in_class_body = _is_def_in_class_body(defstmt, frame)
+        if def_in_class_body:
+            defframe = frame
         if frame is not defframe:
             maybe_before_assign = _detect_global_scope(node, frame, defframe)
         elif defframe.parent is None:
@@ -2394,7 +2447,9 @@ def _is_variable_violation(
                 isinstance(frame, nodes.FunctionDef)
                 or isinstance(node.frame(), nodes.Lambda)
             ) and _assigned_locally(node)
-            if not forbid_lookup and defframe.root().lookup(node.name)[1]:
+            if not forbid_lookup and _has_outer_binding(
+                node.name, defframe, frame if def_in_class_body else None
+            ):
                 maybe_before_assign = False
                 use_outer_definition = stmt == defstmt and not isinstance(
                     defnode, nodes.Comprehension

tests/functional/u/used/used_before_assignment_class_scope_def.py

@@ -0,0 +1,150 @@
+"""A class body may use a module-level or builtin name that a later method shadows.
+
+Names in a class body are looked up in the class namespace first and then in the
+globals and builtins. A ``def`` or ``class`` further down the class body has not
+run yet, so it does not shadow the outer name at that point.
+
+https://github.com/pylint-dev/pylint/issues/9134
+"""
+# pylint: disable=missing-class-docstring,missing-function-docstring
+# pylint: disable=too-few-public-methods,invalid-name,unused-argument
+import operator
+from datetime import timezone
+from functools import cached_property
+from os import path
+from string import Template
+
+
+class ModuleNameShadowedByMethod:
+    joined = path.join("a", "b")
+
+    def path(self):
+        return self
+
+
+class ModuleNameShadowedByNestedClass:
+    joined = path.join("a", "b")
+
+    class path:
+        pass
+
+
+class ModuleNameShadowedByAsyncMethod:
+    joined = path.join("a", "b")
+
+    async def path(self):
+        return self
+
+
+class ModuleClassShadowedByMethod:
+    template = Template("$a")
+
+    def Template(self):
+        return self
+
+
+class ModuleNameUsedInDecorator:
+    @staticmethod
+    def make(arg=path.join("a")):
+        return arg
+
+    def path(self):
+        return self
+
+
+class BuiltinShadowedByMethod:
+    length = len("abc")
+
+    def len(self):
+        return self
+
+
+class ModuleNameShadowedByProperty:
+    equals = operator.eq
+
+    @property
+    def operator(self):
+        return self.equals
+
+
+class ModuleNameShadowedByCachedProperty:
+    default = timezone.utc
+
+    @cached_property
+    def timezone(self):
+        return self.default
+
+
+class NameOnlyDefinedByLaterMethod:
+    joined = missing.join("a")  # [used-before-assignment]
+
+    def missing(self):
+        return self
+
+
+class NameUsedInsideMethodBody:
+    def method(self):
+        return path.join("a"), Template("$a"), operator.eq, timezone.utc
+
+    def path(self):
+        return self
+
+
+class NameUsedAfterMethod:
+    def path(self):
+        return self
+
+    joined = path(None)
+
+
+class ModuleNameDefinedAfterClass:
+    value = defined_later(1)  # [used-before-assignment]
+
+    def defined_later(self):
+        return self
+
+
+defined_later = len
+
+
+class ModuleNameDefinedAfterClassByAssignment:
+    # Known false negative, the same as for any other assignment in a class body.
+    value = assigned_later(1)
+
+    assigned_later = 2
+
+
+assigned_later = len
+
+
+def enclosing_function():
+    from os import sep  # pylint: disable=import-outside-toplevel,unused-import
+
+    class Inner:
+        joined = sep.join("a")  # [used-before-assignment]
+
+        def sep(self):
+            return self
+
+    return Inner
+
+
+def late_bound_module_name():
+    class A:
+        x = later([1])
+
+        def later(self): ...
+
+    return A
+
+
+later = len
+late_bound_module_name()
+
+
+class OuterClass:
+    class NestedClass:
+        joined = path.join("a", "b")
+
+        def path(self):
+            return self

tests/functional/u/used/used_before_assignment_class_scope_def.txt

@@ -0,0 +1,3 @@
+used-before-assignment:79:13:79:20:NameOnlyDefinedByLaterMethod:Using variable 'missing' before assignment:HIGH
+used-before-assignment:101:12:101:25:ModuleNameDefinedAfterClass:Using variable 'defined_later' before assignment:HIGH
+used-before-assignment:124:17:124:20:enclosing_function.Inner:Using variable 'sep' before assignment:HIGH