Doc string for locals() partly contradicts the full documentation

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-127225

首先查看 locals() 的 docstring 输出和链接的 PR gh-127225，然后将其与文档中 locals() 条目的描述进行比较。确定哪种措辞能够准确涵盖列出的作用域情况。完成的标准是 docstring 与完整文档不再相互矛盾。