gh-160948: Only an explicitly passed locals takes precedence over the closure cell

Author: arpittkhandelwal

Lib/annotationlib.py

@@ -128,9 +128,10 @@ def evaluate(
             and isinstance(self.__cell__, types.CellType)
         ):
             # The cell holds the value of the name from the enclosing scope.
-            # Explicitly passed namespaces take precedence over it, so use
-            # this shortcut only if neither was provided; otherwise, the
-            # cell value is used as a fallback during name resolution below.
+            # Take this shortcut only if no namespaces were provided;
+            # otherwise, the resolution below gives an explicitly passed
+            # locals precedence over the cell, and the cell precedence
+            # over globals.
             try:
                 return self.__cell__.cell_contents
             except ValueError:
@@ -202,16 +203,18 @@ def evaluate(
             resolved = _sentinel
             if arg in locals:
                 resolved = locals[arg]
-            elif arg in globals:
-                resolved = globals[arg]
             elif isinstance(self.__cell__, types.CellType):
-                # Fall back to the value from the enclosing scope if the
-                # name is not in either of the provided namespaces.
+                # The cell holds the value of the name from the enclosing
+                # scope. Like the dict-of-cells path above, which merges
+                # cells into locals with setdefault, it takes precedence
+                # over globals, but not over locals.
                 try:
                     resolved = self.__cell__.cell_contents
                 except ValueError:
                     pass
-            if resolved is _sentinel and hasattr(builtins, arg):
+            if resolved is _sentinel and arg in globals:
+                resolved = globals[arg]
+            elif resolved is _sentinel and hasattr(builtins, arg):
                 resolved = getattr(builtins, arg)
 
             if resolved is not _sentinel:

Lib/test/test_annotationlib.py

@@ -2537,13 +2537,20 @@ def inner(arg: x):
         # With no explicit namespaces, the value from the enclosing
         # scope, held in the cell, is used.
         self.assertEqual(fwdref.evaluate(), 1)
-        # Explicitly passed namespaces take precedence over the cell.
+        # An explicitly passed locals takes precedence over the cell,
+        # but globals does not: the cell holds a nonlocal binding, which
+        # sits between locals and globals in the lookup order (as in
+        # the dict-of-cells path, where the cells are merged into the
+        # locals with setdefault).
         self.assertEqual(fwdref.evaluate(locals={"x": 2}), 2)
-        self.assertEqual(fwdref.evaluate(globals={"x": 3}), 3)
+        self.assertEqual(fwdref.evaluate(globals={"x": 3}), 1)
         self.assertEqual(fwdref.evaluate(globals={"x": 3}, locals={"x": 2}), 2)
         self.assertEqual(
             fwdref.evaluate(locals={"x": 2}, format=Format.FORWARDREF), 2
         )
+        self.assertEqual(
+            fwdref.evaluate(globals={"x": 3}, format=Format.FORWARDREF), 1
+        )
         # If the name is not in the explicit namespaces, the cell
         # value is used as a fallback.
         self.assertEqual(fwdref.evaluate(locals={}), 1)
@@ -2568,11 +2575,12 @@ def inner(arg: x):
         self.assertEqual(fwdref.evaluate(locals={"x": 2}), 2)
         self.assertEqual(fwdref.evaluate(globals={"x": 3}), 3)
 
-        # Refilling the cell restores it as the fallback, but explicit
-        # namespaces still take precedence over it.
+        # Refilling the cell restores it: an explicitly passed locals
+        # still takes precedence over it, but globals does not.
         x = 7
         self.assertEqual(fwdref.evaluate(), 7)
         self.assertEqual(fwdref.evaluate(locals={"x": 2}), 2)
+        self.assertEqual(fwdref.evaluate(globals={"x": 3}), 7)
 
     def test_fwdref_final_class(self):
         with self.assertRaises(TypeError):

Misc/NEWS.d/next/Library/2026-10-30-10-03-32.gh-issue-160948.k9Wd3s.rst

@@ -1,4 +1,5 @@
-Fixed :meth:`annotationlib.ForwardRef.evaluate` silently ignoring
-explicitly passed *globals* and *locals* when the reference holds a
-single closure cell. Explicit namespaces now take precedence, as on the
-other resolution paths, and the cell value is used as a fallback.
+Fixed :meth:`annotationlib.ForwardRef.evaluate` silently ignoring an
+explicitly passed *locals* when the reference holds a single closure
+cell. An explicit *locals* now takes precedence over the cell, as on
+the other resolution paths; the cell still takes precedence over
+*globals*, since it holds a nonlocal binding.