帧对象 — Python 3.14.5 文档
Description: 可以使用函数 PyEval_GetFrame() 与 PyThreadState_GetFrame() 去获取一个帧对象。 另请参阅 Reflection 。 Frame locals proxies: 帧对象 的 f_locals 属性是“帧 locals 代理”的一个实例。 该代理对象将对外公开一个下层帧 locals 字典的直写视图。这确保了由 f_locals 暴露的变量总是与帧本身...

# 帧对象

type PyFrameObject
  属于 受限 API （作为不透明的结构体）.

  用于描述帧对象的对象的 C 结构体。

  此结构体中无公有成员。

  在 3.11 版本发生变更: 此结构体的成员已从公有 C API 中移除。请参阅 What's New entry 了解详情。

可以使用函数 `PyEval_GetFrame()` 与 `PyThreadState_GetFrame()` 去获取一个帧对象。

另请参阅 Reflection。

PyTypeObject PyFrame_Type

  帧对象的类型。它与 Python 层中的 `types.FrameType` 是同一对象。

  在 3.11 版本发生变更: 在之前版本中，此类型仅在包含 `<frameobject.h>` 之后可用。

PyFrameObject *PyFrame_New(PyThreadState *tstate, PyCodeObject *code, PyObject *globals, PyObject *locals)

  新建一个帧对象。此函数成功时将返回一个指向新帧对象的 strong reference，失败时则返回 `NULL` 并设置一个异常。

int PyFrame_Check(PyObject *obj)

  如果 obj 是一个帧对象则返回非零值。

  在 3.11 版本发生变更: 在之前版本中，此函数仅在包含 `<frameobject.h>` 之后可用。

PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)
  返回值：新的引用。

  获取 frame 的下一个外部帧。

  返回一个 strong reference，或者如果 frame 没有外部帧则返回 `NULL`。 此函数不会引发异常。

  Added in version 3.9.

PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)
  返回值：新的引用。

  获取 frame 的 `f_builtins` 属性。

  返回一个 strong reference。此结果不可为 `NULL`。

  Added in version 3.11.

PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)
  返回值：新的引用。 属于 稳定 ABI 自 3.10 版起.

  获取 frame 的代码。

  返回一个 strong reference。

  结果（帧代码）不可为 `NULL`。

  Added in version 3.9.

PyObject *PyFrame_GetGenerator(PyFrameObject *frame)
  返回值：新的引用。

  获取拥有该帧的生成器、协程或异步生成器，或者如果该帧不被某个生成器所拥有则为 `NULL`。不会引发异常，即使其返回值为 `NULL`。

  返回一个 strong reference，或者 `NULL`。

  Added in version 3.11.

PyObject *PyFrame_GetGlobals(PyFrameObject *frame)
  返回值：新的引用。

  获取 frame 的 `f_globals` 属性。

  返回一个 strong reference。此结果不可为 `NULL`。

  Added in version 3.11.

int PyFrame_GetLasti(PyFrameObject *frame)

  获取 frame 的 `f_lasti` 属性。

  如果 `frame.f_lasti` 为 `None` 则返回 -1。

  Added in version 3.11.

PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)
  返回值：新的引用。

  获取 frame 的变量 name。

  - 成功时返回一个指向变量值的 strong reference。

  - 如果该变量不存在，则引发 `NameError` 并返回 `NULL`。

  - 如果出错，则引发异常并返回 `NULL`。

  name 必须是 `str` 类型的。

  Added in version 3.12.

PyObject *PyFrame_GetVarString(PyFrameObject *frame, const char *name)
  返回值：新的引用。

  和 `PyFrame_GetVar()` 相似，但该变量名是一个使用 UTF-8 编码的 C 字符串。

  Added in version 3.12.

PyObject *PyFrame_GetLocals(PyFrameObject *frame)
  返回值：新的引用。

  获取 frame 的 `f_locals` 属性。如果该帧指向一个 optimized scope，这将返回一个允许修改 locals 的直写代理对象。在所有其他情况下 (类、模块、`exec()`、`eval()`) 它将直接返回代表该帧的 locals 的映射 (如为 `locals()` 所描述的)。

  返回一个 strong reference。

  Added in version 3.11.

  在 3.13 版本发生变更: 作为 PEP 667 的组成部分，返回一个 `PyFrameLocalsProxy_Type` 的实例。

int PyFrame_GetLineNumber(PyFrameObject *frame)
  属于 稳定 ABI 自 3.10 版起.

  返回 frame 当前正在执行的行号。

## Frame locals proxies

Added in version 3.13.

帧对象 的 `f_locals` 属性是“帧 locals 代理”的一个实例。 该代理对象将对外公开一个下层帧 locals 字典的直写视图。这确保了由 `f_locals` 暴露的变量总是与帧本身的现有局部变量内容一致。

请参阅 PEP 667 了解详情。

PyTypeObject PyFrameLocalsProxy_Type

  帧 `locals()` 代理对象的类型。

int PyFrameLocalsProxy_Check(PyObject *obj)

  如果 obj 是一个帧 `locals()` 代理则返回非零值。

## Legacy local variable APIs

这些 API 已处于 soft deprecated 状态。从 Python 3.13 起，它们不做任何事。 它们的存在只是为了向下兼容。

void PyFrame_LocalsToFast(PyFrameObject *f, int clear)

  在 Python 3.13 之前，此函数会将 f 的 `f_locals` 属性拷贝至内部的由局部变量组成的 "fast" 数组，以允许在帧对象中的变化对解释器可见。如果 clear 为真值，此函数将处理在 locals 字典中未设置的变量。

  自 3.13 版起已处于 Soft deprecated 状态: 此函数现在不执行任何操作。

void PyFrame_FastToLocals(PyFrameObject *f)

  在 Python 3.13 之前，此函数会将内部的由（供解释器使用的）局部变量组成的 "fast" 数组拷贝至 f 的 `f_locals` 属性，以允许在局部变量中的变化对帧对象可见。

  自 3.13 版起已处于 Soft deprecated 状态: 此函数现在不执行任何操作。

int PyFrame_FastToLocalsWithError(PyFrameObject *f)

  在 Python 3.13 之前，此函数类似于 `PyFrame_FastToLocals()`，但成功时返回 `0`，而在失败时返回 `-1` 并设置一个异常。

  自 3.13 版起已处于 Soft deprecated 状态: 此函数现在不执行任何操作。

参见

PEP 667

## Internal frames

除非使用 PEP 523，否则你不会需要它。

struct _PyInterpreterFrame

  解释器的内部帧表示。

  Added in version 3.11.

PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);
  这是 不稳定 API。它可能在次要版本中不经警告地被更改。

  > 返回一个指向帧的代码对象的 strong reference。

  Added in version 3.12.

int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);
  这是 不稳定 API。它可能在次要版本中不经警告地被更改。

  返回最后执行的指令的字节偏移量。

  Added in version 3.12.

int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);
  这是 不稳定 API。它可能在次要版本中不经警告地被更改。

  返回当前正在执行的行号，如果没有行号则返回 -1。

  Added in version 3.12.