From a4329d46e7c50757a0097f5eaf6b9c89b47006df Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 17 Aug 2022 08:26:55 +0300 Subject: [PATCH] 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 --- pep-0558.rst | 108 ++++++++++++++++++++++++++------------------------- 1 file changed, 56 insertions(+), 52 deletions(-) diff --git a/pep-0558.rst b/pep-0558.rst index a35559ec3..e7c201db8 100644 --- a/pep-0558.rst +++ b/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 + `_ -.. [2] Clarify the required behaviour of ``locals()`` - (https://bugs.python.org/issue17960) +.. [3] `Updating function local variables from pdb is unreliable + `_ -.. [3] Updating function local variables from pdb is unreliable - (https://bugs.python.org/issue9633) +.. [4] `CPython's Python API for installing trace hooks + `_ -.. [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 + `_ -.. [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 + `_ -.. [6] PEP 558 reference implementation - (https://github.com/python/cpython/pull/3640/files) +.. [7] `Nathaniel's review of possible function level semantics for locals() + `_ -.. [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 + `_ -.. [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 + `_ -.. [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()) + `_ -.. [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 + `_ -.. [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 + `_ -.. [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 + `_ 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: