Creating Variables using frame.f_locals

[kliu04]

Bug report

Bug description:

PEP 667 states: "frame.f_locals gives read/write access to the local variables in all scopes, including optimized scopes" and "the view object [...] implement the following mutable mapping operations:

• using assignment to add new key/value pairs
• using assignment to update the value associated with a key

All writes to the f_locals mapping will be immediately visible in the underlying variables."

However, creating a variable in an optimized scope causes a crash:

import inspect

def foo():
    frame = inspect.currentframe()
    frame.f_locals["x"] = 1
    print(x)


foo()

yields NameError: name 'x' is not defined

Creating a variable outside of an optimized scope is fine:

import inspect

frame = inspect.currentframe()
frame.f_locals["x"] = 1
print(x)

yields 1.

CPython versions tested on:

3.13

Operating systems tested on:

macOS

[picnixz]

I think it's not meant to work that way (https://peps.python.org/pep-0667/#frame-f-locals-changes):

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)

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.

[RandoNandoz]

Can PEPs be changed? It would be good to clarify in documentation that locals() doesn't behave in the same way as globals(), as changes to the globals() table does create new global variables that are accessible at the code-level.

[kliu04]

Now that I read the PEP again, it seems it is "intended" behaviour that changing f_locals does not create variables, since the "mutability" refers to the mutability of the underlying map and not the actual locals. However, the PEP states: "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", but what is the point of being able to add k-v pairs that do not have any effect?

Also, as @RandoNandoz said above, it's possible to create variables with frame.f_globals but not with f_locals, why is there a difference?

[picnixz]

but what is the point of being able to add k-v pairs that do not have any effect?

One reason is: for debuggers:

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

The purpose of the PEP is not to be able to create variables on the fly but to be able to store state in the frame.

it's possible to create variables with frame.f_globals but not with f_locals, why is there a difference?

Unfortunately I can't answer for that (maybe @gaogaotiantian can?)

[gaogaotiantian]

First of all, it's the expected behavior so no bug here.

It's infeasible to add a real local variable in optimized scope during runtime in CPython. You need to change a lot of the underlying structure to do that.

For unoptimized scopes (globals/class definition), the namespace is a pure dict so you can basically add any variable you like to it.

it's possible to create variables with frame.f_globals but not with f_locals, why is there a difference?

So the difference is how they work. One is a real dict, the other is not.

Can PEPs be changed?

They can, but we don't normally do it. PEPs should not be used as documentation. PEP is a historic file recording the proposal when it was accepted. The bahavior could be changed during implementation or later improvement. You should refer to the latest documentation (I believe for locals()) for the current behavior.

but what is the point of being able to add k-v pairs that do not have any effect?

It allows you to do something like

import sys
def f():
    f_locals = sys._getframe().f_locals
    exec("x = 0", locals=f_locals)
    exec("print(x)", locals=f_locals)
f()

If you think about it, that's how you can do

(Pdb) x = 0
(Pdb) print(x)