CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 667 – Consistent views of namespaces | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0667/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 667 – Consistent views of namespaces | peps.python.org'> <meta property="og:description" content="In early versions of Python all namespaces, whether in functions, classes or modules, were all implemented the same way: as a dictionary."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0667/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="In early versions of Python all namespaces, whether in functions, classes or modules, were all implemented the same way: as a dictionary."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 667</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 667 – Consistent views of namespaces</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Mark Shannon , Tian Gao <gaogaotiantian at hotmail.com></dd> <dt class="field-even">Discussions-To:</dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/46631">Discourse thread</a></dd> <dt class="field-odd">Status:</dt> <dd class="field-odd"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-even">Type:</dt> <dd class="field-even"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-odd">Created:</dt> <dd class="field-odd">30-Jul-2021</dd> <dt class="field-even">Python-Version:</dt> <dd class="field-even">3.13</dd> <dt class="field-odd">Post-History:</dt> <dd class="field-odd">20-Aug-2021, 22-Feb-2024</dd> <dt class="field-even">Resolution:</dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/46631/25">25-Apr-2024</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#making-the-frame-f-locals-attribute-a-write-through-proxy">Making the <code class="docutils literal notranslate">frame.f_locals</code> attribute a write-through proxy</a></li> <li><a class="reference internal" href="#making-the-locals-builtin-return-independent-snapshots">Making the <code class="docutils literal notranslate">locals()</code> builtin return independent snapshots</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#python-api">Python API</a><ul> <li><a class="reference internal" href="#the-frame-f-locals-attribute">The <code class="docutils literal notranslate">frame.f_locals</code> attribute</a></li> <li><a class="reference internal" href="#the-locals-builtin">The <code class="docutils literal notranslate">locals()</code> builtin</a></li> <li><a class="reference internal" href="#the-eval-and-exec-builtins">The <code class="docutils literal notranslate">eval()</code> and <code class="docutils literal notranslate">exec()</code> builtins</a></li> </ul> </li> <li><a class="reference internal" href="#c-api">C API</a><ul> <li><a class="reference internal" href="#additions-to-the-pyeval-c-api">Additions to the <code class="docutils literal notranslate">PyEval</code> C API</a></li> <li><a class="reference internal" href="#pyframe-getlocals-c-api"><code class="docutils literal notranslate">PyFrame_GetLocals</code> C API</a></li> <li><a class="reference internal" href="#deprecated-c-apis">Deprecated C APIs</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#summary-of-changes">Summary of Changes</a><ul> <li><a class="reference internal" href="#python-api-changes">Python API changes</a><ul> <li><a class="reference internal" href="#frame-f-locals-changes"><code class="docutils literal notranslate">frame.f_locals</code> changes</a></li> <li><a class="reference internal" href="#locals-changes"><code class="docutils literal notranslate">locals()</code> changes</a></li> <li><a class="reference internal" href="#eval-and-exec-changes"><code class="docutils literal notranslate">eval()</code> and <code class="docutils literal notranslate">exec()</code> changes</a></li> </ul> </li> <li><a class="reference internal" href="#c-api-changes">C API changes</a><ul> <li><a class="reference internal" href="#pyframe-getlocals-change"><code class="docutils literal notranslate">PyFrame_GetLocals</code> change</a></li> <li><a class="reference internal" href="#pyeval-getlocals-change"><code class="docutils literal notranslate">PyEval_GetLocals</code> change</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a><ul> <li><a class="reference internal" href="#python-api-compatibility">Python API compatibility</a></li> <li><a class="reference internal" href="#frame-f-locals-compatibility"><code class="docutils literal notranslate">frame.f_locals</code> compatibility</a><ul> <li><a class="reference internal" href="#locals-compatibility"><code class="docutils literal notranslate">locals()</code> compatibility</a></li> <li><a class="reference internal" href="#impact-on-exec-and-eval">Impact on <code class="docutils literal notranslate">exec()</code> and <code class="docutils literal notranslate">eval()</code></a></li> <li><a class="reference internal" href="#impact-on-other-code-execution-apis-in-the-standard-library">Impact on other code execution APIs in the standard library</a></li> </ul> </li> <li><a class="reference internal" href="#c-api-compatibility">C API compatibility</a><ul> <li><a class="reference internal" href="#pyeval-getlocals-compatibility"><code class="docutils literal notranslate">PyEval_GetLocals</code> compatibility</a></li> </ul> </li> <li><a class="reference internal" href="#impact-on-pep-709-inlined-comprehensions">Impact on PEP 709 inlined comprehensions</a></li> </ul> </li> <li><a class="reference internal" href="#implementation">Implementation</a><ul> <li><a class="reference internal" href="#id1">C API</a></li> </ul> </li> <li><a class="reference internal" href="#implementation-notes">Implementation Notes</a></li> <li><a class="reference internal" href="#comparison-with-pep-558">Comparison with PEP 558</a></li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <div class="pep-banner canonical-doc sticky-banner admonition important"> Important This PEP is a historical document. The up-to-date, canonical documentation can now be found at <a class="reference external" href="https://docs.python.org/3.13/library/functions.html#locals" title="(in Python v3.13)"><code class="xref py py-func docutils literal notranslate">locals()</code></a>. × See <a class="pep reference internal" href="../pep-0001/" title="PEP 1 – PEP Purpose and Guidelines">PEP 1</a> for how to propose changes. </div> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> In early versions of Python all namespaces, whether in functions, classes or modules, were all implemented the same way: as a dictionary. For performance reasons, the implementation of function namespaces was changed. Unfortunately this meant that accessing these namespaces through <code class="docutils literal notranslate">locals()</code> and <code class="docutils literal notranslate">frame.f_locals</code> ceased to be consistent and some odd bugs crept in over the years as threads, generators and coroutines were added. This PEP proposes making these namespaces consistent once more. Modifications to <code class="docutils literal notranslate">frame.f_locals</code> will always be visible in the underlying variables. Modifications to local variables will immediately be visible in <code class="docutils literal notranslate">frame.f_locals</code>, and they will be consistent regardless of threading or coroutines. The <code class="docutils literal notranslate">locals()</code> function will act the same as it does now for class and modules scopes. For function scopes it will return an instantaneous snapshot of the underlying <code class="docutils literal notranslate">frame.f_locals</code> rather than implicitly refreshing a single shared dictionary cached on the frame object. </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> The implementation of <code class="docutils literal notranslate">locals()</code> and <code class="docutils literal notranslate">frame.f_locals</code> in releases up to and including Python 3.12 is slow, inconsistent and buggy. We want to make it faster, consistent, and most importantly fix the bugs. For example, when attempting to manipulate local variables via frame objects: <div class="highlight-default notranslate"><div class="highlight"><pre>class C: x = 1 sys._getframe().f_locals['x'] = 2 print(x) </pre></div> </div> prints <code class="docutils literal notranslate">2</code>, but: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(): x = 1 sys._getframe().f_locals['x'] = 2 print(x) f() </pre></div> </div> prints <code class="docutils literal notranslate">1</code>. This is inconsistent, and confusing. Worse than that, the Python 3.12 behavior can result in strange <a class="reference external" href="https://github.com/python/cpython/issues/74929">bugs</a>. With this PEP both examples would print <code class="docutils literal notranslate">2</code> as the function level change would be written directly to the optimized local variables in the frame rather than to a cached dictionary snapshot. There are no compensating advantages for the Python 3.12 behavior; it is unreliable and slow. The <code class="docutils literal notranslate">locals()</code> builtin has its own undesirable behaviours. Refer to <a class="pep reference internal" href="../pep-0558/" title="PEP 558 – Defined semantics for locals()">PEP 558</a> for additional details on those concerns. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <section id="making-the-frame-f-locals-attribute-a-write-through-proxy"> <h3><a class="toc-backref" href="#making-the-frame-f-locals-attribute-a-write-through-proxy" role="doc-backlink">Making the <code class="docutils literal notranslate">frame.f_locals</code> attribute a write-through proxy</a></h3> The Python 3.12 implementation of <code class="docutils literal notranslate">frame.f_locals</code> returns a dictionary that is created on the fly from the array of local variables. The <code class="docutils literal notranslate">PyFrame_LocalsToFast()</code> C API is then called by debuggers and trace functions that want to write their changes back to the array (until Python 3.11, this API was called implicitly after every trace function invocation rather than being called explicitly by the trace functions). This can result in the array and dictionary getting out of sync with each other. Writes to the <code class="docutils literal notranslate">f_locals</code> frame attribute may not show up as modifications to local variables if <code class="docutils literal notranslate">PyFrame_LocalsToFast()</code> is never called. Writes to local variables can get lost if a dictionary snapshot created before the variables were modified is written back to the frame (since every known variable stored in the snapshot is written back to the frame, even if the value stored on the frame had changed since the snapshot was taken). By making <code class="docutils literal notranslate">frame.f_locals</code> return a view on the underlying frame, these problems go away. <code class="docutils literal notranslate">frame.f_locals</code> is always in sync with the frame because it is a view of it, not a copy of it. </section> <section id="making-the-locals-builtin-return-independent-snapshots"> <h3><a class="toc-backref" href="#making-the-locals-builtin-return-independent-snapshots" role="doc-backlink">Making the <code class="docutils literal notranslate">locals()</code> builtin return independent snapshots</a></h3> <a class="pep reference internal" href="../pep-0558/" title="PEP 558 – Defined semantics for locals()">PEP 558</a> considered three potential options for standardising the behavior of the <code class="docutils literal notranslate">locals()</code> builtin in <a class="reference external" href="https://docs.python.org/3.13/glossary.html#term-optimized-scope" title="(in Python v3.13)">optimized scopes</a>: <ul class="simple"> <li>retain the historical behaviour of having each call to <code class="docutils literal notranslate">locals()</code> on a given frame update a single shared snapshot of the local variables</li> <li>make <code class="docutils literal notranslate">locals()</code> return write-through proxy instances (similar to <code class="docutils literal notranslate">frame.f_locals</code>)</li> <li>make <code class="docutils literal notranslate">locals()</code> return genuinely independent snapshots so that attempts to change the values of local variables via <code class="docutils literal notranslate">exec()</code> would be consistently ignored rather than being accepted in some circumstances</li> </ul> The last option was chosen as the one which could most easily be explained in the language reference, and memorised by users: <ul class="simple"> <li>the <code class="docutils literal notranslate">locals()</code> builtin gives an instantaneous snapshot of the local variables in optimized scopes, and read/write access in other scopes; and</li> <li><code class="docutils literal notranslate">frame.f_locals</code> gives read/write access to the local variables in all scopes, including optimized scopes</li> </ul> This approach allows the intent of a piece of code to be clearer than it would be if both APIs granted full read/write access in optimized scopes, even when write access wasn’t needed or desired. For additional details on this design decision, refer to <a class="pep reference internal" href="../pep-0558/" title="PEP 558 – Defined semantics for locals()">PEP 558</a>, especially the <a class="reference internal" href="../pep-0558/#pep-558-motivation">Motivation</a> section and <a class="reference internal" href="../pep-0558/#pep-558-exec-eval-impact">Additional considerations for eval() and exec() in optimized scopes</a>. This approach is not without its drawbacks, which are covered in the Backwards Compatibility section below. </section> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <section id="python-api"> <h3><a class="toc-backref" href="#python-api" role="doc-backlink">Python API</a></h3> <section id="the-frame-f-locals-attribute"> <h4><a class="toc-backref" href="#the-frame-f-locals-attribute" role="doc-backlink">The <code class="docutils literal notranslate">frame.f_locals</code> attribute</a></h4> For module and class scopes (including <code class="docutils literal notranslate">exec()</code> and <code class="docutils literal notranslate">eval()</code> invocations), <code class="docutils literal notranslate">frame.f_locals</code> is a direct reference to the local variable namespace used in code execution. For function scopes (and other <a class="reference external" href="https://docs.python.org/3.13/glossary.html#term-optimized-scope" title="(in Python v3.13)">optimized scopes</a>) it will be an instance of a new write-through proxy type that can directly modify the optimized local variable storage array in the underlying frame, as well as the contents of any cell references to non-local variables. The view objects fully implement the <code class="docutils literal notranslate">collections.abc.Mapping</code> interface, and also implement the following mutable mapping operations: <ul class="simple"> <li>using assignment to add new key/value pairs</li> <li>using assignment to update the value associated with a key</li> <li>conditional assignment via the <code class="docutils literal notranslate">setdefault()</code> method</li> <li>bulk updates via the <code class="docutils literal notranslate">update()</code> method</li> </ul> Views of different frames compare unequal even if they have the same contents. All writes to the <code class="docutils literal notranslate">f_locals</code> mapping will be immediately visible in the underlying variables. All changes to the underlying variables will be immediately visible in the mapping. The <code class="docutils literal notranslate">f_locals</code> object will be a full mapping, and can have arbitrary key-value pairs added to it. New names added via the proxies will be stored in a dedicated shared dictionary stored on the underlying frame object (so all proxy instances for a given frame will be able to access any names added this way). Extra keys (which do not correspond to local variables on the underlying frame) may be removed as usual with <code class="docutils literal notranslate">del</code> statements or the <code class="docutils literal notranslate">pop()</code> method. Using <code class="docutils literal notranslate">del</code>, or the <code class="docutils literal notranslate">pop()</code> method, to remove keys that correspond to local variables on the underlying frame is NOT supported, and attempting to do so will raise <code class="docutils literal notranslate">ValueError</code>. Local variables can only be set to <code class="docutils literal notranslate">None</code> (or some other value) via the proxy, they cannot be unbound completely. The <code class="docutils literal notranslate">clear()</code> method is NOT implemented on the write-through proxies, as it is unclear how it should handle the inability to delete entries corresponding to local variables. To maintain backwards compatibility, proxy APIs that need to produce a new mapping (such as <code class="docutils literal notranslate">copy()</code>) will produce regular builtin <code class="docutils literal notranslate">dict</code> instances, rather than write-through proxy instances. To avoid introducing a circular reference between frame objects and the write-through proxies, each access to <code class="docutils literal notranslate">frame.f_locals</code> returns a new write-through proxy instance. </section> <section id="the-locals-builtin"> <h4><a class="toc-backref" href="#the-locals-builtin" role="doc-backlink">The <code class="docutils literal notranslate">locals()</code> builtin</a></h4> <code class="docutils literal notranslate">locals()</code> will be defined as: <div class="highlight-default notranslate"><div class="highlight"><pre>def locals(): frame = sys._getframe(1) f_locals = frame.f_locals if frame._is_optimized(): # Not an actual frame method f_locals = dict(f_locals) return f_locals </pre></div> </div> For module and class scopes (including <code class="docutils literal notranslate">exec()</code> and <code class="docutils literal notranslate">eval()</code> invocations), <code class="docutils literal notranslate">locals()</code> continues to return a direct reference to the local variable namespace used in code execution (which is also the same value reported by <code class="docutils literal notranslate">frame.f_locals</code>). In <a class="reference external" href="https://docs.python.org/3.13/glossary.html#term-optimized-scope" title="(in Python v3.13)">optimized scopes</a>, each call to <code class="docutils literal notranslate">locals()</code> will produce an independent snapshot of the local variables. </section> <section id="the-eval-and-exec-builtins"> <h4><a class="toc-backref" href="#the-eval-and-exec-builtins" role="doc-backlink">The <code class="docutils literal notranslate">eval()</code> and <code class="docutils literal notranslate">exec()</code> builtins</a></h4> Because this PEP changes the behavior of <code class="docutils literal notranslate">locals()</code>, the behavior of <code class="docutils literal notranslate">eval()</code> and <code class="docutils literal notranslate">exec()</code> also changes. Assuming a function <code class="docutils literal notranslate">_eval()</code> which performs the job of <code class="docutils literal notranslate">eval()</code> with explicit namespace arguments, <code class="docutils literal notranslate">eval()</code> can be defined as follows: <div class="highlight-default notranslate"><div class="highlight"><pre>FrameProxyType = type((lambda: sys._getframe().f_locals)()) def eval(expression, /, globals=None, locals=None): if globals is None: # No globals -> use calling frame's globals _calling_frame = sys._getframe(1) globals = _calling_frame.f_globals if locals is None: # No globals or locals -> use calling frame's locals locals = _calling_frame.f_locals if isinstance(locals, FrameProxyType): # Align with locals() builtin in optimized frame locals = dict(locals) elif locals is None: # Globals but no locals -> use same namespace for both locals = globals return _eval(expression, globals, locals) </pre></div> </div> The specified argument handling for <code class="docutils literal notranslate">exec()</code> is similarly updated. (In Python 3.12 and earlier, it was not possible to provide <code class="docutils literal notranslate">locals</code> to <code class="docutils literal notranslate">eval()</code> or <code class="docutils literal notranslate">exec()</code> without also providing <code class="docutils literal notranslate">globals</code> as these were previously positional-only arguments. Independently of this PEP, Python 3.13 updated these builtins to accept keyword arguments) </section> </section> <section id="c-api"> <h3><a class="toc-backref" href="#c-api" role="doc-backlink">C API</a></h3> <section id="additions-to-the-pyeval-c-api"> <h4><a class="toc-backref" href="#additions-to-the-pyeval-c-api" role="doc-backlink">Additions to the <code class="docutils literal notranslate">PyEval</code> C API</a></h4> Three new C-API functions will be added: <div class="highlight-default notranslate"><div class="highlight"><pre>PyObject *PyEval_GetFrameLocals(void) PyObject *PyEval_GetFrameGlobals(void) PyObject *PyEval_GetFrameBuiltins(void) </pre></div> </div> <code class="docutils literal notranslate">PyEval_GetFrameLocals()</code> is equivalent to: <code class="docutils literal notranslate">locals()</code>. <code class="docutils literal notranslate">PyEval_GetFrameGlobals()</code> is equivalent to: <code class="docutils literal notranslate">globals()</code>. All of these functions will return a new reference. </section> <section id="pyframe-getlocals-c-api"> <h4><a class="toc-backref" href="#pyframe-getlocals-c-api" role="doc-backlink"><code class="docutils literal notranslate">PyFrame_GetLocals</code> C API</a></h4> The existing <code class="docutils literal notranslate">PyFrame_GetLocals(f)</code> C API is equivalent to <code class="docutils literal notranslate">f.f_locals</code>. Its return value will be as described above for accessing <code class="docutils literal notranslate">f.f_locals</code>. This function returns a new reference, so it is able to accommodate the creation of a new write-through proxy instance on each call in an optimized scope. </section> <section id="deprecated-c-apis"> <h4><a class="toc-backref" href="#deprecated-c-apis" role="doc-backlink">Deprecated C APIs</a></h4> The following C API functions will be deprecated, as they return borrowed references: <div class="highlight-default notranslate"><div class="highlight"><pre>PyEval_GetLocals() PyEval_GetGlobals() PyEval_GetBuiltins() </pre></div> </div> The following functions (which return new references) should be used instead: <div class="highlight-default notranslate"><div class="highlight"><pre>PyEval_GetFrameLocals() PyEval_GetFrameGlobals() PyEval_GetFrameBuiltins() </pre></div> </div> The following C API functions will become no-ops, and will be deprecated without replacement: <div class="highlight-default notranslate"><div class="highlight"><pre>PyFrame_FastToLocalsWithError() PyFrame_FastToLocals() PyFrame_LocalsToFast() </pre></div> </div> All of the deprecated functions will be marked as deprecated in the Python 3.13 documentation. Of these functions, only <code class="docutils literal notranslate">PyEval_GetLocals()</code> poses any significant maintenance burden. Accordingly, calls to <code class="docutils literal notranslate">PyEval_GetLocals()</code> will emit <code class="docutils literal notranslate">DeprecationWarning</code> in Python 3.14, with a target removal date of Python 3.16 (two releases after Python 3.14). Alternatives are recommended as described in <a class="reference internal" href="#pep-667-pyeval-getlocals-compatibility">PyEval_GetLocals compatibility</a>. </section> </section> </section> <section id="summary-of-changes"> <h2><a class="toc-backref" href="#summary-of-changes" role="doc-backlink">Summary of Changes</a></h2> This section summarises how the specified behaviour in Python 3.13 and later differs from the historical behaviour in Python 3.12 and earlier versions. <section id="python-api-changes"> <h3><a class="toc-backref" href="#python-api-changes" role="doc-backlink">Python API changes</a></h3> <section id="frame-f-locals-changes"> <h4><a class="toc-backref" href="#frame-f-locals-changes" role="doc-backlink"><code class="docutils literal notranslate">frame.f_locals</code> changes</a></h4> Consider the following example: <div class="highlight-default notranslate"><div class="highlight"><pre>def l(): "Get the locals of caller" return sys._getframe(1).f_locals def test(): if 0: y = 1 # Make 'y' a local variable x = 1 l()['x'] = 2 l()['y'] = 4 l()['z'] = 5 y print(locals(), x) </pre></div> </div> Given the changes in this PEP, <code class="docutils literal notranslate">test()</code> will print <code class="docutils literal notranslate">{'x': 2, 'y': 4, 'z': 5} 2</code>. In Python 3.12, this example will fail with an <code class="docutils literal notranslate">UnboundLocalError</code>, as the definition of <code class="docutils literal notranslate">y</code> by <code class="docutils literal notranslate">l()['y'] = 4</code> is lost. If the second-to-last line were changed from <code class="docutils literal notranslate">y</code> to <code class="docutils literal notranslate">z</code>, this will still raise <code class="docutils literal notranslate">NameError</code>, as it does in Python 3.12. Keys added to <code class="docutils literal notranslate">frame.f_locals</code> that are not lexically local variables remain visible in <code class="docutils literal notranslate">frame.f_locals</code>, but do not dynamically become local variables. </section> <section id="locals-changes"> <h4><a class="toc-backref" href="#locals-changes" role="doc-backlink"><code class="docutils literal notranslate">locals()</code> changes</a></h4> Consider the following example: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(): exec("x = 1") print(locals().get("x")) f() </pre></div> </div> Given the changes in this PEP, this will always print <code class="docutils literal notranslate">None</code> (regardless of whether <code class="docutils literal notranslate">x</code> is a defined local variable in the function), as the explicit call to <code class="docutils literal notranslate">locals()</code> produces a distinct snapshot from the one implicitly used in the <code class="docutils literal notranslate">exec()</code> call. In Python 3.12, the exact example shown would print <code class="docutils literal notranslate">1</code>, but seemingly unrelated changes to the definition of the function involved could make it print <code class="docutils literal notranslate">None</code> instead (<a class="reference internal" href="../pep-0558/#pep-558-exec-eval-impact">Additional considerations for eval() and exec() in optimized scopes</a> in PEP 558 goes into more detail on that topic). </section> <section id="eval-and-exec-changes"> <h4><a class="toc-backref" href="#eval-and-exec-changes" role="doc-backlink"><code class="docutils literal notranslate">eval()</code> and <code class="docutils literal notranslate">exec()</code> changes</a></h4> The primary change affecting <code class="docutils literal notranslate">eval()</code> and <code class="docutils literal notranslate">exec()</code> is shown in the “<a class="reference internal" href="#pep-667-locals-changes">locals() changes</a>” example: repeatedly accessing <code class="docutils literal notranslate">locals()</code> in an optimized scope will no longer implicitly share a common underlying namespace. </section> </section> <section id="c-api-changes"> <h3><a class="toc-backref" href="#c-api-changes" role="doc-backlink">C API changes</a></h3> <section id="pyframe-getlocals-change"> <h4><a class="toc-backref" href="#pyframe-getlocals-change" role="doc-backlink"><code class="docutils literal notranslate">PyFrame_GetLocals</code> change</a></h4> <code class="docutils literal notranslate">PyFrame_GetLocals</code> can already return arbitrary mappings in Python 3.12, as <code class="docutils literal notranslate">exec()</code> and <code class="docutils literal notranslate">eval()</code> accept arbitrary mappings as their <code class="docutils literal notranslate">locals</code> argument, and metaclasses may return arbitrary mappings from their <code class="docutils literal notranslate">__prepare__</code> methods. Returning a frame locals proxy in optimized scopes just adds another case where something other than a builtin dictionary will be returned. </section> <section id="pyeval-getlocals-change"> <h4><a class="toc-backref" href="#pyeval-getlocals-change" role="doc-backlink"><code class="docutils literal notranslate">PyEval_GetLocals</code> change</a></h4> The semantics of <code class="docutils literal notranslate">PyEval_GetLocals()</code> are technically unchanged, but they do change in practice as the dictionary cached on optimized frames is no longer shared with other mechanisms for accessing the frame locals (<code class="docutils literal notranslate">locals()</code> builtin, <code class="docutils literal notranslate">PyFrame_GetLocals</code> function, frame <code class="docutils literal notranslate">f_locals</code> attributes). </section> </section> </section> <section id="backwards-compatibility"> <h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2> <section id="python-api-compatibility"> <h3><a class="toc-backref" href="#python-api-compatibility" role="doc-backlink">Python API compatibility</a></h3> The implementation used in versions up to and including Python 3.12 has many corner cases and oddities. Code that works around those may need to be changed. Code that uses <code class="docutils literal notranslate">locals()</code> for simple templating, or print debugging, will continue to work correctly. Debuggers and other tools that use <code class="docutils literal notranslate">f_locals</code> to modify local variables, will now work correctly, even in the presence of threaded code, coroutines and generators. </section> <section id="frame-f-locals-compatibility"> <h3><a class="toc-backref" href="#frame-f-locals-compatibility" role="doc-backlink"><code class="docutils literal notranslate">frame.f_locals</code> compatibility</a></h3> Although <code class="docutils literal notranslate">f.f_locals</code> behaves as if it were the namespace of the function, there will be some observable differences. For example, <code class="docutils literal notranslate">f.f_locals is f.f_locals</code> will be <code class="docutils literal notranslate">False</code> for optimized frames, as each access to the attribute produces a new write-through proxy instance. However <code class="docutils literal notranslate">f.f_locals == f.f_locals</code> will be <code class="docutils literal notranslate">True</code>, and all changes to the underlying variables, by any means, including the addition of new variable names as mapping keys, will always be visible. <section id="locals-compatibility"> <h4><a class="toc-backref" href="#locals-compatibility" role="doc-backlink"><code class="docutils literal notranslate">locals()</code> compatibility</a></h4> <code class="docutils literal notranslate">locals() is locals()</code> will be <code class="docutils literal notranslate">False</code> for optimized frames, so code like the following will raise <code class="docutils literal notranslate">KeyError</code> instead of returning <code class="docutils literal notranslate">1</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(): locals()["x"] = 1 return locals()["x"] </pre></div> </div> To continue working, such code will need to explicitly store the namespace to be modified in a local variable, rather than relying on the previous implicit caching on the frame object: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(): ns = {} ns["x"] = 1 return ns["x"] </pre></div> </div> While this technically isn’t a formal backwards compatibility break (since the behaviour of writing back to <code class="docutils literal notranslate">locals()</code> was explicitly documented as undefined), there is definitely some code that relies on the existing behaviour. Accordingly, the updated behaviour will be explicitly noted in the documentation as a change and it will be covered in the Python 3.13 porting guide. To work with a copy of <code class="docutils literal notranslate">locals()</code> in optimized scopes on all versions without making redundant copies on Python 3.13+, users will need to define a version-dependent helper function that only makes an explicit copy on Python versions prior to Python 3.13: <div class="highlight-default notranslate"><div class="highlight"><pre>if sys.version_info >= (3, 13): def _ensure_func_snapshot(d): return d # 3.13+ locals() already returns a snapshot else: def _ensure_func_snapshot(d): return dict(d) # Create snapshot on older versions def f(): ns = _ensure_func_snapshot(locals()) ns["x"] = 1 return ns </pre></div> </div> In other scopes, <code class="docutils literal notranslate">locals().copy()</code> can continue to be called unconditionally without introducing any redundant copies. </section> <section id="impact-on-exec-and-eval"> <h4><a class="toc-backref" href="#impact-on-exec-and-eval" role="doc-backlink">Impact on <code class="docutils literal notranslate">exec()</code> and <code class="docutils literal notranslate">eval()</code></a></h4> Even though this PEP does not modify <code class="docutils literal notranslate">exec()</code> or <code class="docutils literal notranslate">eval()</code> directly, the semantic change to <code class="docutils literal notranslate">locals()</code> impacts the behavior of <code class="docutils literal notranslate">exec()</code> and <code class="docutils literal notranslate">eval()</code> as they default to running code in the calling namespace. This poses a potential compatibility issue for some code, as with the previous implementation that returns the same dict when <code class="docutils literal notranslate">locals()</code> is called multiple times in function scope, the following code usually worked due to the implicitly shared local variable namespace: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(): exec('a = 0') # equivalent to exec('a = 0', globals(), locals()) exec('print(a)') # equivalent to exec('print(a)', globals(), locals()) print(locals()) # {'a': 0} # However, print(a) will not work here f() </pre></div> </div> With the semantic changes to <code class="docutils literal notranslate">locals()</code> in this PEP, the <code class="docutils literal notranslate">exec('print(a)')'</code> call will fail with <code class="docutils literal notranslate">NameError</code>, and <code class="docutils literal notranslate">print(locals())</code> will report an empty dictionary, as each line will be using its own distinct snapshot of the local variables rather than implicitly sharing a single cached snapshot stored on the frame object. A shared namespace across <code class="docutils literal notranslate">exec()</code> calls can still be obtained by using explicit namespaces rather than relying on the previously implicitly shared frame namespace: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(): ns = {} exec('a = 0', locals=ns) exec('print(a)', locals=ns) # 0 f() </pre></div> </div> You can even reliably change the variables in the local scope by explicitly using <code class="docutils literal notranslate">frame.f_locals</code>, which was not possible before (even using <code class="docutils literal notranslate">ctypes</code> to invoke <code class="docutils literal notranslate">PyFrame_LocalsToFast</code> was subject to the state inconsistency problems discussed elsewhere in this PEP): <div class="highlight-default notranslate"><div class="highlight"><pre>def f(): a = None exec('a = 0', locals=sys._getframe().f_locals) print(a) # 0 f() </pre></div> </div> The behavior of <code class="docutils literal notranslate">exec()</code> and <code class="docutils literal notranslate">eval()</code> for module and class scopes (including nested invocations) is not changed, as the behaviour of <code class="docutils literal notranslate">locals()</code> in those scopes is not changing. </section> <section id="impact-on-other-code-execution-apis-in-the-standard-library"> <h4><a class="toc-backref" href="#impact-on-other-code-execution-apis-in-the-standard-library" role="doc-backlink">Impact on other code execution APIs in the standard library</a></h4> <code class="docutils literal notranslate">pdb</code> and <code class="docutils literal notranslate">bdb</code> use the <code class="docutils literal notranslate">frame.f_locals</code> API, and hence will be able to reliably update local variables even in optimized frames. Implementing this PEP will resolve several longstanding bugs in these modules relating to threads, generators, coroutines, and other mechanisms that allow concurrent code execution while the debugger is active. Other code execution APIs in the standard library (such as the <code class="docutils literal notranslate">code</code> module) do not implicitly access <code class="docutils literal notranslate">locals()</code> or <code class="docutils literal notranslate">frame.f_locals</code>, but the behaviour of explicitly passing these namespaces will change as described in the rest of this PEP (passing <code class="docutils literal notranslate">locals()</code> in optimized scopes will no longer implicitly share the code execution namespace across calls, passing <code class="docutils literal notranslate">frame.f_locals</code> in optimized scopes will allow reliable modification of local variables and nonlocal cell references). </section> </section> <section id="c-api-compatibility"> <h3><a class="toc-backref" href="#c-api-compatibility" role="doc-backlink">C API compatibility</a></h3> <section id="pyeval-getlocals-compatibility"> <h4><a class="toc-backref" href="#pyeval-getlocals-compatibility" role="doc-backlink"><code class="docutils literal notranslate">PyEval_GetLocals</code> compatibility</a></h4> <code class="docutils literal notranslate">PyEval_GetLocals()</code> has never historically distinguished between whether it was emulating <code class="docutils literal notranslate">locals()</code> or <code class="docutils literal notranslate">sys._getframe().f_locals</code> at the Python level, as they all returned references to the same shared cache of the local variable bindings. With this PEP, <code class="docutils literal notranslate">locals()</code> changes to return independent snapshots on each call for optimized frames, and <code class="docutils literal notranslate">frame.f_locals</code> (along with <code class="docutils literal notranslate">PyFrame_GetLocals</code>) changes to return new write-through proxy instances. Because <code class="docutils literal notranslate">PyEval_GetLocals()</code> returns a borrowed reference, it isn’t possible to update its semantics to align with either of those alternatives, leaving it as the only remaining API that requires a shared cache dictionary stored on the frame object. While this technically leaves the semantics of the function unchanged, it no longer allows extra dict entries to be made visible to users of the other APIs, as those APIs are no longer accessing the same underlying cache dictionary. When <code class="docutils literal notranslate">PyEval_GetLocals()</code> is being used as an equivalent to the Python <code class="docutils literal notranslate">locals()</code> builtin, <code class="docutils literal notranslate">PyEval_GetFrameLocals()</code> should be used instead. This code: <div class="highlight-default notranslate"><div class="highlight"><pre>locals = PyEval_GetLocals(); if (locals == NULL) { goto error_handler; } Py_INCREF(locals); </pre></div> </div> should be replaced with: <div class="highlight-default notranslate"><div class="highlight"><pre>// Equivalent to "locals()" in Python code locals = PyEval_GetFrameLocals(); if (locals == NULL) { goto error_handler; } </pre></div> </div> When <code class="docutils literal notranslate">PyEval_GetLocals()</code> is being used as an equivalent to calling <code class="docutils literal notranslate">sys._getframe().f_locals</code> in Python, it should be replaced by calling <code class="docutils literal notranslate">PyFrame_GetLocals()</code> on the result of <code class="docutils literal notranslate">PyEval_GetFrame()</code>. In these cases, the original code should be replaced with: <div class="highlight-default notranslate"><div class="highlight"><pre>// Equivalent to "sys._getframe()" in Python code frame = PyEval_GetFrame(); if (frame == NULL) { goto error_handler; } // Equivalent to "frame.f_locals" in Python code locals = PyFrame_GetLocals(frame); frame = NULL; // Minimise visibility of borrowed reference if (locals == NULL) { goto error_handler; } </pre></div> </div> </section> </section> <section id="impact-on-pep-709-inlined-comprehensions"> <h3><a class="toc-backref" href="#impact-on-pep-709-inlined-comprehensions" role="doc-backlink">Impact on PEP 709 inlined comprehensions</a></h3> For inlined comprehensions within a function, <code class="docutils literal notranslate">locals()</code> currently behaves the same inside or outside of the comprehension, and this will not change. The behavior of <code class="docutils literal notranslate">locals()</code> inside functions will generally change as specified in the rest of this PEP. For inlined comprehensions at module or class scope, calling <code class="docutils literal notranslate">locals()</code> within the inlined comprehension returns a new dictionary for each call. This PEP will make <code class="docutils literal notranslate">locals()</code> within a function also always return a new dictionary for each call, improving consistency; class or module scope inlined comprehensions will appear to behave as if the inlined comprehension is still a distinct function. </section> </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> Each read of <code class="docutils literal notranslate">frame.f_locals</code> will create a new proxy object that gives the appearance of being the mapping of local (including cell and free) variable names to the values of those local variables. A possible implementation is sketched out below. All attributes that start with an underscore are invisible and cannot be accessed directly. They serve only to illustrate the proposed design. <div class="highlight-default notranslate"><div class="highlight"><pre>NULL: Object # NULL is a singleton representing the absence of a value. class CodeType: _name_to_offset_mapping_impl: dict | NULL _cells: frozenset # Set of indexes of cell and free variables ... def __init__(self, ...): self._name_to_offset_mapping_impl = NULL self._variable_names = deduplicate( self.co_varnames + self.co_cellvars + self.co_freevars ) ... @property def _name_to_offset_mapping(self): "Mapping of names to offsets in local variable array." if self._name_to_offset_mapping_impl is NULL: self._name_to_offset_mapping_impl = { name: index for (index, name) in enumerate(self._variable_names) } return self._name_to_offset_mapping_impl class FrameType: _locals : array[Object] # The values of the local variables, items may be NULL. _extra_locals: dict | NULL # Dictionary for storing extra locals not in _locals. _locals_cache: FrameLocalsProxy | NULL # required to support PyEval_GetLocals() def __init__(self, ...): self._extra_locals = NULL self._locals_cache = NULL ... @property def f_locals(self): return FrameLocalsProxy(self) class FrameLocalsProxy: "Implements collections.MutableMapping." __slots__ = ("_frame", ) def __init__(self, frame:FrameType): self._frame = frame def __getitem__(self, name): f = self._frame co = f.f_code if name in co._name_to_offset_mapping: index = co._name_to_offset_mapping[name] val = f._locals[index] if val is NULL: raise KeyError(name) if index in co._cells val = val.cell_contents if val is NULL: raise KeyError(name) return val else: if f._extra_locals is NULL: raise KeyError(name) return f._extra_locals[name] def __setitem__(self, name, value): f = self._frame co = f.f_code if name in co._name_to_offset_mapping: index = co._name_to_offset_mapping[name] kind = co._local_kinds[index] if index in co._cells cell = f._locals[index] cell.cell_contents = val else: f._locals[index] = val else: if f._extra_locals is NULL: f._extra_locals = {} f._extra_locals[name] = val def __iter__(self): f = self._frame co = f.f_code yield from iter(f._extra_locals) for index, name in enumerate(co._variable_names): val = f._locals[index] if val is NULL: continue if index in co._cells: val = val.cell_contents if val is NULL: continue yield name def __contains__(self, item): f = self._frame if item in f._extra_locals: return True return item in co._variable_names def __len__(self): f = self._frame co = f.f_code res = 0 for index, _ in enumerate(co._variable_names): val = f._locals[index] if val is NULL: continue if index in co._cells: if val.cell_contents is NULL: continue res += 1 return len(self._extra_locals) + res </pre></div> </div> <section id="id1"> <h3><a class="toc-backref" href="#id1" role="doc-backlink">C API</a></h3> <code class="docutils literal notranslate">PyEval_GetLocals()</code> will be implemented roughly as follows: <div class="highlight-default notranslate"><div class="highlight"><pre>PyObject *PyEval_GetLocals(void) { PyFrameObject * = ...; // Get the current frame. if (frame->_locals_cache == NULL) { frame->_locals_cache = PyEval_GetFrameLocals(); } else { PyDict_Update(frame->_locals_cache, PyFrame_GetLocals(frame)); } return frame->_locals_cache; } </pre></div> </div> As with all functions that return a borrowed reference, care must be taken to ensure that the reference is not used beyond the lifetime of the object. </section> </section> <section id="implementation-notes"> <h2><a class="toc-backref" href="#implementation-notes" role="doc-backlink">Implementation Notes</a></h2> When accepted, the PEP text suggested that <code class="docutils literal notranslate">PyEval_GetLocals</code> would start returning a cached instance of the new write-through proxy, while the implementation sketch indicated it would continue to return a dictionary snapshot cached on the frame instance. This discrepancy was identified while implementing the PEP, and <a class="reference external" href="https://github.com/python/steering-council/issues/245#issuecomment-2179005461">resolved by the Steering Council</a> in favour of retaining the Python 3.12 behaviour of returning a dictionary snapshot cached on the frame instance. The PEP text has been updated accordingly. During the discussions of the C API clarification, it also became apparent that the rationale behind <code class="docutils literal notranslate">locals()</code> being updated to return independent snapshots in <a class="reference external" href="https://docs.python.org/3.13/glossary.html#term-optimized-scope" title="(in Python v3.13)">optimized scopes</a> wasn’t clear, as it had been inherited from the original <a class="pep reference internal" href="../pep-0558/" title="PEP 558 – Defined semantics for locals()">PEP 558</a> discussions rather than being independently covered in this PEP. The PEP text has been updated to better cover this change, with additional updates to the Specification and Backwards Compatibility sections to cover the impact on code execution APIs that default to executing code in the <code class="docutils literal notranslate">locals()</code> namespace. Additional motivation and rationale details have also been added to <a class="pep reference internal" href="../pep-0558/" title="PEP 558 – Defined semantics for locals()">PEP 558</a>. In 3.13.0, the write-through proxies did not allow deletion of even extra variables with <code class="docutils literal notranslate">del</code> and <code class="docutils literal notranslate">pop()</code>. This was subsequently reported as a <a class="reference external" href="https://github.com/python/cpython/issues/125590">compatibility regression</a>, and <a class="reference external" href="https://github.com/python/cpython/pull/125616">resolved</a> as now described in <a class="reference internal" href="#pep-667-f-locals-spec">The frame.f_locals attribute</a>. </section> <section id="comparison-with-pep-558"> <h2><a class="toc-backref" href="#comparison-with-pep-558" role="doc-backlink">Comparison with PEP 558</a></h2> This PEP and <a class="pep reference internal" href="../pep-0558/" title="PEP 558 – Defined semantics for locals()">PEP 558</a> shared a common goal: to make the semantics of <code class="docutils literal notranslate">locals()</code> and <code class="docutils literal notranslate">frame.f_locals()</code> intelligible, and their operation reliable. The key difference between this PEP and PEP 558 is that PEP 558 attempted to store extra variables inside a full internal dictionary copy of the local variables in an effort to improve backwards compatibility with the legacy <code class="docutils literal notranslate">PyEval_GetLocals()</code> API, whereas this PEP does not (it stores the extra local variables in a dedicated dictionary accessed solely via the new frame proxy objects, and copies them to the <code class="docutils literal notranslate">PyEval_GetLocals()</code> shared dict only when requested). PEP 558 did not specify exactly when that internal copy was updated, making the behavior of PEP 558 impossible to reason about in several cases where this PEP remains well specified. PEP 558 also proposed the introduction of some additional Python scope introspection interfaces to the C API that would allow extension modules to more easily determine whether the currently active Python scope is optimized or not, and hence whether the C API’s <code class="docutils literal notranslate">locals()</code> equivalent returns a direct reference to the frame’s local execution namespace or a shallow copy of the frame’s local variables and nonlocal cell references. Whether or not to add such introspection APIs is independent of the proposed changes to <code class="docutils literal notranslate">locals()</code> and <code class="docutils literal notranslate">frame.f_locals</code> and hence no such proposals have been included in this PEP. PEP 558 was <a class="pep reference internal" href="../pep-0558/#pep-withdrawal" title="PEP 558 – Defined semantics for locals() § PEP Withdrawal">ultimately withdrawn</a> in favour of this PEP. </section> <section id="reference-implementation"> <h2><a class="toc-backref" href="#reference-implementation" role="doc-backlink">Reference Implementation</a></h2> The implementation is in development as a <a class="reference external" href="https://github.com/python/cpython/pull/115153">draft pull request on GitHub</a>. </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0667.rst">https://github.com/python/peps/blob/main/peps/pep-0667.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0667.rst">2024-10-27 07:11:46 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#making-the-frame-f-locals-attribute-a-write-through-proxy">Making the <code class="docutils literal notranslate">frame.f_locals</code> attribute a write-through proxy</a></li> <li><a class="reference internal" href="#making-the-locals-builtin-return-independent-snapshots">Making the <code class="docutils literal notranslate">locals()</code> builtin return independent snapshots</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#python-api">Python API</a><ul> <li><a class="reference internal" href="#the-frame-f-locals-attribute">The <code class="docutils literal notranslate">frame.f_locals</code> attribute</a></li> <li><a class="reference internal" href="#the-locals-builtin">The <code class="docutils literal notranslate">locals()</code> builtin</a></li> <li><a class="reference internal" href="#the-eval-and-exec-builtins">The <code class="docutils literal notranslate">eval()</code> and <code class="docutils literal notranslate">exec()</code> builtins</a></li> </ul> </li> <li><a class="reference internal" href="#c-api">C API</a><ul> <li><a class="reference internal" href="#additions-to-the-pyeval-c-api">Additions to the <code class="docutils literal notranslate">PyEval</code> C API</a></li> <li><a class="reference internal" href="#pyframe-getlocals-c-api"><code class="docutils literal notranslate">PyFrame_GetLocals</code> C API</a></li> <li><a class="reference internal" href="#deprecated-c-apis">Deprecated C APIs</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#summary-of-changes">Summary of Changes</a><ul> <li><a class="reference internal" href="#python-api-changes">Python API changes</a><ul> <li><a class="reference internal" href="#frame-f-locals-changes"><code class="docutils literal notranslate">frame.f_locals</code> changes</a></li> <li><a class="reference internal" href="#locals-changes"><code class="docutils literal notranslate">locals()</code> changes</a></li> <li><a class="reference internal" href="#eval-and-exec-changes"><code class="docutils literal notranslate">eval()</code> and <code class="docutils literal notranslate">exec()</code> changes</a></li> </ul> </li> <li><a class="reference internal" href="#c-api-changes">C API changes</a><ul> <li><a class="reference internal" href="#pyframe-getlocals-change"><code class="docutils literal notranslate">PyFrame_GetLocals</code> change</a></li> <li><a class="reference internal" href="#pyeval-getlocals-change"><code class="docutils literal notranslate">PyEval_GetLocals</code> change</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a><ul> <li><a class="reference internal" href="#python-api-compatibility">Python API compatibility</a></li> <li><a class="reference internal" href="#frame-f-locals-compatibility"><code class="docutils literal notranslate">frame.f_locals</code> compatibility</a><ul> <li><a class="reference internal" href="#locals-compatibility"><code class="docutils literal notranslate">locals()</code> compatibility</a></li> <li><a class="reference internal" href="#impact-on-exec-and-eval">Impact on <code class="docutils literal notranslate">exec()</code> and <code class="docutils literal notranslate">eval()</code></a></li> <li><a class="reference internal" href="#impact-on-other-code-execution-apis-in-the-standard-library">Impact on other code execution APIs in the standard library</a></li> </ul> </li> <li><a class="reference internal" href="#c-api-compatibility">C API compatibility</a><ul> <li><a class="reference internal" href="#pyeval-getlocals-compatibility"><code class="docutils literal notranslate">PyEval_GetLocals</code> compatibility</a></li> </ul> </li> <li><a class="reference internal" href="#impact-on-pep-709-inlined-comprehensions">Impact on PEP 709 inlined comprehensions</a></li> </ul> </li> <li><a class="reference internal" href="#implementation">Implementation</a><ul> <li><a class="reference internal" href="#id1">C API</a></li> </ul> </li> <li><a class="reference internal" href="#implementation-notes">Implementation Notes</a></li> <li><a class="reference internal" href="#comparison-with-pep-558">Comparison with PEP 558</a></li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0667.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>