Skip to content

PEP 558: fix footnote references #2754

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Aug 17, 2022
Merged

PEP 558: fix footnote references #2754

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
f838e17
PEP 558: fix footnote references
hugovk Aug 8, 2022
af53b3d
PEP 558: Remove orphaned footnote
hugovk Aug 8, 2022
12f88e0
PEP 558: Remove redundant emacs metadata
hugovk Aug 8, 2022
df1f559
PEP 558: Fix code formatting
hugovk Aug 8, 2022
64234cd
PEP 558: Fix typos
hugovk Aug 8, 2022
3f66889
PEP 558: Update BPO redirects
hugovk Aug 8, 2022
ace825d
PEP 558: Convert to regular links
hugovk Aug 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 56 additions & 52 deletions pep-0558.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,9 @@ behaviour at function scope to make it more predictable and independent of the
presence or absence of tracing functions.

In addition, it proposes that the following functions be added to the stable
Python C API/ABI::
Python C API/ABI:

.. code-block:: c

typedef enum {
PyLocals_UNDEFINED = -1,
Expand Down Expand Up @@ -145,7 +147,7 @@ builtin to read as follows:
dictionaries.


There would also be a versionchanged note for the release making this change:
There would also be a ``versionchanged`` note for the release making this change:

In prior versions, the semantics of mutating the mapping object returned
from ``locals()`` were formally undefined. In CPython specifically,
Expand Down Expand Up @@ -273,14 +275,20 @@ Summary of proposed implementation-specific changes

* Changes are made as necessary to provide the updated Python level semantics
* Two new functions are added to the stable ABI to replicate the updated
behaviour of the Python ``locals()`` builtin::
behaviour of the Python ``locals()`` builtin:

.. code-block:: c

PyObject * PyLocals_Get();
PyLocals_Kind PyLocals_GetKind();

* One new function is added to the stable ABI to efficiently get a snapshot of
the local namespace in the running frame::
the local namespace in the running frame:

.. code-block:: c

PyObject * PyLocals_GetCopy();

* Corresponding frame accessor functions for these new public APIs are added to
the CPython frame C API
* On optimised frames, the Python level ``f_locals`` API will return dynamically
Expand Down Expand Up @@ -494,7 +502,9 @@ independent, behaviour. However, it is also desirable to allow C code to
exactly mimic the behaviour of Python code at the same scope.

To enable mimicking the behaviour of Python code, the stable C ABI would gain
the following new functions::
the following new functions:

.. code-block:: c

PyObject * PyLocals_Get();
PyLocals_Kind PyLocals_GetKind();
Expand Down Expand Up @@ -526,15 +536,19 @@ information visually through lexical scoping (as covered in the new ``locals()``
builtin documentation).

To allow extension module code to behave consistently regardless of the active
Python scope, the stable C ABI would gain the following new function::
Python scope, the stable C ABI would gain the following new function:

.. code-block:: c

PyObject * PyLocals_GetCopy();

``PyLocals_GetCopy()`` returns a new dict instance populated from the current
locals namespace. Roughly equivalent to ``dict(locals())`` in Python code, but
avoids the double-copy in the case where ``locals()`` already returns a shallow
copy. Akin to the following code, but doesn't assume there will only ever be
two kinds of locals result::
two kinds of locals result:

.. code-block:: c

locals = PyLocals_Get();
if (PyLocals_GetKind() == PyLocals_DIRECT_REFERENCE) {
Expand Down Expand Up @@ -598,7 +612,9 @@ specifics of when the namespace it returns gets refreshed are still an
interpreter implementation detail)

The additions to the public CPython C API are the frame level enhancements
needed to support the stable C API/ABI updates::
needed to support the stable C API/ABI updates:

.. code-block:: c

PyLocals_Kind PyFrame_GetLocalsKind(frame);
PyObject * PyFrame_GetLocals(frame);
Expand Down Expand Up @@ -628,7 +644,9 @@ affected code should be updated to use
instead.

In addition to the above documented interfaces, the draft reference
implementation also exposes the following undocumented interfaces::
implementation also exposes the following undocumented interfaces:

.. code-block:: c

PyTypeObject _PyFastLocalsProxy_Type;
#define _PyFastLocalsProxy_CheckExact(self) Py_IS_TYPE(op, &_PyFastLocalsProxy_Type)
Expand Down Expand Up @@ -1016,7 +1034,7 @@ specifically related to the C API:
* :pep:`667` still proposes completely unnecessary C API breakage (the programmatic
deprecation and eventual removal of ``PyEval_GetLocals()``,
``PyFrame_FastToLocalsWithError()``, and ``PyFrame_FastToLocals()``) without
justification, when it is entirely possible to keep these working indefintely
justification, when it is entirely possible to keep these working indefinitely
(and interoperably) given a suitably designed fast locals proxy implementation
* the fast locals proxy handling of additional variables is defined in this PEP
in a way that is fully interoperable with the existing ``PyEval_GetLocals()``
Expand All @@ -1029,7 +1047,7 @@ specifically related to the C API:
like a type name than a data access API.
* this PEP adds ``PyLocals_GetCopy()`` and ``PyFrame_GetLocalsCopy()`` APIs to
allow extension modules to easily avoid incurring a double copy operation in
frames where ``PyLocals_Get()`` alreadys makes a copy
frames where ``PyLocals_Get()`` already makes a copy
* this PEP adds ``PyLocals_Kind``, ``PyLocals_GetKind()``, and
``PyFrame_GetLocalsKind()`` to allow extension modules to identify when code
is running at function scope without having to inspect non-portable frame and
Expand Down Expand Up @@ -1238,7 +1256,7 @@ complexity improvement.
The O(1) nature of the other operations can be restored by adding implementation
code that doesn't rely on the value cache being up to date.

Keeping the iterator/iterable retrieval methods as ``O(1)`` will involve
Keeping the iterator/iterable retrieval methods as O(1) will involve
writing custom replacements for the corresponding builtin dict helper types,
just as proposed in :pep:`667`. As illustrated above, the implementations would
be similar to the pseudo-code presented in :pep:`667`, but not identical (due to
Expand Down Expand Up @@ -1274,7 +1292,7 @@ Thanks to Nathaniel J. Smith for proposing the write-through proxy idea in
PEP that attempted to avoid introducing such a proxy.

Thanks to Steve Dower and Petr Viktorin for asking that more attention be paid
to the developer experience of the proposed C API additions [8,13]_.
to the developer experience of the proposed C API additions [8]_ [13]_.

Thanks to Larry Hastings for the suggestion on how to use enums in the stable
ABI while ensuring that they safely support typecasting from arbitrary
Expand All @@ -1283,7 +1301,7 @@ integers.
Thanks to Mark Shannon for pushing for further simplification of the C level
API and semantics, as well as significant clarification of the PEP text (and for
restarting discussion on the PEP in early 2021 after a further year of
inactivity) [10,11,12]_. Mark's comments that were ultimately published as
inactivity) [10]_ [11]_ [12]_. Mark's comments that were ultimately published as
:pep:`667` also directly resulted in several implementation efficiency improvements
that avoid incurring the cost of redundant O(n) mapping refresh operations
when the relevant mappings aren't used, as well as the change to ensure that
Expand All @@ -1293,58 +1311,44 @@ the state reported through the Python level ``f_locals`` API is never stale.
References
==========

.. [1] Broken local variable assignment given threads + trace hook + closure
(https://bugs.python.org/issue30744)
.. [1] `Broken local variable assignment given threads + trace hook + closure
<https://github.com/python/cpython/issues/74929>`_

.. [2] Clarify the required behaviour of ``locals()``
(https://bugs.python.org/issue17960)
.. [3] `Updating function local variables from pdb is unreliable
<https://github.com/python/cpython/issues/5384)>`_

.. [3] Updating function local variables from pdb is unreliable
(https://bugs.python.org/issue9633)
.. [4] `CPython's Python API for installing trace hooks
<https://docs.python.org/dev/library/sys.html#sys.settrace>`_

.. [4] CPython's Python API for installing trace hooks
(https://docs.python.org/dev/library/sys.html#sys.settrace)
.. [5] `CPython's C API for installing trace hooks
<https://docs.python.org/3/c-api/init.html#c.PyEval_SetTrace>`_

.. [5] CPython's C API for installing trace hooks
(https://docs.python.org/3/c-api/init.html#c.PyEval_SetTrace)
.. [6] `PEP 558 reference implementation
<https://github.com/python/cpython/pull/3640/files>`_

.. [6] PEP 558 reference implementation
(https://github.com/python/cpython/pull/3640/files)
.. [7] `Nathaniel's review of possible function level semantics for locals()
<https://mail.python.org/pipermail/python-dev/2019-May/157738.html>`_

.. [7] Nathaniel's review of possible function level semantics for locals()
(https://mail.python.org/pipermail/python-dev/2019-May/157738.html)
.. [8] `Discussion of more intentionally designed C API enhancements
<https://discuss.python.org/t/pep-558-defined-semantics-for-locals/2936/3>`_

.. [8] Discussion of more intentionally designed C API enhancements
(https://discuss.python.org/t/pep-558-defined-semantics-for-locals/2936/3)
.. [9] `Disable automatic update of frame locals during tracing
<https://github.com/python/cpython/issues/86363>`_

.. [9] Disable automatic update of frame locals during tracing
(https://bugs.python.org/issue42197)
.. [10] `python-dev thread: Resurrecting PEP 558 (Defined semantics for locals())
<https://mail.python.org/archives/list/[email protected]/thread/TUQOEWQSCQZPUDV2UFFKQ3C3I4WGFPAJ/>`_

.. [10] python-dev thread: Resurrecting PEP 558 (Defined semantics for locals())
(https://mail.python.org/archives/list/[email protected]/thread/TUQOEWQSCQZPUDV2UFFKQ3C3I4WGFPAJ/)
.. [11] `python-dev thread: Comments on PEP 558
<https://mail.python.org/archives/list/[email protected]/thread/A3UN4DGBCOB45STE6AQBITJFW6UZE43O/>`_

.. [11] python-dev thread: Comments on PEP 558
(https://mail.python.org/archives/list/[email protected]/thread/A3UN4DGBCOB45STE6AQBITJFW6UZE43O/)
.. [12] `python-dev thread: More comments on PEP 558
<https://mail.python.org/archives/list/[email protected]/thread/7TKPMD5LHCBXGFUIMKDAUZELRH6EX76S/>`_

.. [12] python-dev thread: More comments on PEP 558
(https://mail.python.org/archives/list/[email protected]/thread/7TKPMD5LHCBXGFUIMKDAUZELRH6EX76S/)

.. [13] Petr Viktorin's suggestion to use an enum for ``PyLocals_Get``'s behaviour
(https://mail.python.org/archives/list/[email protected]/message/BTQUBHIVE766RPIWLORC5ZYRCRC4CEBL/)
.. [13] `Petr Viktorin's suggestion to use an enum for PyLocals_Get's behaviour
<https://mail.python.org/archives/list/[email protected]/message/BTQUBHIVE766RPIWLORC5ZYRCRC4CEBL/>`_

Copyright
=========

This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.



..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
coding: utf-8
End: