mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-02 03:01:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 15

gh-74929: PEP 667 general docs update (gh-119201)

Browse source 
* expand on What's New entry for PEP 667 (including porting notes)
* define 'optimized scope' as a glossary term
* cover comprehensions and generator expressions in locals() docs
* review all mentions of "locals" in documentation (updating if needed)
* review all mentions of "f_locals" in documentation (updating if needed)
This commit is contained in:
Alyssa Coghlan 2024-05-21 13:32:15 +10:00 • committed by GitHub
parent 538ed5e481
commit e870c852c0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 162 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

101
Doc/library/functions.rst
View file

@ -543,18 +543,19 @@ are always available. They are listed here in alphabetical order.
The *expression* argument is parsed and evaluated as a Python expression
(technically speaking, a condition list) using the *globals* and *locals*
dictionaries as global and local namespace. If the *globals* dictionary is
mappings as global and local namespace. If the *globals* dictionary is
present and does not contain a value for the key ``__builtins__``, a
reference to the dictionary of the built-in module :mod:`builtins` is
inserted under that key before *expression* is parsed. That way you can
control what builtins are available to the executed code by inserting your
own ``__builtins__`` dictionary into *globals* before passing it to
:func:`eval`. If the *locals* dictionary is omitted it defaults to the
*globals* dictionary. If both dictionaries are omitted, the expression is
:func:`eval`. If the *locals* mapping is omitted it defaults to the
*globals* dictionary. If both mappings are omitted, the expression is
executed with the *globals* and *locals* in the environment where
:func:`eval` is called. Note, *eval()* does not have access to the
:func:`eval` is called. Note, *eval()* will only have access to the
:term:`nested scopes <nested scope>` (non-locals) in the enclosing
environment.
environment if they are already referenced in the scope that is calling
:func:`eval` (e.g. via a :keyword:`nonlocal` statement).
Example:
@ -587,6 +588,11 @@ are always available. They are listed here in alphabetical order.
The *globals* and *locals* arguments can now be passed as keywords.
.. versionchanged:: 3.13
The semantics of the default *locals* namespace have been adjusted as
described for the :func:`locals` builtin.
.. index:: pair: built-in function; exec
.. function:: exec(source, /, globals=None, locals=None, *, closure=None)
@ -612,9 +618,15 @@ are always available. They are listed here in alphabetical order.
.. note::
Most users should just pass a *globals* argument and never *locals*.
If exec gets two separate objects as *globals* and *locals*, the code
will be executed as if it were embedded in a class definition.
When ``exec`` gets two separate objects as *globals* and *locals*, the
code will be executed as if it were embedded in a class definition. This
means functions and classes defined in the executed code will not be able
to access variables assigned at the top level (as the "top level"
variables are treated as class variables in a class definition).
Passing a :class:`collections.ChainMap` instance as *globals* allows name
lookups to be chained across multiple mappings without triggering this
behaviour. Values assigned to top level names in the executed code can be
retrieved by passing an empty dictionary as the first entry in the chain.
If the *globals* dictionary does not contain a value for the key
``__builtins__``, a reference to the dictionary of the built-in module
@ -635,7 +647,7 @@ are always available. They are listed here in alphabetical order.
.. note::
The built-in functions :func:`globals` and :func:`locals` return the current
global and local dictionary, respectively, which may be useful to pass around
global and local namespace, respectively, which may be useful to pass around
for use as the second and third argument to :func:`exec`.
.. note::
@ -651,6 +663,11 @@ are always available. They are listed here in alphabetical order.
The *globals* and *locals* arguments can now be passed as keywords.
.. versionchanged:: 3.13
The semantics of the default *locals* namespace have been adjusted as
described for the :func:`locals` builtin.
.. function:: filter(function, iterable)
@ -1056,39 +1073,51 @@ are always available. They are listed here in alphabetical order.
variable names as the keys, and their currently bound references as the
values.
At module scope, as well as when using ``exec()`` or ``eval()`` with a
single namespace, this function returns the same namespace as ``globals()``.
At module scope, as well as when using :func:`exec` or :func:`eval` with
a single namespace, this function returns the same namespace as
:func:`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.
arguments, 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.
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.
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.
In an :term:`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.
Calling ``locals()`` as part of a comprehension in a function, generator, or
coroutine is equivalent to calling it in the containing scope, except that
the comprehension's initialised iteration variables will be included. In
other scopes, it behaves as if the comprehension were running as a nested
function.
Calling ``locals()`` as part of a generator expression is equivalent to
calling it in a nested generator function.
.. versionchanged:: 3.12
The behaviour of ``locals()`` in a comprehension has been updated as
described in :pep:`709`.
.. 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()``.
As part of :pep:`667`, the semantics of mutating the mapping objects
returned from this function are now defined. The behavior in
:term:`optimized scopes <optimized scope>` is now as described above.
Aside from being defined, the behaviour in other scopes remains
unchanged from previous versions.
.. function:: map(function, iterable, *iterables)
@ -1975,14 +2004,18 @@ are always available. They are listed here in alphabetical order.
:attr:`~object.__dict__` attributes (for example, classes use a
:class:`types.MappingProxyType` to prevent direct dictionary updates).
Without an argument, :func:`vars` acts like :func:`locals`. Note, the
locals dictionary is only useful for reads since updates to the locals
dictionary are ignored.
Without an argument, :func:`vars` acts like :func:`locals`.
A :exc:`TypeError` exception is raised if an object is specified but
it doesn't have a :attr:`~object.__dict__` attribute (for example, if
its class defines the :attr:`~object.__slots__` attribute).
.. versionchanged:: 3.13
The result of calling this function without an argument has been
updated as described for the :func:`locals` builtin.
.. function:: zip(*iterables, strict=False)
Iterate over several iterables in parallel, producing tuples with an item