Doc string for locals() partly contradicts the full documentation

[uwu-crj]

locals() documentation

>>> print(locals.__doc__)
Return a dictionary containing the current scope's local variables.

NOTE: Whether or not updates to this dictionary will affect name lookups in
the local scope and vice-versa is *implementation dependent* and not
covered by any backwards compatibility guarantees.

But in the docs:

At module scope, as well as when using exec() or eval() with a single namespace [...]

At class scope [...]

When using exec() or eval() with separate local and global arguments [...]

In all of the above cases, each call to locals() in a given frame of execution will return the same mapping object. Changes made through the mapping object returned from locals() will be visible as assigned, reassigned, or deleted local variables, and assigning, reassigning, or deleting local variables will immediately affect the contents of the returned mapping object.

In an optimized scope (including functions, generators, and coroutines), each call to locals() instead returns a fresh dictionary containing the current bindings of the function’s local variables and any nonlocal cell references. In this case, name binding changes made via the returned dict are not written back to the corresponding local variables or nonlocal cell references, and assigning, reassigning, or deleting local variables and nonlocal cell references does not affect the contents of previously returned dictionaries.

So either:

• Behaviour is undefined and the full documentation fails to mention this in giving a complete description of it
• The behaviour given in the full documentation is stable and can be relied upon, in which case the doc string is misleading

It feels like at least one of the two should be corrected/clarified.

Linked PRs

• gh-126170: Update and clarify locals() docstring #127225

[rimi0108]

@corona10