[pyflakes] suppress false positive in F821 for names used before del in stub files (#23550)

stakeswky · amyreese · web-flow · commit 81d655fadce0 · 2026-02-26T18:41:05.000Z
Co-authored-by: stakeswky &lt;stakeswky@users.noreply.github.com&gt;
Co-authored-by: Amethyst Reese &lt;amethyst@n7.gg&gt;
diff --git a/crates/ruff_linter/resources/test/fixtures/pyflakes/F821_34.pyi b/crates/ruff_linter/resources/test/fixtures/pyflakes/F821_34.pyi
@@ -0,0 +1,22 @@
+# OK: `del` after use in stub file should not trigger F821
+class MyClass: ...
+def f(cls: MyClass) -> None: ...
+del MyClass
+
+# OK: same pattern with a variable
+_T = int
+x: _T
+del _T
+
+# OK: used in base class
+class Base: ...
+class Child(Base): ...
+del Base
+
+# Error: `del` before use should still trigger F821
+class EarlyDel: ...
+del EarlyDel
+def f2(cls: EarlyDel) -> None: ...  # F821
+
+# Error: name that was never defined
+def g(x: Undefined) -> None: ...  # F821
diff --git a/crates/ruff_linter/src/rules/pyflakes/mod.rs b/crates/ruff_linter/src/rules/pyflakes/mod.rs
@@ -168,6 +168,7 @@ mod tests {
     #[test_case(Rule::UndefinedName, Path::new("F821_31.py"))]
     #[test_case(Rule::UndefinedName, Path::new("F821_32.pyi"))]
     #[test_case(Rule::UndefinedName, Path::new("F821_33.py"))]
+    #[test_case(Rule::UndefinedName, Path::new("F821_34.pyi"))]
     #[test_case(Rule::UndefinedExport, Path::new("F822_0.py"))]
     #[test_case(Rule::UndefinedExport, Path::new("F822_0.pyi"))]
     #[test_case(Rule::UndefinedExport, Path::new("F822_1.py"))]
diff --git a/crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__F821_F821_34.pyi.snap b/crates/ruff_linter/src/rules/pyflakes/snapshots/ruff_linter__rules__pyflakes__tests__F821_F821_34.pyi.snap
@@ -0,0 +1,21 @@
+---
+source: crates/ruff_linter/src/rules/pyflakes/mod.rs
+---
+F821 Undefined name `EarlyDel`
+  --> F821_34.pyi:19:13
+   |
+17 | class EarlyDel: ...
+18 | del EarlyDel
+19 | def f2(cls: EarlyDel) -> None: ...  # F821
+   |             ^^^^^^^^
+20 |
+21 | # Error: name that was never defined
+   |
+
+F821 Undefined name `Undefined`
+  --> F821_34.pyi:22:10
+   |
+21 | # Error: name that was never defined
+22 | def g(x: Undefined) -> None: ...  # F821
+   |          ^^^^^^^^^
+   |
diff --git a/crates/ruff_python_semantic/src/model.rs b/crates/ruff_python_semantic/src/model.rs
@@ -502,7 +502,48 @@ impl<'a> SemanticModel<'a> {
                     // print(x)
                     //
                     // The `x` in `print(x)` should be treated as unresolved.
-                    BindingKind::Deletion | BindingKind::UnboundException(None) => {
+                    BindingKind::Deletion => {
+                        // In stub files, `del` is used to hide names from re-export
+                        // while the name is still valid for use in type annotations
+                        // within the same file. Since annotations are deferred in
+                        // stubs, the `Deletion` binding is seen at resolve time even
+                        // though the reference textually precedes the `del`. Resolve
+                        // to the shadowed (pre-`del`) binding when available.
+                        if self.in_stub_file() {
+                            if let Some(shadowed_id) =
+                                self.scopes[scope_id].shadowed_binding(binding_id)
+                            {
+                                // Only suppress F821 when the reference textually precedes
+                                // the `del` statement. If `del` comes before the reference,
+                                // the name is genuinely undefined at that point and F821
+                                // should still fire.
+                                let deletion_range = self.bindings[binding_id].range;
+                                if !self.bindings[shadowed_id].is_unbound()
+                                    && name.range.start() < deletion_range.start()
+                                {
+                                    let reference_id = self.resolved_references.push(
+                                        self.scope_id,
+                                        self.node_id,
+                                        ExprContext::Load,
+                                        self.flags,
+                                        name.range,
+                                    );
+                                    self.bindings[shadowed_id].references.push(reference_id);
+                                    self.resolved_names.insert(name.into(), shadowed_id);
+                                    return ReadResult::Resolved(shadowed_id);
+                                }
+                            }
+                        }
+
+                        self.unresolved_references.push(
+                            name.range,
+                            self.exceptions(),
+                            UnresolvedReferenceFlags::empty(),
+                        );
+                        return ReadResult::UnboundLocal(binding_id);
+                    }
+
+                    BindingKind::UnboundException(None) => {
                         self.unresolved_references.push(
                             name.range,
                             self.exceptions(),
