gh-99350: Fix symtable.SymbolTable.is_nested() documentation

The docstring and library reference described is_nested() as returning True
for 'a nested class or function', which wrongly implies any nesting. The
underlying flag is only set when the block is nested within a function, so a
method of a top-level class is not nested. Reword both descriptions and add a
characterizing assertion to test_nested.

Author: iamsharduld

Doc/library/symtable.rst

@@ -125,7 +125,10 @@ Examining Symbol Tables
 
    .. method:: is_nested()
 
-      Return ``True`` if the block is a nested class or function.
+      Return ``True`` if the block is a function or class nested, directly or
+      indirectly, within a function.  A block defined at module level, or
+      nested only within classes (and not within any function), is not
+      considered nested.
 
    .. method:: has_children()
 

Lib/symtable.py

@@ -126,8 +126,12 @@ def is_optimized(self):
         return bool(self._table.type == _symtable.TYPE_FUNCTION)
 
     def is_nested(self):
-        """Return *True* if the block is a nested class
-        or function."""
+        """Return *True* if the block is a function or class nested,
+        directly or indirectly, within a function.
+
+        A block defined at module level, or nested only within classes
+        (and not within any function), is not considered nested.
+        """
         return bool(self._table.nested)
 
     def has_children(self):

Lib/test/test_symtable.py

@@ -234,6 +234,10 @@ def test_optimized(self):
     def test_nested(self):
         self.assertFalse(self.top.is_nested())
         self.assertFalse(self.Mine.is_nested())
+        # gh-99350: a method of a top-level class is not nested, because
+        # is_nested() reflects being enclosed by a function, not merely
+        # being nested inside some other block.
+        self.assertFalse(self.a_method.is_nested())
         self.assertFalse(self.spam.is_nested())
         self.assertTrue(self.internal.is_nested())
 

Misc/NEWS.d/next/Documentation/2026-06-22-16-30-00.gh-issue-99350.Wd2rPq.rst

@@ -0,0 +1,3 @@
+Clarify that :meth:`symtable.SymbolTable.is_nested` returns ``True`` only when
+the block is nested (directly or indirectly) within a function, and not when it
+is nested merely within another block such as a class.