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 compatibility, proxy APIs that need to produce a new mapping (such as copy()) will produce regular builtin dict instances, rather than write-through proxy instances.

To avoid introducing a circular reference between frame objects and the write-through proxies, each access to frame.f_locals returns a new write-through proxy instance.

The locals() builtin

locals() will be defined as:

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

For module and class scopes (including exec() and eval() invocations), locals() continues to return a direct reference to the local variable namespace used in code execution (which is also the same value reported by frame.f_locals).

In optimized scopes, each call to locals() will produce an independent snapshot of the local variables.

The eval() and exec() builtins

Because this PEP changes the behavior of locals(), the behavior of eval() and exec() also changes.

Assuming a function _eval() which performs the job of eval() with explicit namespace arguments, eval() can be defined as follows:

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)

The specified argument handling for exec() is similarly updated.

(In Python 3.12 and earlier, it was not possible to provide locals to eval() or exec() without also providing globals as these were previously positional-only arguments. Independently of this PEP, Python 3.13 updated these builtins to accept keyword arguments)

Additions to the PyEval C API

Three new C-API functions will be added:

PyObject *PyEval_GetFrameLocals(void)
PyObject *PyEval_GetFrameGlobals(void)
PyObject *PyEval_GetFrameBuiltins(void)

PyEval_GetFrameLocals() is equivalent to: locals(). PyEval_GetFrameGlobals() is equivalent to: globals().

All of these functions will return a new reference.

PyFrame_GetLocals C API

The existing PyFrame_GetLocals(f) C API is equivalent to f.f_locals. Its return value will be as described above for accessing f.f_locals.

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.

Deprecated C APIs

The following C API functions will be deprecated, as they return borrowed references:

PyEval_GetLocals()
PyEval_GetGlobals()
PyEval_GetBuiltins()

The following functions (which return new references) should be used instead:

PyEval_GetFrameLocals()
PyEval_GetFrameGlobals()
PyEval_GetFrameBuiltins()

The following C API functions will become no-ops, and will be deprecated without replacement:

PyFrame_FastToLocalsWithError()
PyFrame_FastToLocals()
PyFrame_LocalsToFast()

All of the deprecated functions will be marked as deprecated in the Python 3.13 documentation.

Of these functions, only PyEval_GetLocals() poses any significant maintenance burden. Accordingly, calls to PyEval_GetLocals() will emit DeprecationWarning 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 PyEval_GetLocals compatibility.

frame.f_locals changes

Consider the following example:

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)

Given the changes in this PEP, test() will print {'x': 2, 'y': 4, 'z': 5} 2.

In Python 3.12, this example will fail with an UnboundLocalError, as the definition of y by l()['y'] = 4 is lost.

If the second-to-last line were changed from y to z, this will still raise NameError, as it does in Python 3.12. Keys added to frame.f_locals that are not lexically local variables remain visible in frame.f_locals, but do not dynamically become local variables.

locals() changes

Consider the following example:

def f():
    exec("x = 1")
    print(locals().get("x"))
f()

Given the changes in this PEP, this will always print None (regardless of whether x is a defined local variable in the function), as the explicit call to locals() produces a distinct snapshot from the one implicitly used in the exec() call.

In Python 3.12, the exact example shown would print 1, but seemingly unrelated changes to the definition of the function involved could make it print None instead (Additional considerations for eval() and exec() in optimized scopes in PEP 558 goes into more detail on that topic).

eval() and exec() changes

The primary change affecting eval() and exec() is shown in the “locals() changes” example: repeatedly accessing locals() in an optimized scope will no longer implicitly share a common underlying namespace.

PyFrame_GetLocals change

PyFrame_GetLocals can already return arbitrary mappings in Python 3.12, as exec() and eval() accept arbitrary mappings as their locals argument, and metaclasses may return arbitrary mappings from their __prepare__ methods.

Returning a frame locals proxy in optimized scopes just adds another case where something other than a builtin dictionary will be returned.

PyEval_GetLocals change

The semantics of PyEval_GetLocals() 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 (locals() builtin, PyFrame_GetLocals function, frame f_locals attributes).

locals() compatibility

locals() is locals() will be False for optimized frames, so code like the following will raise KeyError instead of returning 1:

def f():
    locals()["x"] = 1
    return locals()["x"]

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:

def f():
    ns = {}
    ns["x"] = 1
    return ns["x"]

While this technically isn’t a formal backwards compatibility break (since the behaviour of writing back to locals() 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 locals() 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:

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

In other scopes, locals().copy() can continue to be called unconditionally without introducing any redundant copies.

Impact on exec() and eval()

Even though this PEP does not modify exec() or eval() directly, the semantic change to locals() impacts the behavior of exec() and eval() 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 locals() is called multiple times in function scope, the following code usually worked due to the implicitly shared local variable namespace:

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()

With the semantic changes to locals() in this PEP, the exec('print(a)')' call will fail with NameError, and print(locals()) 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 exec() calls can still be obtained by using explicit namespaces rather than relying on the previously implicitly shared frame namespace:

def f():
    ns = {}
    exec('a = 0', locals=ns)
    exec('print(a)', locals=ns)  # 0
f()

You can even reliably change the variables in the local scope by explicitly using frame.f_locals, which was not possible before (even using ctypes to invoke PyFrame_LocalsToFast was subject to the state inconsistency problems discussed elsewhere in this PEP):

def f():
    a = None
    exec('a = 0', locals=sys._getframe().f_locals)
    print(a)  # 0
f()

The behavior of exec() and eval() for module and class scopes (including nested invocations) is not changed, as the behaviour of locals() in those scopes is not changing.

Impact on other code execution APIs in the standard library

pdb and bdb use the frame.f_locals 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 module) do not implicitly access locals() or frame.f_locals, but the behaviour of explicitly passing these namespaces will change as described in the rest of this PEP (passing locals() in optimized scopes will no longer implicitly share the code execution namespace across calls, passing frame.f_locals in optimized scopes will allow reliable modification of local variables and nonlocal cell references).

PyEval_GetLocals compatibility

PyEval_GetLocals() has never historically distinguished between whether it was emulating locals() or sys._getframe().f_locals at the Python level, as they all returned references to the same shared cache of the local variable bindings.

With this PEP, locals() changes to return independent snapshots on each call for optimized frames, and frame.f_locals (along with PyFrame_GetLocals) changes to return new write-through proxy instances.

Because PyEval_GetLocals() 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 PyEval_GetLocals() is being used as an equivalent to the Python locals() builtin, PyEval_GetFrameLocals() should be used instead.

This code:

locals = PyEval_GetLocals();
if (locals == NULL) {
    goto error_handler;
}
Py_INCREF(locals);

should be replaced with:

// Equivalent to "locals()" in Python code
locals = PyEval_GetFrameLocals();
if (locals == NULL) {
    goto error_handler;
}

When PyEval_GetLocals() is being used as an equivalent to calling sys._getframe().f_locals in Python, it should be replaced by calling PyFrame_GetLocals() on the result of PyEval_GetFrame().

In these cases, the original code should be replaced with:

// 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;
}