gh-120029: make symtable.Symbol.__repr__ correctly reflect the compiler's flags

Doc/library/symtable.rst

@@ -184,6 +184,25 @@ Examining Symbol Tables
       Return ``True`` if the symbol is referenced in its block, but not assigned
       to.
 
+   .. method:: is_free_class()
+
+      Return *True* if a symbol is free from a method perspective.
+
+      Consider the following example::
+
+         def f():
+             x = 1  # function-scoped
+                 class C:
+                     x = 2  # class-scoped
+                     def method(self):
+                         return x
+
+      In this example, the the class-scoped ``x`` symbol is considered
+      to be free from the perspective of ``C.method``, thereby allowing
+      the ``method`` to return *1* at runtime and not *2*.
+
+      .. versionadded:: 3.14
+
    .. method:: is_assigned()
 
       Return ``True`` if the symbol is assigned to in its block.

Lib/symtable.py

@@ -5,7 +5,7 @@
     USE,
     DEF_GLOBAL, DEF_NONLOCAL, DEF_LOCAL,
     DEF_PARAM, DEF_TYPE_PARAM,
-    DEF_FREE, DEF_FREE_CLASS,
+    DEF_FREE_CLASS,
     DEF_IMPORT, DEF_BOUND, DEF_ANNOT,
     DEF_COMP_ITER, DEF_COMP_CELL,
     SCOPE_OFF, SCOPE_MASK,
@@ -308,6 +308,10 @@ def is_free(self):
         """
         return bool(self.__scope == FREE)
 
+    def is_free_class(self):
+        """Return *True* if a symbol is free from a method perspective."""
+        return bool(self.__flags & DEF_FREE_CLASS)
+
     def is_imported(self):
         """Return *True* if the symbol is created from
         an import statement.

Lib/test/test_symtable.py

@@ -310,6 +310,18 @@ def test_symbol_repr(self):
         self.assertEqual(repr(st2.lookup("x")),
                          "<symbol 'x': CELL, DEF_LOCAL|DEF_COMP_ITER|DEF_COMP_CELL>")
 
+        st3 = symtable.symtable("def f():\n"
+                                "   x = 1\n"
+                                "   class A:\n"
+                                "       x = 2\n"
+                                "       def method():\n"
+                                "           return x\n",
+                                "?", "exec")
+        func_f = st3.get_children()[0]
+        class_A = func_f.get_children()[0]
+        self.assertEqual(repr(class_A.lookup('x')),
+                         "<symbol 'x': LOCAL, DEF_LOCAL|DEF_FREE_CLASS>")
+
     def test_symtable_entry_repr(self):
         expected = f"<symtable entry top({self.top.get_id()}), line {self.top.get_lineno()}>"
         self.assertEqual(repr(self.top._table), expected)

Misc/NEWS.d/next/Library/2024-06-05-11-03-10.gh-issue-120029.QBsw47.rst

@@ -1,4 +1,4 @@
-Expose :meth:`symtable.Symbol.is_comp_iter` and :meth:`symtable.Symbol.is_comp_cell`
-in the :mod:`symtable` module.
+Expose :meth:`symtable.Symbol.is_free_class`, :meth:`symtable.Symbol.is_comp_iter`
+and :meth:`symtable.Symbol.is_comp_cell` in the :mod:`symtable` module.
 Patch by Bénédikt Tran.