iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 2022-08-17 08:26:55 +03:00 committed by GitHub
parent cdc1a44f71
commit a4329d46e7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 56 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
pep-0558.rst
View File

@ -24,7 +24,9 @@ behaviour at function scope to make it more predictable and independent of the
presence or absence of tracing functions. presence or absence of tracing functions.
In addition, it proposes that the following functions be added to the stable 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 { typedef enum {
PyLocals_UNDEFINED = -1, PyLocals_UNDEFINED = -1,
@ -145,7 +147,7 @@ builtin to read as follows:
dictionaries. 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 In prior versions, the semantics of mutating the mapping object returned
from ``locals()`` were formally undefined. In CPython specifically, 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 * 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 * 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(); PyObject * PyLocals_Get();
PyLocals_Kind PyLocals_GetKind(); PyLocals_Kind PyLocals_GetKind();
* One new function is added to the stable ABI to efficiently get a snapshot of * 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(); PyObject * PyLocals_GetCopy();
* Corresponding frame accessor functions for these new public APIs are added to * Corresponding frame accessor functions for these new public APIs are added to
the CPython frame C API the CPython frame C API
* On optimised frames, the Python level ``f_locals`` API will return dynamically * 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. 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 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(); PyObject * PyLocals_Get();
PyLocals_Kind PyLocals_GetKind(); PyLocals_Kind PyLocals_GetKind();
@ -526,7 +536,9 @@ information visually through lexical scoping (as covered in the new ``locals()``
builtin documentation). builtin documentation).
To allow extension module code to behave consistently regardless of the active 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(); 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 locals namespace. Roughly equivalent to ``dict(locals())`` in Python code, but
avoids the double-copy in the case where ``locals()`` already returns a shallow 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 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(); locals = PyLocals_Get();
if (PyLocals_GetKind() == PyLocals_DIRECT_REFERENCE) { 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) interpreter implementation detail)
The additions to the public CPython C API are the frame level enhancements 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); PyLocals_Kind PyFrame_GetLocalsKind(frame);
PyObject * PyFrame_GetLocals(frame); PyObject * PyFrame_GetLocals(frame);
@ -628,7 +644,9 @@ affected code should be updated to use
instead. instead.
In addition to the above documented interfaces, the draft reference 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; PyTypeObject _PyFastLocalsProxy_Type;
#define _PyFastLocalsProxy_CheckExact(self) Py_IS_TYPE(op, &_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 * :pep:`667` still proposes completely unnecessary C API breakage (the programmatic
deprecation and eventual removal of ``PyEval_GetLocals()``, deprecation and eventual removal of ``PyEval_GetLocals()``,
``PyFrame_FastToLocalsWithError()``, and ``PyFrame_FastToLocals()``) without ``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 (and interoperably) given a suitably designed fast locals proxy implementation
* the fast locals proxy handling of additional variables is defined in this PEP * 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()`` 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. like a type name than a data access API.
* this PEP adds ``PyLocals_GetCopy()`` and ``PyFrame_GetLocalsCopy()`` APIs to * this PEP adds ``PyLocals_GetCopy()`` and ``PyFrame_GetLocalsCopy()`` APIs to
allow extension modules to easily avoid incurring a double copy operation in 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 * this PEP adds ``PyLocals_Kind``, ``PyLocals_GetKind()``, and
``PyFrame_GetLocalsKind()`` to allow extension modules to identify when code ``PyFrame_GetLocalsKind()`` to allow extension modules to identify when code
is running at function scope without having to inspect non-portable frame and 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 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. 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, writing custom replacements for the corresponding builtin dict helper types,
just as proposed in :pep:`667`. As illustrated above, the implementations would 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 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. PEP that attempted to avoid introducing such a proxy.
Thanks to Steve Dower and Petr Viktorin for asking that more attention be paid 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 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 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 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 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 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 :pep:`667` also directly resulted in several implementation efficiency improvements
that avoid incurring the cost of redundant O(n) mapping refresh operations 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 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 References
========== ==========
.. [1] Broken local variable assignment given threads + trace hook + closure .. [1] `Broken local variable assignment given threads + trace hook + closure
(https://bugs.python.org/issue30744) <https://github.com/python/cpython/issues/74929>`_
.. [2] Clarify the required behaviour of ``locals()`` .. [3] `Updating function local variables from pdb is unreliable
(https://bugs.python.org/issue17960) <https://github.com/python/cpython/issues/5384)>`_
.. [3] Updating function local variables from pdb is unreliable .. [4] `CPython's Python API for installing trace hooks
(https://bugs.python.org/issue9633) <https://docs.python.org/dev/library/sys.html#sys.settrace>`_
.. [4] CPython's Python API for installing trace hooks .. [5] `CPython's C API for installing trace hooks
(https://docs.python.org/dev/library/sys.html#sys.settrace) <https://docs.python.org/3/c-api/init.html#c.PyEval_SetTrace>`_
.. [5] CPython's C API for installing trace hooks .. [6] `PEP 558 reference implementation
(https://docs.python.org/3/c-api/init.html#c.PyEval_SetTrace) <https://github.com/python/cpython/pull/3640/files>`_
.. [6] PEP 558 reference implementation .. [7] `Nathaniel's review of possible function level semantics for locals()
(https://github.com/python/cpython/pull/3640/files) <https://mail.python.org/pipermail/python-dev/2019-May/157738.html>`_
.. [7] Nathaniel's review of possible function level semantics for locals() .. [8] `Discussion of more intentionally designed C API enhancements
(https://mail.python.org/pipermail/python-dev/2019-May/157738.html) <https://discuss.python.org/t/pep-558-defined-semantics-for-locals/2936/3>`_
.. [8] Discussion of more intentionally designed C API enhancements .. [9] `Disable automatic update of frame locals during tracing
(https://discuss.python.org/t/pep-558-defined-semantics-for-locals/2936/3) <https://github.com/python/cpython/issues/86363>`_
.. [9] Disable automatic update of frame locals during tracing .. [10] `python-dev thread: Resurrecting PEP 558 (Defined semantics for locals())
(https://bugs.python.org/issue42197) <https://mail.python.org/archives/list/python-dev@python.org/thread/TUQOEWQSCQZPUDV2UFFKQ3C3I4WGFPAJ/>`_
.. [10] python-dev thread: Resurrecting PEP 558 (Defined semantics for locals()) .. [11] `python-dev thread: Comments on PEP 558
(https://mail.python.org/archives/list/python-dev@python.org/thread/TUQOEWQSCQZPUDV2UFFKQ3C3I4WGFPAJ/) <https://mail.python.org/archives/list/python-dev@python.org/thread/A3UN4DGBCOB45STE6AQBITJFW6UZE43O/>`_
.. [11] python-dev thread: Comments on PEP 558 .. [12] `python-dev thread: More comments on PEP 558
(https://mail.python.org/archives/list/python-dev@python.org/thread/A3UN4DGBCOB45STE6AQBITJFW6UZE43O/) <https://mail.python.org/archives/list/python-dev@python.org/thread/7TKPMD5LHCBXGFUIMKDAUZELRH6EX76S/>`_
.. [12] python-dev thread: More comments on PEP 558 .. [13] `Petr Viktorin's suggestion to use an enum for PyLocals_Get's behaviour
(https://mail.python.org/archives/list/python-dev@python.org/thread/7TKPMD5LHCBXGFUIMKDAUZELRH6EX76S/) <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 Copyright
========= =========
This document is placed in the public domain or under the This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive. 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: