PEP 558: fix footnote references (#2754)
* PEP 558: fix footnote references * PEP 558: Remove orphaned footnote * PEP 558: Remove redundant emacs metadata * PEP 558: Fix code formatting * PEP 558: Fix typos * PEP 558: Update BPO redirects * PEP 558: Convert to regular links
This commit is contained in:
Hugo van Kemenade
GitHub
parent
cdc1a44f71
commit
a4329d46e7
108
pep-0558.rst
108
pep-0558.rst
|
|
@ -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,
|
||||
|
|
@ -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,
|
||||
|
|
@ -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
|
||||
|
|
@ -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();
|
||||
|
|
@ -526,7 +536,9 @@ 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();
|
||||
|
||||
|
|
@ -534,7 +546,9 @@ Python scope, the stable C ABI would gain the following new function::
|
|||
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) {
|
||||
|
|
@ -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);
|
||||
|
|
@ -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)
|
||||
|
|
@ -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()``
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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/python-dev@python.org/thread/TUQOEWQSCQZPUDV2UFFKQ3C3I4WGFPAJ/>`_
|
||||
|
||||
.. [10] python-dev thread: Resurrecting PEP 558 (Defined semantics for locals())
|
||||
(https://mail.python.org/archives/list/python-dev@python.org/thread/TUQOEWQSCQZPUDV2UFFKQ3C3I4WGFPAJ/)
|
||||
.. [11] `python-dev thread: Comments on PEP 558
|
||||
<https://mail.python.org/archives/list/python-dev@python.org/thread/A3UN4DGBCOB45STE6AQBITJFW6UZE43O/>`_
|
||||
|
||||
.. [11] python-dev thread: Comments on PEP 558
|
||||
(https://mail.python.org/archives/list/python-dev@python.org/thread/A3UN4DGBCOB45STE6AQBITJFW6UZE43O/)
|
||||
.. [12] `python-dev thread: More comments on PEP 558
|
||||
<https://mail.python.org/archives/list/python-dev@python.org/thread/7TKPMD5LHCBXGFUIMKDAUZELRH6EX76S/>`_
|
||||
|
||||
.. [12] python-dev thread: More comments on PEP 558
|
||||
(https://mail.python.org/archives/list/python-dev@python.org/thread/7TKPMD5LHCBXGFUIMKDAUZELRH6EX76S/)
|
||||
|
||||
.. [13] Petr Viktorin's suggestion to use an enum for ``PyLocals_Get``'s behaviour
|
||||
(https://mail.python.org/archives/list/python-dev@python.org/message/BTQUBHIVE766RPIWLORC5ZYRCRC4CEBL/)
|
||||
.. [13] `Petr Viktorin's suggestion to use an enum for PyLocals_Get's behaviour
|
||||
<https://mail.python.org/archives/list/python-dev@python.org/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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue