帧对象
******

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

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

   此结构体中无公有成员。

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

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

可参考：Reflection 1

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* 当前正在执行的行号。


帧 locals 代理
==============

Added in version 3.13.

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

请参阅 **PEP 667** 了解详情。

PyTypeObject PyFrameLocalsProxy_Type

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

int PyFrameLocalsProxy_Check(PyObject *obj)

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


旧式局部变量 API
================

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

void PyFrame_LocalsToFast(PyFrameObject *f, int clear)

   此函数已处于 *soft deprecated* 状态并不做任何事。

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

   在 3.13 版本发生变更: 此函数现在不执行任何操作。

void PyFrame_FastToLocals(PyFrameObject *f)

   此函数已处于 *soft deprecated* 状态并不做任何事。

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

   在 3.13 版本发生变更: 此函数现在不执行任何操作。

int PyFrame_FastToLocalsWithError(PyFrameObject *f)

   此函数已处于 *soft deprecated* 状态并不做任何事。

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

   在 3.13 版本发生变更: 此函数现在不执行任何操作。

参见: **PEP 667**


内部帧
======

除非使用 **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.
