代码对象

代码对象是 CPython 实现的底层细节。每个代码对象表示尚未绑定到函数中的可执行代码块。

type PyCodeObject

用于描述代码对象的 C 结构。此类型的字段随时可能更改。

PyTypeObject PyCode_Type

这是表示 Python 代码对象 的 PyTypeObject 实例。

int PyCode_Check(PyObject *co)

如果 co 是 代码对象，则返回 true。此函数始终成功。

Py_ssize_t PyCode_GetNumFree(PyCodeObject *co)

返回代码对象中的空闲变量数。

int PyCode_GetFirstFree(PyCodeObject *co)

返回代码对象中第一个空闲变量的位置。

PyCodeObject *PyUnstable_Code_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)

这是 不稳定 API。它可能会在小版本中不经警告而更改。

返回一个新的代码对象。如果您需要一个虚拟代码对象来创建一个框架，请使用 PyCode_NewEmpty()。

由于字节码的定义经常更改，因此直接调用 PyUnstable_Code_New() 可能会将您绑定到一个精确的 Python 版本。

此函数的许多参数以复杂的方式相互依赖，这意味着对值的细微更改很可能导致错误执行或 VM 崩溃。仅在极其小心时使用此函数。

3.11 版本中已更改： 添加了 qualname 和 exceptiontable 参数。

3.12 版本中已更改： 从 PyCode_New 重命名为 不稳定 C API 的一部分。旧名称已弃用，但仍可用，直到签名再次更改。

PyCodeObject *PyUnstable_Code_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)

这是 不稳定 API。它可能会在小版本中不经警告而更改。

类似于 PyUnstable_Code_New()，但为仅限位置的参数提供额外的 “posonlyargcount”。适用于 PyUnstable_Code_New 的相同警告也适用于此函数。

在 3.8 版本中添加： 作为 PyCode_NewWithPosOnlyArgs

3.11 版本中已更改： 添加了 qualname 和 exceptiontable 参数。

在 3.12 版本中更改： 重命名为 PyUnstable_Code_NewWithPosOnlyArgs。旧名称已弃用，但仍会保留，直到签名再次更改。

PyCodeObject *PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)

返回值：新引用。

返回一个新的空代码对象，其中包含指定的文件名、函数名和第一行号。如果执行，结果代码对象将引发 Exception。

int PyCode_Addr2Line

返回发生在 byte_offset 之前或在其上且在其后结束的指令的行号。如果您只需要帧的行号，请改用 PyFrame_GetLineNumber()。

要高效地迭代代码对象中的行号，请使用 PEP 626 中描述的 API。

int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)

将传递的 int 指针设置为 byte_offset 处的指令的源代码行号和列号。当任何特定元素不可用时，将值设置为 0。

如果函数成功，则返回 1，否则返回 0。

在版本 3.11 中添加。

PyObject *PyCode_GetCode(PyCodeObject *co)

等同于 Python 代码 getattr(co, 'co_code')。返回对 PyBytesObject 的强引用，该对象表示代码对象中的字节码。如果出错，则返回 NULL 并引发异常。

此 PyBytesObject 可能由解释器按需创建，并不一定表示 CPython 实际执行的字节码。此函数的主要用例是调试器和分析器。

在版本 3.11 中添加。

PyObject *PyCode_GetVarnames(PyCodeObject *co)

等同于 Python 代码 getattr(co, 'co_varnames')。返回对 PyTupleObject 的新引用，该对象包含局部变量的名称。如果出错，则返回 NULL 并引发异常。

在版本 3.11 中添加。

PyObject *PyCode_GetCellvars(PyCodeObject *co)

等效于 Python 代码 getattr(co, 'co_cellvars')。返回对包含嵌套函数引用的局部变量名称的 PyTupleObject 的新引用。如果出错，则返回 NULL 并引发异常。

在版本 3.11 中添加。

PyObject *PyCode_GetFreevars(PyCodeObject *co)

等效于 Python 代码 getattr(co, 'co_freevars')。返回对包含自由变量名称的 PyTupleObject 的新引用。如果出错，则返回 NULL 并引发异常。

在版本 3.11 中添加。

int PyCode_AddWatcher(PyCode_WatchCallback callback)

将 callback 注册为当前解释器的代码对象观察器。返回一个 ID，该 ID 可以传递给 PyCode_ClearWatcher()。如果出错（例如，没有更多观察器 ID 可用），则返回 -1 并设置异常。

在版本 3.12 中添加。

int PyCode_ClearWatcher(int watcher_id)

清除之前从 PyCode_AddWatcher() 返回的、由 watcher_id 标识的、针对当前解释器的观察器。如果成功，则返回 0，如果出错（例如，如果给定的 watcher_id 从未注册），则返回 -1 并设置异常。

在版本 3.12 中添加。

type PyCodeEvent

可能的代码对象观察器事件的枚举：- PY_CODE_EVENT_CREATE - PY_CODE_EVENT_DESTROY

在版本 3.12 中添加。

typedef int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject *co)

代码对象观察器回调函数的类型。

如果 event 为 PY_CODE_EVENT_CREATE，则在 co 完全初始化后调用回调。否则，在 co 被销毁之前调用回调，因此可以检查 co 的先前状态。

如果事件是 PY_CODE_EVENT_DESTROY，在回调中引用即将被销毁的代码对象将使它复活，并防止它此时被释放。当复活的对象稍后被销毁时，那时激活的任何观察者回调都将再次被调用。

此 API 的用户不应依赖于内部运行时实现细节。此类细节可能包括但不限于代码对象的创建和销毁的确切顺序和时间。虽然这些细节的变化可能会导致观察者（包括是否调用回调）可以观察到的差异，但它不会改变正在执行的 Python 代码的语义。

如果回调设置异常，则它必须返回 -1；此异常将使用 PyErr_WriteUnraisable() 打印为不可引发异常。否则它应返回 0。

在进入回调时可能已经设置了待处理异常。在这种情况下，回调应返回 0，且仍设置相同的异常。这意味着回调可能不会调用任何其他可以设置异常的 API，除非它首先保存并清除异常状态，并在返回之前恢复它。

在版本 3.12 中添加。

附加信息

为了支持对帧评估的底层扩展（例如外部即时编译器），可以将任意附加数据附加到代码对象。

这些函数是 unstable C API 层的一部分：此功能是 CPython 实现细节，API 可能会在不发出弃用警告的情况下更改。

Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex(freefunc free)

这是 不稳定 API。它可能会在小版本中不经警告而更改。

返回一个新的不透明索引值，用于向代码对象添加数据。

您通常调用此函数一次（每个解释器），并将其结果与 PyCode_GetExtra 和 PyCode_SetExtra 一起使用，以操作单个代码对象上的数据。

如果free 不为 NULL：当代码对象被释放时，将对存储在新索引下的非 NULL 数据调用 free。存储 PyObject 时，使用 Py_DecRef()。

在 3.6 版中添加： 作为 _PyEval_RequestCodeExtraIndex

在 3.12 版中更改： 重命名为 PyUnstable_Eval_RequestCodeExtraIndex。旧的私有名称已弃用，但仍可用，直到 API 更改。

int PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)

这是 不稳定 API。它可能会在小版本中不经警告而更改。

将 extra 设置为存储在给定索引下的附加数据。成功时返回 0。设置异常并返回 -1 表示失败。

如果未在索引下设置任何数据，则将 extra 设置为 NULL，并在不设置异常的情况下返回 0。

在 3.6 版中添加： 作为 _PyCode_GetExtra

在 3.12 版中更改： 重命名为 PyUnstable_Code_GetExtra。旧的私有名称已弃用，但仍可用，直到 API 更改。

int PyUnstable_Code_SetExtra(PyObject *code, Py_ssize_t index, void *extra)

这是 不稳定 API。它可能会在小版本中不经警告而更改。

将存储在给定索引下的额外数据设置为extra。成功时返回 0。设置异常并在失败时返回 -1。

在版本 3.6 中添加： 作为 _PyCode_SetExtra

在版本 3.12 中更改： 重命名为 PyUnstable_Code_SetExtra。旧的私有名称已弃用，但会在 API 更改之前一直可用。