模块对象

PyTypeObject PyModule_Type

作为 稳定 ABI 的一部分。

PyTypeObject 的这个实例代表 Python 模块类型。这在 Python 程序中作为 types.ModuleType 公开。

int PyModule_Check(PyObject *p)

如果 p 是模块对象或模块对象的子类型，则返回 true。此函数始终成功。

int PyModule_CheckExact(PyObject *p)

如果 p 是模块对象，但不是 PyModule_Type 的子类型，则返回 true。此函数始终成功。

PyObject *PyModule_NewObject(PyObject *name)

返回值: 新引用。 自 3.7 版本起成为 稳定ABI 的一部分。

返回一个新的模块对象，其 module.__name__ 设置为 name。模块的 __name__、__doc__、__package__ 和 __loader__ 属性已填充（除了 __name__，其他都设置为 None）。调用者负责设置 __file__ 属性。

如果出错，返回 NULL 并设置异常。

在 3.3 版本加入。

3.4 版本中已更改: __package__ 和 __loader__ 现在设置为 None。

PyObject *PyModule_New(const char *name)

返回值: 新引用。 稳定ABI 的一部分。

类似于 PyModule_NewObject()，但名称是 UTF-8 编码字符串而不是 Unicode 对象。

PyObject *PyModule_GetDict(PyObject *module)

返回值: 借用引用。 稳定ABI 的一部分。

返回实现 module 命名空间的字典对象；此对象与模块对象的 __dict__ 属性相同。如果 module 不是模块对象（或模块对象的子类型），则会引发 SystemError 并返回 NULL。

建议扩展使用其他 PyModule_* 和 PyObject_* 函数，而不是直接操作模块的 __dict__。

PyObject *PyModule_GetNameObject(PyObject *module)

返回值: 新引用。 自 3.7 版本起成为 稳定ABI 的一部分。

返回 module 的 __name__ 值。如果模块未提供，或者它不是字符串，则会引发 SystemError 并返回 NULL。

在 3.3 版本加入。

const char *PyModule_GetName(PyObject *module)

作为 稳定 ABI 的一部分。

类似于 PyModule_GetNameObject()，但返回编码为 'utf-8' 的名称。

void *PyModule_GetState(PyObject *module)

作为 稳定 ABI 的一部分。

返回模块的“状态”，即在模块创建时分配的内存块的指针，如果为 NULL 则不返回。请参见 PyModuleDef.m_size。

PyModuleDef *PyModule_GetDef(PyObject *module)

作为 稳定 ABI 的一部分。

返回指向创建该模块的 PyModuleDef 结构的指针，如果该模块不是通过定义创建的，则返回 NULL。

PyObject *PyModule_GetFilenameObject(PyObject *module)

返回值: 新引用。 稳定ABI 的一部分。

使用 module 的 __file__ 属性返回加载 module 的文件名。如果未定义，或不是字符串，则引发 SystemError 并返回 NULL；否则返回 Unicode 对象的引用。

在 3.2 版本加入。

const char *PyModule_GetFilename(PyObject *module)

作为 稳定 ABI 的一部分。

类似于 PyModule_GetFilenameObject()，但返回编码为 'utf-8' 的文件名。

3.2 版本中已废弃: PyModule_GetFilename() 对不可编码的文件名引发 UnicodeEncodeError，请改用 PyModule_GetFilenameObject()。

模块定义

上一节中的函数适用于任何模块对象，包括从 Python 代码导入的模块。

使用 C API 定义的模块通常使用 模块定义，即 PyModuleDef —— 一个静态分配的常量“描述”，用于说明如何创建模块。

该定义通常用于定义扩展的“主”模块对象（有关详细信息，请参见 定义扩展模块）。它也用于动态创建扩展模块。

与 PyModule_New() 不同，该定义允许管理 模块状态 —— 一块与模块对象一起分配和清除的内存。与模块的 Python 属性不同，Python 代码不能替换或删除存储在模块状态中的数据。

type PyModuleDef

稳定 ABI 的一部分（包括所有成员）。

模块定义结构体，它包含创建模块对象所需的所有信息。此结构体必须静态分配（或以其他方式保证在任何从它创建的模块存在期间都有效）。通常，每个扩展模块只有一个此类型的变量。

PyModuleDef_Base m_base

此成员始终初始化为 PyModuleDef_HEAD_INIT。

const char *m_name

新模块的名称。

const char *m_doc

模块的文档字符串；通常使用 PyDoc_STRVAR 创建的文档字符串变量。

Py_ssize_t m_size

模块状态可以保存在每个模块的内存区域中，可以使用 PyModule_GetState() 检索，而不是静态全局变量。这使得模块可以安全地在多个子解释器中使用。

此内存区域根据 m_size 在模块创建时分配，并在模块对象解除分配时释放，如果存在 m_free 函数，则在其调用之后释放。

将其设置为非负值表示模块可以重新初始化，并指定其状态所需的额外内存量。

将 m_size 设置为 -1 表示模块不支持子解释器，因为它具有全局状态。只有在使用 旧版单阶段初始化 或动态创建模块时才允许负值 m_size。

有关更多详细信息，请参见 PEP 3121。

PyMethodDef *m_methods

指向模块级别函数表的指针，由 PyMethodDef 值描述。如果没有函数，可以为 NULL。

PyModuleDef_Slot *m_slots

用于多阶段初始化的槽定义数组，以 {0, NULL} 条目终止。当使用旧版单阶段初始化时，m_slots 必须为 NULL。

3.5 版本中已更改: 在 3.5 版本之前，此成员始终设置为 NULL，并定义为

inquiry m_reload

traverseproc m_traverse

在模块对象进行 GC 遍历时调用的遍历函数，如果不需要则为 NULL。

如果模块状态已请求但尚未分配，则不调用此函数。这种情况发生在模块创建后立即和模块执行前 (Py_mod_exec 函数)。更准确地说，如果 m_size 大于 0 且模块状态（由 PyModule_GetState() 返回）为 NULL，则不调用此函数。

3.9 版本中已更改: 不再在模块状态分配之前调用。

inquiry m_clear

在模块对象进行 GC 清理时调用的清理函数，如果不需要则为 NULL。

如果模块状态已请求但尚未分配，则不调用此函数。这种情况发生在模块创建后立即和模块执行前 (Py_mod_exec 函数)。更准确地说，如果 m_size 大于 0 且模块状态（由 PyModule_GetState() 返回）为 NULL，则不调用此函数。

与 PyTypeObject.tp_clear 一样，此函数在模块被解除分配之前不 总是 被调用。例如，当引用计数足以确定对象不再使用时，不涉及循环垃圾回收器，并直接调用 m_free。

3.9 版本中已更改: 不再在模块状态分配之前调用。

freefunc m_free

在模块对象解除分配时调用的函数，如果不需要则为 NULL。

如果模块状态已请求但尚未分配，则不调用此函数。这种情况发生在模块创建后立即和模块执行前 (Py_mod_exec 函数)。更准确地说，如果 m_size 大于 0 且模块状态（由 PyModule_GetState() 返回）为 NULL，则不调用此函数。

3.9 版本中已更改: 不再在模块状态分配之前调用。

模块槽位

type PyModuleDef_Slot

int slot

一个槽位 ID，从下面解释的可用值中选择。

void *value

槽位的值，其含义取决于槽位 ID。

在 3.5 版本加入。

可用的槽位类型有

Py_mod_create

指定一个函数，该函数用于创建模块对象本身。此槽位的 value 指针必须指向以下签名的函数：

PyObject *create_module(PyObject *spec, PyModuleDef *def)

该函数接收一个 ModuleSpec 实例，如 PEP 451 中所定义，以及模块定义。它应该返回一个新的模块对象，或者设置错误并返回 NULL。

此函数应尽量精简。特别是，它不应调用任意 Python 代码，因为尝试再次导入同一模块可能导致无限循环。

在一个模块定义中不能指定多个 Py_mod_create 槽位。

如果未指定 Py_mod_create，则导入机制将使用 PyModule_New() 创建一个普通模块对象。名称取自 spec，而不是定义，以允许扩展模块动态适应其在模块层次结构中的位置，并通过符号链接以不同的名称导入，同时共享单个模块定义。

返回的对象不要求是 PyModule_Type 的实例。只要它支持设置和获取与导入相关的属性，可以使用任何类型。但是，如果 PyModuleDef 具有非 NULL 的 m_traverse、m_clear、m_free；非零的 m_size；或除了 Py_mod_create 之外的槽位，则只能返回 PyModule_Type 实例。

Py_mod_exec

指定一个函数，该函数用于 执行 模块。这相当于执行 Python 模块的代码：通常，此函数将类和常量添加到模块中。该函数的签名为

int exec_module(PyObject *module)

如果指定了多个 Py_mod_exec 槽，它们将按照在 m_slots 数组中出现的顺序进行处理。

Py_mod_multiple_interpreters

指定以下值之一

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED

该模块不支持在子解释器中导入。

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED

该模块支持在子解释器中导入，但仅当它们共享主解释器的 GIL 时。（请参阅 隔离扩展模块。）

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

该模块支持在子解释器中导入，即使它们有自己的 GIL。（请参阅 隔离扩展模块。）

此槽位决定在子解释器中导入此模块是否会失败。

在一个模块定义中不能指定多个 Py_mod_multiple_interpreters 槽位。

如果未指定 Py_mod_multiple_interpreters，则导入机制默认为 Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED。

3.12 新版功能.

Py_mod_gil

指定以下值之一

Py_MOD_GIL_USED

模块依赖于全局解释器锁 (GIL) 的存在，并且可以在没有同步的情况下访问全局状态。

Py_MOD_GIL_NOT_USED

模块可以在没有活动 GIL 的情况下安全运行。

未配置 --disable-gil 的 Python 构建将忽略此槽位。否则，它将决定导入此模块是否会导致 GIL 自动启用。有关详细信息，请参见 Free-threaded CPython。

在一个模块定义中不能指定多个 Py_mod_gil 槽位。

如果未指定 Py_mod_gil，则导入机制默认为 Py_MOD_GIL_USED。

在 3.13 版本加入。

动态创建扩展模块

以下函数可用于在扩展的 初始化函数 之外创建模块。它们也用于 单阶段初始化。

PyObject *PyModule_Create(PyModuleDef *def)

返回值：新引用。

创建一个新的模块对象，给定 def 中的定义。这是一个宏，它调用 PyModule_Create2()，其中 module_api_version 设置为 PYTHON_API_VERSION，如果使用受限 API，则设置为 PYTHON_ABI_VERSION。

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)

返回值: 新引用。 稳定ABI 的一部分。

创建一个新的模块对象，给定 def 中的定义，并假设 API 版本为 module_api_version。如果该版本与运行中的解释器版本不匹配，则会发出 RuntimeWarning。

如果出错，返回 NULL 并设置异常。

此函数不支持槽位。def 的 m_slots 成员必须为 NULL。

备注

此函数的大多数用途都应该使用 PyModule_Create()；只有在确定需要时才使用此函数。

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)

返回值：新引用。

此宏调用 PyModule_FromDefAndSpec2()，其中 module_api_version 设置为 PYTHON_API_VERSION，如果使用受限 API，则设置为 PYTHON_ABI_VERSION。

在 3.5 版本加入。

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)

返回值: 新引用。 自 3.7 版本起成为 稳定ABI 的一部分。

创建一个新的模块对象，给定 def 中的定义和模块规格 spec，假设 API 版本为 module_api_version。如果该版本与运行中的解释器版本不匹配，则会发出 RuntimeWarning。

如果出错，返回 NULL 并设置异常。

请注意，这不处理执行槽位 (Py_mod_exec)。必须同时调用 PyModule_FromDefAndSpec 和 PyModule_ExecDef 才能完全初始化模块。

备注

此函数的大多数用途都应该使用 PyModule_FromDefAndSpec()；只有在确定需要时才使用此函数。

在 3.5 版本加入。

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)

自 3.7 版本起成为 稳定ABI 的一部分。

处理 def 中给定的任何执行槽 (Py_mod_exec)。

在 3.5 版本加入。

PYTHON_API_VERSION

C API 版本。为向后兼容性而定义。

目前，此常量不会在新的 Python 版本中更新，并且对版本控制没有用。这在将来可能会改变。

PYTHON_ABI_VERSION

定义为 3，以实现向后兼容性。

目前，此常量不会在新的 Python 版本中更新，并且对版本控制没有用。这在将来可能会改变。

支持函数

提供以下函数以帮助初始化模块状态。它们用于模块的执行槽 (Py_mod_exec)、旧版 单阶段初始化 的初始化函数或动态创建模块的代码。

int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)

自 3.10 版本以来，作为 稳定 ABI 的一部分。

将对象作为 name 添加到 module。这是一个方便的函数，可以在模块的初始化函数中使用。

成功时返回 0。错误时，引发异常并返回 -1。

用法示例：

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    if (obj == NULL) {
        return -1;
    }
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_DECREF(obj);
    return res;
 }

为了方便，此函数接受带有已设置异常的 NULL value。在这种情况下，返回 -1 并保持已引发的异常不变。

示例也可以不显式检查 obj 是否为 NULL

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_XDECREF(obj);
    return res;
 }

请注意，在这种情况下应使用 Py_XDECREF() 而不是 Py_DECREF()，因为 obj 可以为 NULL。

传递给此函数的不同 name 字符串的数量应保持较少，通常仅使用静态分配的字符串作为 name。对于在编译时未知的名称，优先直接调用 PyUnicode_FromString() 和 PyObject_SetAttr()。有关更多详细信息，请参见 PyUnicode_InternFromString()，它可能在内部用于创建键对象。

在 3.10 版本加入。

int PyModule_Add(PyObject *module, const char *name, PyObject *value)

自 3.13 版本起成为 稳定 ABI 的一部分。

类似于 PyModule_AddObjectRef()，但“窃取”对 value 的引用。它可以与返回新引用的函数的结果一起调用，而无需检查其结果甚至将其保存到变量中。

用法示例：

if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
    goto error;
}

在 3.13 版本加入。

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)

作为 稳定 ABI 的一部分。

类似于 PyModule_AddObjectRef()，但成功时（如果返回 0）窃取对 value 的引用。

推荐使用新的 PyModule_Add() 或 PyModule_AddObjectRef() 函数，因为误用 PyModule_AddObject() 函数很容易引入引用泄漏。

备注

与其他窃取引用的函数不同，PyModule_AddObject() 仅在 成功时 释放对 value 的引用。

这意味着必须检查其返回值，并且在错误时调用代码必须手动 Py_XDECREF() value。

用法示例：

PyObject *obj = PyBytes_FromString(value);
if (PyModule_AddObject(module, "spam", obj) < 0) {
    // If 'obj' is not NULL and PyModule_AddObject() failed,
    // 'obj' strong reference must be deleted with Py_XDECREF().
    // If 'obj' is NULL, Py_XDECREF() does nothing.
    Py_XDECREF(obj);
    goto error;
}
// PyModule_AddObject() stole a reference to obj:
// Py_XDECREF(obj) is not needed here.

自 3.13 版本弃用: PyModule_AddObject() 已软弃用。

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

作为 稳定 ABI 的一部分。

将整数常量作为 name 添加到 module。此便捷函数可用于模块的初始化函数。错误时返回 -1 并设置异常，成功时返回 0。

这是一个调用 PyLong_FromLong() 和 PyModule_AddObjectRef() 的便捷函数；有关详细信息，请参见其文档。

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)

作为 稳定 ABI 的一部分。

将字符串常量作为 name 添加到 module。此便捷函数可用于模块的初始化函数。字符串 value 必须以 NULL 终止。错误时返回 -1 并设置异常，成功时返回 0。

这是一个调用 PyUnicode_InternFromString() 和 PyModule_AddObjectRef() 的便捷函数；有关详细信息，请参见其文档。

PyModule_AddIntMacro(module, macro)

向 module 添加一个整数常量。名称和值取自 macro。例如 PyModule_AddIntMacro(module, AF_INET) 将整数常量 AF_INET 及其值添加到 module。错误时返回 -1 并设置异常，成功时返回 0。

PyModule_AddStringMacro(module, macro)

向 module 添加一个字符串常量。

int PyModule_AddType(PyObject *module, PyTypeObject *type)

自 3.10 版本以来，作为 稳定 ABI 的一部分。

向 module 添加一个类型对象。通过内部调用 PyType_Ready() 来最终确定类型对象。类型对象的名称取自 tp_name 点号后的最后一个组件。错误时返回 -1 并设置异常，成功时返回 0。

在 3.9 版本中新增。

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)

自 3.7 版本起成为 稳定ABI 的一部分。

将 NULL 终止的 functions 数组中的函数添加到 module。有关各个条目的详细信息，请参阅 PyMethodDef 文档（由于缺乏共享模块命名空间，C 中实现的模块级“函数”通常将模块作为其第一个参数，使其类似于 Python 类上的实例方法）。

当从 PyModuleDef 创建模块时（例如使用 多阶段初始化、PyModule_Create 或 PyModule_FromDefAndSpec 时），此函数会自动调用。一些模块作者可能更喜欢在多个 PyMethodDef 数组中定义函数；在这种情况下，他们应该直接调用此函数。

在 3.5 版本加入。

int PyModule_SetDocString(PyObject *module, const char *docstring)

自 3.7 版本起成为 稳定ABI 的一部分。

将 module 的文档字符串设置为 docstring。当从 PyModuleDef 创建模块时（例如使用 多阶段初始化、PyModule_Create 或 PyModule_FromDefAndSpec 时），此函数会自动调用。

在 3.5 版本加入。

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)

这是一个不稳定 API。它可能会在次要版本中未经警告而更改。

指示 module 是否支持在没有全局解释器锁 (GIL) 的情况下运行，使用 Py_mod_gil 中的某个值。在使用 旧版单阶段初始化 时，必须在 module 的初始化函数期间调用它。如果此函数在模块初始化期间未被调用，则导入机制假定该模块不支持在没有 GIL 的情况下运行。此函数仅在配置了 --disable-gil 的 Python 构建中可用。错误时返回 -1 并设置异常，成功时返回 0。

在 3.13 版本加入。

模块查找（单阶段初始化）

旧版 单阶段初始化 方案创建单例模块，可以在当前解释器的上下文中查找。这允许稍后仅通过模块定义的引用来检索模块对象。

这些函数不适用于使用多阶段初始化创建的模块，因为可以从单个定义创建多个此类模块。

PyObject *PyState_FindModule(PyModuleDef *def)

返回值: 借用引用。 稳定ABI 的一部分。

返回为当前解释器从 def 创建的模块对象。此方法要求模块对象已预先使用 PyState_AddModule() 附加到解释器状态。如果未找到相应的模块对象或尚未附加到解释器状态，则返回 NULL。

int PyState_AddModule(PyObject *module, PyModuleDef *def)

自 3.3 版本以来作为 稳定 ABI 的一部分。

将传递给函数的模块对象附加到解释器状态。这允许通过 PyState_FindModule() 访问模块对象。

仅对使用单阶段初始化创建的模块有效。

Python 在导入使用 单阶段初始化 的模块后会自动调用 PyState_AddModule，因此从模块初始化代码中调用它是不必要的（但无害）。只有当模块自己的初始化代码随后调用 PyState_FindModule 时，才需要显式调用。此函数主要用于实现替代导入机制（通过直接调用它，或通过参考其实现来了解所需的状态更新细节）。

如果之前使用相同的 def 附加了模块，它将被新的 module 替换。

调用者必须具有 已附加的线程状态。

错误时返回 -1 并设置异常，成功时返回 0。

在 3.3 版本加入。

int PyState_RemoveModule(PyModuleDef *def)

自 3.3 版本以来作为 稳定 ABI 的一部分。

从解释器状态中删除从 def 创建的模块对象。错误时返回 -1 并设置异常，成功时返回 0。

调用者必须具有 已附加的线程状态。

在 3.3 版本加入。