帧对象

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.

const PyTypeObject *PyUnstable_ExecutableKinds

这是 不稳定 API。它可能在次要版本中不经警告地被更改。

An array of executable kinds (executor types) for frames, used for internal debugging and tracing.

Tools like debuggers and profilers can use this to identify the type of execution context associated with a frame (such as to filter out internal frames). The entries are indexed by the following constants:

Constant	Description
PyUnstable_EXECUTABLE_KIND_SKIP 这是 不稳定 API。它可能在次要版本中不经警告地被更改。	The frame is internal (For example: inlined) and should be skipped by tools.
PyUnstable_EXECUTABLE_KIND_PY_FUNCTION 这是 不稳定 API。它可能在次要版本中不经警告地被更改。	The frame corresponds to a standard Python function.
PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION 这是 不稳定 API。它可能在次要版本中不经警告地被更改。	The frame corresponds to a function defined in native code.
PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR 这是 不稳定 API。它可能在次要版本中不经警告地被更改。	The frame corresponds to a method on a class instance.

However, Python's C API lacks a function to read the executable kind from a frame. Instead, use this recipe:

int
get_executable_kind(PyFrameObject *frame)
{
   _PyInterpreterFrame *f = frame->f_frame;
   PyObject *exec = PyStackRef_AsPyObjectBorrow(f->f_executable);

   if (PyCode_Check(exec)) {
      return PyUnstable_EXECUTABLE_KIND_PY_FUNCTION;
   }
   if (PyMethod_Check(exec)) {
      return PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION;
   }
   if (Py_IS_TYPE(exec, &PyMethodDescr_Type)) {
      return PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR;
   }

   return PyUnstable_EXECUTABLE_KIND_SKIP;
}

Added in version 3.13.

PyUnstable_EXECUTABLE_KINDS

这是 不稳定 API。它可能在次要版本中不经警告地被更改。

The number of entries in PyUnstable_ExecutableKinds.

Added in version 3.13.