frame.f_locals 属性

对于模块和类作用域（包括 exec() 和 eval() 调用），frame.f_locals 是对代码执行中使用的局部变量命名空间的直接引用。

对于函数作用域（以及其他 优化作用域），它将是新的直写代理类型的一个实例，可以直接修改底层帧中优化的局部变量存储数组，以及对非局部变量的任何单元格引用的内容。

视图对象完整实现了 collections.abc.Mapping 接口，并且还实现了以下可变映射操作

• 使用赋值添加新的键/值对
• 使用赋值更新与键关联的值
• 通过 setdefault() 方法进行条件赋值
• 通过 update() 方法进行批量更新

即使内容相同，不同帧的视图也会比较不相等。

对 f_locals 映射的所有写入将立即在底层变量中可见。对底层变量的所有更改将立即在映射中可见。

f_locals 对象将是一个完整的映射，可以向其中添加任意键值对。通过代理添加的新名称将存储在底层帧对象上专门的共享字典中（因此给定帧的所有代理实例将能够访问以这种方式添加的任何名称）。

多余的键（不对应于底层帧上的局部变量）可以像往常一样通过 del 语句或 pop() 方法删除。

不支持使用 del 或 pop() 方法删除对应于底层帧上局部变量的键，尝试这样做将引发 ValueError。局部变量只能通过代理设置为 None（或其他值），不能完全解除绑定。

直写代理上未实现 clear() 方法，因为不清楚它应如何处理无法删除与局部变量对应的条目。

为了保持向后兼容性，需要生成新映射的代理 API（例如 copy()）将生成常规的内置 dict 实例，而不是直写代理实例。

为了避免在帧对象和直写代理之间引入循环引用，每次访问 frame.f_locals 都会返回一个*新的*直写代理实例。

locals() 内建函数

locals() 将定义为

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

对于模块和类作用域（包括 exec() 和 eval() 调用），locals() 继续返回对代码执行中使用的局部变量命名空间的直接引用（该值也与 frame.f_locals 报告的值相同）。

在 优化作用域 中，每次调用 locals() 都将生成一个*独立的*局部变量快照。

eval() 和 exec() 内建函数

因为此 PEP 更改了 locals() 的行为，所以 eval() 和 exec() 的行为也随之改变。

假设有一个函数 _eval() 执行 eval() 的工作，并带有显式命名空间参数，则 eval() 可以定义如下

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)

exec() 的指定参数处理也类似更新。

（在 Python 3.12 及更早版本中，无法向 eval() 或 exec() 提供 locals 而不提供 globals，因为这些以前是仅限位置参数。独立于此 PEP，Python 3.13 更新了这些内置函数以接受关键字参数）

PyEval C API 的补充

将添加三个新的 C-API 函数

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

PyEval_GetFrameLocals() 等同于： locals()。 PyEval_GetFrameGlobals() 等同于： globals()。

所有这些函数都将返回一个新引用。

PyFrame_GetLocals C API

现有的 PyFrame_GetLocals(f) C API 等同于 f.f_locals。其返回值将如上文访问 f.f_locals 所述。

此函数返回一个新引用，因此它能够适应在优化作用域中每次调用时创建新的直写代理实例。

已弃用的 C API

以下 C API 函数将被弃用，因为它们返回借用引用

PyEval_GetLocals()
PyEval_GetGlobals()
PyEval_GetBuiltins()

应使用以下函数（返回新引用）来代替

PyEval_GetFrameLocals()
PyEval_GetFrameGlobals()
PyEval_GetFrameBuiltins()

以下 C API 函数将变为无操作，并被弃用而无替代

PyFrame_FastToLocalsWithError()
PyFrame_FastToLocals()
PyFrame_LocalsToFast()

所有已弃用的函数都将在 Python 3.13 文档中标记为已弃用。

在这些函数中，只有 PyEval_GetLocals() 带来显著的维护负担。因此，对 PyEval_GetLocals() 的调用将在 Python 3.14 中发出 DeprecationWarning，目标删除日期为 Python 3.16（Python 3.14 之后的两个版本）。建议使用替代方案，如 PyEval_GetLocals 兼容性 中所述。

frame.f_locals 变更

考虑以下示例

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)

鉴于本 PEP 中的更改，test() 将打印 {'x': 2, 'y': 4, 'z': 5} 2。

在 Python 3.12 中，此示例将因 UnboundLocalError 而失败，因为通过 l()['y'] = 4 对 y 的定义丢失了。

如果倒数第二行从 y 更改为 z，这仍将引发 NameError，就像在 Python 3.12 中一样。添加到 frame.f_locals 中不是词法局部变量的键在 frame.f_locals 中仍然可见，但不会动态地成为局部变量。

locals() 变更

考虑以下示例

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

鉴于本 PEP 中的更改，这将*始终*打印 None（无论 x 是否是函数中定义的局部变量），因为对 locals() 的显式调用会生成一个与 exec() 调用中隐式使用的快照不同的快照。

在 Python 3.12 中，所示的精确示例将打印 1，但与所涉及函数的定义看似无关的更改可能会使其打印 None（PEP 558 中的 在优化作用域中 eval() 和 exec() 的额外考虑 对该主题进行了更详细的讨论）。

eval() 和 exec() 变更

影响 eval() 和 exec() 的主要变化显示在“locals() 更改”示例中：在优化作用域中重复访问 locals() 将不再隐式共享一个共同的底层命名空间。

PyFrame_GetLocals 变更

PyFrame_GetLocals 在 Python 3.12 中已经可以返回任意映射，因为 exec() 和 eval() 接受任意映射作为其 locals 参数，并且元类可以从其 __prepare__ 方法返回任意映射。

在优化作用域中返回帧局部变量代理只是增加了另一种情况，即会返回内置字典以外的东西。

PyEval_GetLocals 变更

PyEval_GetLocals() 的语义在技术上没有改变，但实际上它们发生了变化，因为优化帧上缓存的字典不再与访问帧局部变量的其他机制（locals() 内建函数、PyFrame_GetLocals 函数、帧 f_locals 属性）共享。

locals() 兼容性

对于优化帧，locals() is locals() 将为 False，因此以下代码将引发 KeyError 而不是返回 1

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

为了继续工作，此类代码需要显式将要修改的命名空间存储在局部变量中，而不是依赖于帧对象上先前的隐式缓存

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

虽然这在技术上不是正式的向后兼容性破坏（因为写回 locals() 的行为明确记录为未定义），但确实有一些代码依赖于现有行为。因此，更新后的行为将在文档中明确注明为更改，并将在 Python 3.13 移植指南中涵盖。

为了在所有版本上使用优化作用域中 locals() 的副本，而不在 Python 3.13+ 上进行冗余复制，用户需要定义一个版本相关的辅助函数，该函数仅在 Python 3.13 之前的 Python 版本上进行显式复制

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

在其他作用域中，locals().copy() 可以继续无条件调用，而不会引入任何冗余副本。

对 exec() 和 eval() 的影响

尽管此 PEP 未直接修改 exec() 或 eval()，但 locals() 的语义更改会影响 exec() 和 eval() 的行为，因为它们默认在调用命名空间中运行代码。

这给某些代码带来了潜在的兼容性问题，因为在以前的实现中，当 locals() 在函数作用域中被多次调用时，返回的是同一个字典，所以以下代码通常会由于隐式共享的局部变量命名空间而工作

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

根据本 PEP 对 locals() 的语义更改，exec('print(a)')' 调用将因 NameError 而失败，并且 print(locals()) 将报告一个空字典，因为每一行都将使用其自己独立的局部变量快照，而不是隐式共享存储在帧对象上的单个缓存快照。

通过使用显式命名空间而不是依赖以前隐式共享的帧命名空间，仍然可以在 exec() 调用之间获得共享命名空间

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

您甚至可以通过显式使用 frame.f_locals 来可靠地更改局部作用域中的变量，这在以前是不可能实现的（即使使用 ctypes 调用 PyFrame_LocalsToFast 也受本 PEP 其他部分讨论的状态不一致问题的影响）

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

exec() 和 eval() 对于模块和类作用域（包括嵌套调用）的行为没有改变，因为 locals() 在这些作用域中的行为没有改变。

对标准库中其他代码执行 API 的影响

pdb 和 bdb 使用 frame.f_locals API，因此即使在优化帧中也能够可靠地更新局部变量。实施此 PEP 将解决这些模块中与线程、生成器、协程以及在调试器活动时允许并发代码执行的其他机制相关的几个长期存在的错误。

标准库中的其他代码执行 API（例如 code 模块）不会隐式访问 locals() *或* frame.f_locals，但显式传递这些命名空间的行为将按本 PEP 其余部分所述进行更改（在优化作用域中传递 locals() 将不再隐式共享跨调用的代码执行命名空间，在优化作用域中传递 frame.f_locals 将允许可靠地修改局部变量和非局部单元格引用）。

PyEval_GetLocals 兼容性

PyEval_GetLocals() 历史上从未区分它是在 Python 级别模拟 locals() 还是 sys._getframe().f_locals，因为它们都返回对局部变量绑定的同一共享缓存的引用。

根据本 PEP，locals() 更改为在每次调用优化帧时返回独立的快照，而 frame.f_locals（以及 PyFrame_GetLocals）更改为返回新的直写代理实例。

由于 PyEval_GetLocals() 返回一个借用引用，因此无法更新其语义以与这些替代方案中的任何一个对齐，使其成为唯一需要存储在帧对象上的共享缓存字典的剩余 API。

虽然这在技术上使函数的语义保持不变，但它不再允许将额外的字典条目暴露给其他 API 的用户，因为这些 API 不再访问相同的底层缓存字典。

当 PyEval_GetLocals() 被用作 Python locals() 内建函数的等价物时，应该使用 PyEval_GetFrameLocals() 来代替。

这段代码

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

应该替换为

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

当 PyEval_GetLocals() 被用作 Python 中调用 sys._getframe().f_locals 的等价物时，它应该替换为在 PyEval_GetFrame() 的结果上调用 PyFrame_GetLocals()。

在这些情况下，原始代码应替换为

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