gh-151321: Fix opcode metadata flags for LOAD_DEREF and LOAD_CLOSURE

LOAD_DEREF and LOAD_CLOSURE were missing HAS_FREE_FLAG in the generated
opcode metadata, and both also carried HAS_LOCAL_FLAG, so dis.hasfree no
longer reported them while dis.haslocal wrongly included them. This
regressed the documented dis.hasfree / dis.haslocal contract: LOAD_CLOSURE
broke in 3.13 (when it became a pseudo-op inheriting LOAD_FAST's flags) and
LOAD_DEREF broke in 3.14 (when it started using _PyCell_GetStackRef, which
the cases generator's has_free heuristic did not recognize).

Teach the cases generator to treat _PyCell_GetStackRef as a free-variable
access, and give the LOAD_CLOSURE pseudo an explicit HAS_FREE flag. A pseudo
that explicitly accesses a free variable now suppresses the inherited
HAS_LOCAL, mirroring the existing "uses_locals and not has_free" rule for
real instructions, so HAS_FREE and HAS_LOCAL are never both set. The change
is to introspection metadata only; the generated interpreter and optimizer
code are unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: harjothkhara

Include/internal/pycore_opcode_metadata.h

@@ -61,6 +61,23 @@ def check_function(self, func, expected):
         check_function(self, _opcode.has_local, dis.haslocal)
         check_function(self, _opcode.has_exc, dis.hasexc)
 
+    def test_hasfree_membership(self):
+        # gh-151321: opcodes that access a free (closure) variable must be
+        # reported by dis.hasfree and not by dis.haslocal.
+        free_ops = {
+            'DELETE_DEREF',
+            'LOAD_CLOSURE',
+            'LOAD_DEREF',
+            'LOAD_FROM_DICT_OR_DEREF',
+            'MAKE_CELL',
+            'STORE_DEREF',
+        }
+        self.assertEqual(free_ops, {dis.opname[op] for op in dis.hasfree})
+        self.assertNotIn(dis.opmap['LOAD_DEREF'], dis.haslocal)
+        self.assertNotIn(dis.opmap['LOAD_CLOSURE'], dis.haslocal)
+        # A free-variable access is never also a local access.
+        self.assertEqual(set(), set(dis.hasfree) & set(dis.haslocal))
+
 
 class StackEffectTests(unittest.TestCase):
     def test_stack_effect(self):

Include/internal/pycore_uop_metadata.h

@@ -0,0 +1,3 @@
+Fix the opcode metadata flags for :opcode:`LOAD_DEREF` and :opcode:`LOAD_CLOSURE`
+so that they are reported by :data:`dis.hasfree` again, and are no longer
+incorrectly reported by :data:`dis.haslocal`.

Lib/test/test__opcode.py

@@ -264,7 +264,7 @@ dummy_func(
             _CHECK_PERIODIC_IF_NOT_YIELD_FROM +
             _MONITOR_RESUME;
 
-        pseudo(LOAD_CLOSURE, (-- unused)) = {
+        pseudo(LOAD_CLOSURE, (-- unused), (HAS_FREE)) = {
             LOAD_FAST,
         };
 

Misc/NEWS.d/next/Core_and_Builtins/2026-06-11-15-17-09.gh-issue-151321.Kf3Lp9.rst

@@ -313,7 +313,15 @@ def dump(self, indent: str) -> None:
 
     @property
     def properties(self) -> Properties:
-        return Properties.from_list([i.properties for i in self.targets])
+        properties = Properties.from_list([i.properties for i in self.targets])
+        if "HAS_FREE" in self.flags:
+            # A pseudo that explicitly accesses a free (closure) variable is
+            # not a local access, even though it may target a local-accessing
+            # instruction such as LOAD_FAST.  This mirrors the
+            # ``uses_locals and not has_free`` rule for real instructions so
+            # that HAS_FREE and HAS_LOCAL are not both set (gh-151321).
+            properties.uses_locals = False
+        return properties
 
 
 @dataclass
@@ -970,6 +978,7 @@ def compute_properties(op: parser.CodeDef) -> Properties:
         or variable_used(op, "PyCell_GetRef")
         or variable_used(op, "PyCell_SetTakeRef")
         or variable_used(op, "PyCell_SwapTakeRef")
+        or variable_used(op, "_PyCell_GetStackRef")
     )
     deopts_if = variable_used(op, "DEOPT_IF")
     exits_if = variable_used(op, "EXIT_IF")