mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 10:19:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

gh-118934: Fix PyEval_GetLocals docs (PEP 667) (#119932)

Browse source 
PEP 667's description of the planned changes to PyEval_GetLocals
was internally inconsistent when accepted, so the docs added for
gh-74929 didn't match either the current behaviour or the intended
behaviour once gh-118934 is fixed.

This PR updates the documentation and 3.13 What's New to match the
intended behaviour (once gh-118934 is fixed).

It also tidies up lingering references to `f_locals` always being a
dictionary (this hasn't been true since at least when custom
namespace support for class statement execution was added)
This commit is contained in:
Alyssa Coghlan 2024-06-02 14:44:29 +10:00 • committed by GitHub
parent e378dc15b5
commit fd6cd621e0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 46 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

27
Doc/c-api/reflection.rst
View file

@ -19,23 +19,28 @@ Reflection
.. deprecated:: 3.13
To avoid creating a reference cycle in :term:`optimized scopes <optimized scope>`,
use either :c:func:`PyEval_GetFrameLocals` to obtain the same behaviour as calling
Use either :c:func:`PyEval_GetFrameLocals` to obtain the same behaviour as calling
:func:`locals` in Python code, or else call :c:func:`PyFrame_GetLocals` on the result
of :c:func:`PyEval_GetFrame` to get the same result as this function without having to
cache the proxy instance on the underlying frame.
of :c:func:`PyEval_GetFrame` to access the :attr:`~frame.f_locals` attribute of the
currently executing frame.
Return the :attr:`~frame.f_locals` attribute of the currently executing frame,
Return a mapping providing access to the local variables in the current execution frame,
or ``NULL`` if no frame is currently executing.
If the frame refers to an :term:`optimized scope`, this returns a
write-through proxy object that allows modifying the locals.
In all other cases (classes, modules, :func:`exec`, :func:`eval`) it returns
the mapping representing the frame locals directly (as described for
:func:`locals`).
Refer to :func:`locals` for details of the mapping returned at different scopes.
As this function returns a :term:`borrowed reference`, the dictionary returned for
:term:`optimized scopes <optimized scope>` is cached on the frame object and will remain
alive as long as the frame object does. Unlike :c:func:`PyEval_GetFrameLocals` and
:func:`locals`, subsequent calls to this function in the same frame will update the
contents of the cached dictionary to reflect changes in the state of the local variables
rather than returning a new snapshot.
.. versionchanged:: 3.13
As part of :pep:`667`, return a proxy object for optimized scopes.
As part of :pep:`667`, :c:func:`PyFrame_GetLocals`, :func:`locals`, and
:attr:`FrameType.f_locals <frame.f_locals>` no longer make use of the shared cache
dictionary. Refer to the :ref:`What's New entry <whatsnew313-locals-semantics>` for
additional details.
.. c:function:: PyObject* PyEval_GetGlobals(void)