Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitfd6cd62

Browse files
authored
gh-118934: Fix PyEval_GetLocals docs (PEP 667) (#119932)
PEP 667's description of the planned changes to PyEval_GetLocalswas internally inconsistent when accepted, so the docs added forgh-74929 didn't match either the current behaviour or the intendedbehaviour oncegh-118934 is fixed.This PR updates the documentation and 3.13 What's New to match theintended behaviour (oncegh-118934 is fixed).It also tidies up lingering references to `f_locals` always being adictionary (this hasn't been true since at least when customnamespace support for class statement execution was added)
1 parente378dc1 commitfd6cd62

File tree

3 files changed

+46
-21
lines changed

3 files changed

+46
-21
lines changed

‎Doc/c-api/reflection.rst‎

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,23 +19,28 @@ Reflection
1919
2020
.. deprecated:: 3.13
2121
22-
To avoid creating a reference cycle in :term:`optimized scopes <optimized scope>`,
23-
use either :c:func:`PyEval_GetFrameLocals` to obtain the same behaviour as calling
22+
Use either :c:func:`PyEval_GetFrameLocals` to obtain the same behaviour as calling
2423
:func:`locals` in Python code, or else call :c:func:`PyFrame_GetLocals` on the result
25-
of :c:func:`PyEval_GetFrame` toget thesame result as this function without having to
26-
cache the proxy instance on the underlying frame.
24+
of :c:func:`PyEval_GetFrame` toaccess the:attr:`~frame.f_locals` attribute of the
25+
currently executing frame.
2726
28-
Return the:attr:`~frame.f_locals` attribute of thecurrently executing frame,
27+
Returna mapping providing access tothelocal variables in thecurrent execution frame,
2928
or ``NULL`` if no frame is currently executing.
3029
31-
If the frame refers to an :term:`optimized scope`, this returns a
32-
write-through proxy object that allows modifying the locals.
33-
In all other cases (classes, modules,:func:`exec`,:func:`eval`) it returns
34-
the mapping representing the frame locals directly (as described for
35-
:func:`locals`).
30+
Refer to :func:`locals` for details of the mapping returned at different scopes.
31+
32+
As this function returns a :term:`borrowed reference`, the dictionary returned for
33+
:term:`optimized scopes <optimized scope>` is cached on the frame object and will remain
34+
alive as long as the frame object does. Unlike :c:func:`PyEval_GetFrameLocals` and
35+
:func:`locals`, subsequent calls to this function in the same frame will update the
36+
contents of the cached dictionary to reflect changes in the state of the local variables
37+
rather than returning a new snapshot.
3638
3739
.. versionchanged:: 3.13
38-
As part of :pep:`667`, return a proxy object for optimized scopes.
40+
As part of :pep:`667`, :c:func:`PyFrame_GetLocals`, :func:`locals`, and
41+
:attr:`FrameType.f_locals <frame.f_locals>` no longer make use of the shared cache
42+
dictionary. Refer to the :ref:`What's New entry <whatsnew313-locals-semantics>` for
43+
additional details.
3944
4045
4146
.. c:function:: PyObject* PyEval_GetGlobals(void)

‎Doc/reference/datamodel.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1347,13 +1347,13 @@ Special read-only attributes
13471347
``object.__getattr__`` with arguments ``obj`` and ``"f_code"``.
13481348

13491349
* - .. attribute:: frame.f_locals
1350-
- Thedictionary used by the frame to look up
1350+
- Themapping used by the frame to look up
13511351
:ref:`local variables<naming>`.
13521352
If the frame refers to an:term:`optimized scope`,
13531353
this may return a write-through proxy object.
13541354

13551355
..versionchanged::3.13
1356-
Return a proxy forfunctions and comprehensions.
1356+
Return a proxy foroptimized scopes.
13571357

13581358
* - .. attribute:: frame.f_globals
13591359
- The dictionary used by the frame to look up

‎Doc/whatsnew/3.13.rst‎

Lines changed: 28 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -287,8 +287,9 @@ returns a write-through proxy to the frame's local and locally referenced
287287
nonlocal variables in these scopes, rather than returning an inconsistently
288288
updated shared ``dict`` instance with undefined runtime semantics.
289289

290-
See:pep:`667` for more details, including related C API changes and
291-
deprecations.
290+
See:pep:`667` for more details, including related C API changes and deprecations. Porting
291+
notes are also provided below for the affected:ref:`Python APIs<pep667-porting-notes-py>`
292+
and:ref:`C APIs<pep667-porting-notes-c>`.
292293

293294
(PEP and implementation contributed by Mark Shannon and Tian Gao in
294295
:gh:`74929`. Documentation updates provided by Guido van Rossum and
@@ -2246,6 +2247,8 @@ Changes in the Python API
22462247
returned by:meth:`zipfile.ZipFile.open` was changed from ``'r'`` to ``'rb'``.
22472248
(Contributed by Serhiy Storchaka in:gh:`115961`.)
22482249

2250+
.. _pep667-porting-notes-py:
2251+
22492252
* Calling:func:`locals` in an:term:`optimized scope` now produces an
22502253
independent snapshot on each call, and hence no longer implicitly updates
22512254
previously returned references. Obtaining the legacy CPython behaviour now
@@ -2341,15 +2344,27 @@ Changes in the C API
23412344
to:c:func:`PyUnstable_Code_GetFirstFree`.
23422345
(Contributed by Bogdan Romanyuk in:gh:`115781`.)
23432346

2344-
* Calling:c:func:`PyFrame_GetLocals` or:c:func:`PyEval_GetLocals` in an
2345-
:term:`optimized scope` now returns a write-through proxy rather than a
2346-
snapshot that gets updated at ill-specified times. If a snapshot is desired,
2347-
it must be created explicitly (e.g. with:c:func:`PyDict_Copy`) or by calling
2348-
the new:c:func:`PyEval_GetFrameLocals` API. (Changed as part of:pep:`667`.)
2347+
.. _pep667-porting-notes-c:
2348+
2349+
* The effects of mutating the dictionary returned from:c:func:`PyEval_GetLocals` in an
2350+
:term:`optimized scope` have changed. New dict entries added this way will now *only* be
2351+
visible to subsequent:c:func:`PyEval_GetLocals` calls in that frame, as
2352+
:c:func:`PyFrame_GetLocals`,:func:`locals`, and
2353+
:attr:`FrameType.f_locals <frame.f_locals>` no longer access the same underlying cached
2354+
dictionary. Changes made to entries for actual variable names and names added via the
2355+
write-through proxy interfaces will be overwritten on subsequent calls to
2356+
:c:func:`PyEval_GetLocals` in that frame. The recommended code update depends on how the
2357+
function was being used, so refer to the deprecation notice on the function for details.
2358+
(Changed as part of:pep:`667`.)
2359+
2360+
* Calling:c:func:`PyFrame_GetLocals` in an:term:`optimized scope` now returns a
2361+
write-through proxy rather than a snapshot that gets updated at ill-specified times.
2362+
If a snapshot is desired, it must be created explicitly (e.g. with:c:func:`PyDict_Copy`)
2363+
or by calling the new:c:func:`PyEval_GetFrameLocals` API. (Changed as part of:pep:`667`.)
23492364

23502365
*:c:func:`!PyFrame_FastToLocals` and:c:func:`!PyFrame_FastToLocalsWithError`
23512366
no longer have any effect. Calling these functions has been redundant since
2352-
Python 3.11, when:c:func:`PyFrame_GetLocals` was first introduced.
2367+
Python 3.11, when:c:func:`PyFrame_GetLocals` was first introduced.
23532368
(Changed as part of:pep:`667`.)
23542369

23552370
*:c:func:`!PyFrame_LocalsToFast` no longer has any effect. Calling this function
@@ -2509,6 +2524,11 @@ Deprecated C APIs
25092524
:c:func:`PyWeakref_GetRef` on Python 3.12 and older.
25102525
(Contributed by Victor Stinner in:gh:`105927`.)
25112526

2527+
* Deprecate the:c:func:`PyEval_GetBuiltins`,:c:func:`PyEval_GetGlobals`, and
2528+
:c:func:`PyEval_GetLocals` functions, which return a:term:`borrowed reference`.
2529+
Refer to the deprecation notices on each function for their recommended replacements.
2530+
(Soft deprecated as part of:pep:`667`.)
2531+
25122532
Pending Removal in Python 3.14
25132533
------------------------------
25142534

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp