Text of peps.python.org › pep-0667 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 667 – Consistent views of namespaces | peps.python.org

PEP 667 – Consistent views of namespaces PEP 667 – Consistent views of namespaces Author : Mark Shannon <mark at hotpy.org>, Tian Gao <gaogaotiantian at hotmail.com> Discussions-To : Discourse thread Status : Final Type : Standards Track Created : 30-Jul-2021 Python-Version : 3.13 Post-History : 20-Aug-2021, 22-Feb-2024 Resolution : 25-Apr-2024 Table of Contents Abstract Motivation Rationale Making the frame.f_locals attribute a write-through proxy Making the locals() builtin return independent snapshots Specification Python API The frame.f_locals attribute The locals() builtin The eval() and exec() builtins C API Additions to the PyEval C API PyFrame_GetLocals C API Deprecated C APIs Summary of Changes Python API changes frame.f_locals changes locals() changes eval() and exec() changes C API changes PyFrame_GetLocals change PyEval_GetLocals change Backwards Compatibility Python API compatibility frame.f_locals compatibility locals() compatibility Impact on exec() and eval() Impact on other code execution APIs in the standard library C API compatibility PyEval_GetLocals compatibility Impact on PEP 709 inlined comprehensions Implementation C API Implementation Notes Comparison with PEP 558 Reference Implementation Copyright Important This PEP is a historical document.

The up-to-date, canonical documentation can now be found at locals() . × See PEP 1 for how to propose changes. Abstract 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 locals() and frame.f_locals 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 frame.f_locals will always be visible in the underlying variables. Modifications to local variables will immediately be visible in frame.f_locals , and they will be consistent regardless of threading or coroutines. The locals() 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 frame.f_locals rather than implicitly refreshing a single shared dictionary cached on the frame object.

Motivation The implementation of locals() and frame.f_locals 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: class C : x = 1 sys . _getframe () . f_locals [ 'x' ] = 2 print ( x ) prints 2 , but: def f (): x = 1 sys . _getframe () . f_locals [ 'x' ] = 2 print ( x ) f () prints 1 .

This is inconsistent, and confusing. Worse than that, the Python 3.12 behavior can result in strange bugs . With this PEP both examples would print 2 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 locals() builtin has its own undesirable behaviours.

Refer to PEP 558 for additional details on those concerns. Rationale Making the frame.f_locals attribute a write-through proxy The Python 3.12 implementation of frame.f_locals returns a dictionary that is created on the fly from the array of local variables. The PyFrame_LocalsToFast() 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 f_locals frame attribute may not show up as modifications to local variables if PyFrame_LocalsToFast() 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 frame.f_locals return a view on the underlying frame, these problems go away. frame.f_locals is always in sync with the frame because it is a view of it, not a copy of it. Making the locals() builtin return independent snapshots PEP 558 considered three potential options for standardising the behavior of the locals() builtin in optimized scopes : retain the historical behaviour of having each call to locals() on a given frame update a single shared snapshot of the local variables make locals() return write-through proxy instances (similar to frame.f_locals ) make locals() return genuinely independent snapshots so that attempts to change the values of local variables via exec() would be consistently ignored rather than being accepted in some circumstances The last option was chosen as the one which could most easily be explained in the language reference, and memorised by users: the locals() builtin gives an instantaneous snapshot of the local variables in optimized scopes, and read/write access in other scopes; and frame.f_locals gives read/write access to the local variables in all scopes, including optimized scopes 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 PEP 558 , especially the Motivation section and Additional considerations for eval() and exec() in optimized scopes . This approach is not without its drawbacks, which are covered in the Backwards Compatibility section below. Specification Python API The frame.f_locals attribute For module and class scopes (including exec() and eval() invocations), frame.f_locals is a direct reference to the local variable namespace used in code execution.

For function scopes (and other optimized scopes ) 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 collections.abc.Mapping interface, and also implement the following mutable mapping operations: using assignment to add new key/value pairs using assignment to update the value associated with a key conditional assignment via the setdefault() method bulk updates via the update() method Views of different frames compare unequal even if they have the same contents.

All writes to the f_locals mapping will be immediately visible in the underlying variables. All changes to the underlying variables will be immediately visible in the mapping. The f_locals 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 del statements or the pop() method. Using del , or the pop() method, to remove keys that correspond to local variables on the underlying frame is NOT supported, and attempting to do so will raise ValueError . Local variables can only be set to None (or some other value) via the proxy, they cannot be unbound completely.

The clear() 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 compatibi

The rest of this page is on the live site.