From f838e17e9d8ebf9ab1c99e4cff23cd1af0ba85f2 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 8 Aug 2022 07:43:58 +0300 Subject: [PATCH 1/7] PEP 558: fix footnote references --- pep-0558.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pep-0558.rst b/pep-0558.rst index a35559ec3b5..987054dbbb9 100644 --- a/pep-0558.rst +++ b/pep-0558.rst @@ -1274,7 +1274,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 +1283,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 From af53b3dc6e54e6999717c3356e12ba0ec6ca014b Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 8 Aug 2022 07:45:34 +0300 Subject: [PATCH 2/7] PEP 558: Remove orphaned footnote --- pep-0558.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/pep-0558.rst b/pep-0558.rst index 987054dbbb9..6118f7a5315 100644 --- a/pep-0558.rst +++ b/pep-0558.rst @@ -1296,9 +1296,6 @@ References .. [1] Broken local variable assignment given threads + trace hook + closure (https://bugs.python.org/issue30744) -.. [2] Clarify the required behaviour of ``locals()`` - (https://bugs.python.org/issue17960) - .. [3] Updating function local variables from pdb is unreliable (https://bugs.python.org/issue9633) From 12f88e0bf4417d337e725a58b2eddd33ac063e73 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 8 Aug 2022 07:45:59 +0300 Subject: [PATCH 3/7] PEP 558: Remove redundant emacs metadata --- pep-0558.rst | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/pep-0558.rst b/pep-0558.rst index 6118f7a5315..f8c1802f441 100644 --- a/pep-0558.rst +++ b/pep-0558.rst @@ -1334,14 +1334,3 @@ 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: From df1f559409e7d6dbd66900ec6ae219654b4fd301 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 8 Aug 2022 07:48:03 +0300 Subject: [PATCH 4/7] PEP 558: Fix code formatting --- pep-0558.rst | 38 ++++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/pep-0558.rst b/pep-0558.rst index f8c1802f441..8efd916ec62 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) @@ -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 From 64234cda59433aab2e3e6a2ea11ed2c0a5e9b37e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 8 Aug 2022 08:17:58 +0300 Subject: [PATCH 5/7] PEP 558: Fix typos --- pep-0558.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pep-0558.rst b/pep-0558.rst index 8efd916ec62..cec27035abf 100644 --- a/pep-0558.rst +++ b/pep-0558.rst @@ -1034,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()`` @@ -1047,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 From 3f6688974bbd2216f3b982b3f06c381c1b7b8e0d Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 8 Aug 2022 08:31:20 +0300 Subject: [PATCH 6/7] PEP 558: Update BPO redirects --- pep-0558.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pep-0558.rst b/pep-0558.rst index cec27035abf..5c4330eb2e0 100644 --- a/pep-0558.rst +++ b/pep-0558.rst @@ -1312,10 +1312,10 @@ References ========== .. [1] Broken local variable assignment given threads + trace hook + closure - (https://bugs.python.org/issue30744) + (https://github.com/python/cpython/issues/74929) .. [3] Updating function local variables from pdb is unreliable - (https://bugs.python.org/issue9633) + (https://github.com/python/cpython/issues/53842) .. [4] CPython's Python API for installing trace hooks (https://docs.python.org/dev/library/sys.html#sys.settrace) @@ -1333,7 +1333,7 @@ References (https://discuss.python.org/t/pep-558-defined-semantics-for-locals/2936/3) .. [9] Disable automatic update of frame locals during tracing - (https://bugs.python.org/issue42197) + (https://github.com/python/cpython/issues/86363) .. [10] python-dev thread: Resurrecting PEP 558 (Defined semantics for locals()) (https://mail.python.org/archives/list/python-dev@python.org/thread/TUQOEWQSCQZPUDV2UFFKQ3C3I4WGFPAJ/) From ace825d8eabb27dec558b85a20bbd91aefd037f0 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 8 Aug 2022 08:37:31 +0300 Subject: [PATCH 7/7] PEP 558: Convert to regular links --- pep-0558.rst | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/pep-0558.rst b/pep-0558.rst index 5c4330eb2e0..e7c201db82a 100644 --- a/pep-0558.rst +++ b/pep-0558.rst @@ -1311,41 +1311,41 @@ 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://github.com/python/cpython/issues/74929) +.. [1] `Broken local variable assignment given threads + trace hook + closure + `_ -.. [3] Updating function local variables from pdb is unreliable - (https://github.com/python/cpython/issues/53842) +.. [3] `Updating function local variables from pdb is unreliable + `_ -.. [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 + `_ -.. [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 + `_ -.. [6] PEP 558 reference implementation - (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://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://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://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://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/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/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/message/BTQUBHIVE766RPIWLORC5ZYRCRC4CEBL/) +.. [13] `Petr Viktorin's suggestion to use an enum for PyLocals_Get's behaviour + `_ Copyright =========