mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-27 13:45:25 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

gh-74929: locals() documentation update for PEP 667 (#118265)

Browse source 
Documentation wording taken from the
withdrawn PEP 558 (which had switched to the
Python level semantics proposed in PEP 667 prior
to its withdrawal).
This commit is contained in:
Alyssa Coghlan 2024-05-06 20:06:07 +10:00 • committed by GitHub
parent 8e750b83a8
commit 757fd3e010
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 38 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

47
Doc/library/functions.rst
View file

@ -636,8 +636,7 @@ are always available. They are listed here in alphabetical order.
.. note:: .. note::
The default *locals* act as described for function :func:`locals` below: The default *locals* act as described for function :func:`locals` below.
modifications to the default *locals* dictionary should not be attempted.
Pass an explicit *locals* dictionary if you need to see effects of the Pass an explicit *locals* dictionary if you need to see effects of the
code on *locals* after function :func:`exec` returns. code on *locals* after function :func:`exec` returns.
@ -1049,14 +1048,44 @@ are always available. They are listed here in alphabetical order.
.. function:: locals() .. function:: locals()
Update and return a dictionary representing the current local symbol table. Return a mapping object representing the current local symbol table, with
Free variables are returned by :func:`locals` when it is called in function variable names as the keys, and their currently bound references as the
blocks, but not in class blocks. Note that at the module level, :func:`locals` values.
and :func:`globals` are the same dictionary.
At module scope, as well as when using ``exec()`` or ``eval()`` with a
single namespace, this function returns the same namespace as ``globals()``.
At class scope, it returns the namespace that will be passed to the
metaclass constructor.
When using ``exec()`` or ``eval()`` with separate local and global
namespaces, it returns the local namespace passed in to the function call.
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 bound,
rebound, or deleted local variables, and binding, rebinding, or deleting
local variables will immediately affect the contents of the returned mapping
object.
At function scope (including for 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 binding, rebinding, or deleting local variables and nonlocal
cell references does *not* affect the contents of previously returned
dictionaries.
.. versionchanged:: 3.13
In previous versions, the semantics of mutating the mapping object
returned from this function were formally undefined. In CPython
specifically, the mapping returned at function scope could be
implicitly refreshed by other operations, such as calling ``locals()``
again. Obtaining the legacy CPython behaviour now requires explicit
calls to update the initially returned dictionary with the results
of subsequent calls to ``locals()``.
.. note::
The contents of this dictionary should not be modified; changes may not
affect the values of local and free variables used by the interpreter.
.. function:: map(function, iterable, *iterables) .. function:: map(function, iterable, *iterables)