library symtable.SymbolTable.is_nested() description differs from Cpython implementation.

The documentation says

is_nested()
Return True if the block is a nested class or function.

The cpython implementation of symtable.c sets the corresponding flag only if the block is nested somewhere inside a function. This would include, for example, a scope inside a class inside a function.

Thus

def f():    # false
  def g():    # true
    def h():    # true
    class C:    # true
  class B:    # true
    def h():    # true
    class C:    # true
class A:    # false
  def g():    # false !!
    def h():    # true
    class C:    # true
  class B:    # false !!
    def h():    # false !!
    class C:    # false !!

The value is the same as the CO_NESTED bit in the code object's co_flags member.
The flag is also documented (similarly incorrectly) in the inspect module documentation.

I would recommend deprecating this feature. The documentation for co_flags says that

bits 0x10 and 0x1000 were used in earlier versions of Python.

0x10 is the CO_NESTED bit. I would guess that nobody uses CO_NESTED or SymbolTable.is_nested().

Alternatives:

• Change the behavior in Cpython to agree with the documentation. A class nested in another scope should also have CO_NESTED set. Make a test case for the compiler, to ensure that other implementations follow the same definition.
• Correct the documentation for symtable and inspect modules. Possibly also deprecate the feature.

Linked PRs

• gh-151901

Review linked PR gh-151901 first, then compare the symtable and inspect documentation with the stated CPython behavior and the CO_NESTED flag. The issue leaves the resolution open: either align implementation and add compiler tests, or correct the documentation and possibly deprecate the feature.