模块对象¶

PyTypeObject PyModule_Type¶: 属于稳定 ABI.
这个 PyTypeObject 的实例代表 Python 模块类型。它作为 types.ModuleType 被暴露给 Python 程序。

int PyModule_Check(PyObject *p)¶: 当 p 为模块类型的对象，或是模块子类型的对象时返回真值。该函数永远有返回值。

int PyModule_CheckExact(PyObject *p)¶: 当 p 为模块类型的对象且不是 PyModule_Type 的子类型的对象时返回真值。该函数永远有返回值。

PyObject *PyModule_NewObject(PyObject *name)¶

返回值：新的引用。 属于稳定 ABI 自 3.7 版起.

返回一个新的模块对象，该对象的 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)¶: 返回值：新的引用。 属于稳定 ABI 自 3.7 版起.
返回 module 的 __name__ 值。如果模块未提供该值，或者如果它不是一个字符串，则会引发 SystemError 并返回 NULL。

在 3.3 版本加入.

const char *PyModule_GetName(PyObject *module)¶

属于稳定 ABI.

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

返回的缓冲区将保持可用直到模块被重命名或销毁。请注意 Python 代码可能会通过设置其 __name__ 属性来重命名一个模块。

PyModuleDef *PyModule_GetDef(PyObject *module)¶

属于稳定 ABI.

返回指向模块创建所使用的 PyModuleDef 结构体的指针，或者如果模块不是使用结构体定义创建的则返回 NULL。

出错时，返回 NULL 并设置一个异常。使用 PyErr_Occurred() 将这种情况与缺少 PyModuleDef 区分开来。

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' 的文件名。

返回的缓冲区将保持可用直到模块的 __file__ 属性被重新赋值或模块被销毁。

自 3.2 版本弃用: PyModule_GetFilename() 对于不可编码的文件名会引发 UnicodeEncodeError，请改用 PyModule_GetFilenameObject() 函数。

模块定义¶

使用 C API 创建的模块通常是用 PySlot 结构体的数组来定义的，它提供了一个模块应当如何被创建的“描述”。请参阅定位槽位获取有关槽位的更多通用信息。

在 3.15 版本发生变更: 此前，定义模块时需要使用 PyModuleDef 结构体。若计划支持较早版本的 Python，仍可采用较旧的模块定义方式：请参阅模块定义 struct 章节或本文档的早期版本。

slots 数组通常用于定义扩展模块的“主”模块对象（详情请参阅定义扩展模块）。它还可用于 create extension modules dynamically。

除非另有说明，否则同一槽位 ID 不得在槽位数组中重复使用。

元数据槽位¶

Py_mod_name¶

属于稳定 ABI 自 3.15 版起.

用于新模块名称的 Slot ID，其值为以 NUL 结尾、UTF-8 编码的 const char *。

请注意，模块通常使用 ModuleSpec 创建；一旦创建，将使用规范中指定的名称，而非 Py_mod_name。不过，仍建议为自省和调试目的保留此槽位。

在 3.15 版本加入: 请使用 PyModuleDef.m_name 以支持旧版本。

Py_mod_doc¶

属于稳定 ABI 自 3.15 版起.

用于新模块 docstring 的 Slot ID，其值为以 NUL 结尾、UTF-8 编码的 const char *。

它通常会被设为以 PyDoc_STRVAR 创建的变量。

在 3.15 版本加入: 请改用 PyModuleDef.m_doc 以支持之前的版本。

特征槽位¶

Py_mod_abi¶

属于稳定 ABI 自 3.15 版起.

槽位 ID 值指向一个描述扩展所使用的 ABI 的 PyABIInfo 结构体。

可以使用 PyABIInfo_VAR 宏来定义适当的 PyABIInfo 变量，例如：

PyABIInfo_VAR(abi_info);

static PySlot mymodule_slots[] = {
   PySlot_DATA(Py_mod_abi, &abi_info),
   ...
};

当创建模块时，Python 将使用 PyABIInfo_Check() 检查该槽位的值。

此槽位是必需的，只有通过 PyModuleDef 创建的模块除外。

在 3.15 版本加入.

Py_mod_multiple_interpreters¶

属于稳定 ABI 自 3.12 版起.

槽位 ID 将为下列取值之一：

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_SUPPORTED 值。

出于历史原因，这些值被声明为指针（void *）。在使用 PySlot 数组时，应将 PySlot_DATA 用于 Py_mod_multiple_interpreters：

PySlot_DATA(Py_mod_multiple_interpreters,
            Py_MOD_PER_INTERPRETER_GIL_SUPPORTED)

在 3.12 版本加入.

Py_mod_gil¶

属于稳定 ABI 自 3.13 版起.

槽位 ID 将为下列取值之一：

Py_MOD_GIL_USED¶: 这个模块依赖于全局解释器锁 (GIL) 的存在，并可在无需同步的情况下访问全局状态。

Py_MOD_GIL_NOT_USED¶: 这个模块可以在不激活 GIL 的情况下安全运行。

这个槽位会被未配置 --disable-gil 的 Python 构建版所忽略。在其他情况下，它将决定导入此模块是否会导致 GIL 被自动启用。请参阅自由线程的 CPython 了解详情。

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

出于历史原因，这些值被声明为指针（void *）。在使用 PySlot 数组时，应将 PySlot_DATA 用于 Py_mod_gil：

PySlot_DATA(Py_mod_gil, Py_MOD_GIL_NOT_USED)

在 3.13 版本加入.

创建和初始化槽位¶

Py_mod_create¶

属于稳定 ABI 自 3.5 版起.

用于创建模块对象本身的函数所对应的 Slot ID。该函数必须具有以下签名：

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

该函数将以如下方式调用：

spec：一个类似 ModuleSpec 的对象，即为 importlib.machinery.ModuleSpec 定义的任何属性都具有对应的语义；不过其中任何属性都可能缺失。
def：NULL；若该模块是由某个模块生成的，则使用该模块的定义。

此函数应当返回一个新的模块对象，或是设置一个异常并返回 NULL。

此函数应当保持最小化。特别地，它不应当调用任意 Python 代码，因为尝试再次导入同一个模块可能会导致无限循环。

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

返回的对象无需必须是 PyModule_Type 的实例。不过，某些槽位可能仅可与 PyModule_Type 实例配合使用；具体而言：

Py_mod_exec,
module state slots (Py_mod_state_*),
Py_mod_token.

在 3.5 版本加入.

在 3.15 版本发生变更: spec 参数可能是一个类 ModuleSpec 的对象，而不是一个真正的 ModuleSpec 实例。请注意，早期版本的 CPython 并未对此作出强制要求。

def 参数现在可以设为 NULL，因为模块并不一定由定义构成。

Py_mod_exec¶

属于稳定 ABI 自 3.5 版起.

用于执行（即初始化）模块的函数所对应的 Slot ID。该函数相当于执行 Python 模块的代码：通常，它会向模块中添加类和常量。该函数的签名如下：

int exec_module(PyObject *module)¶

请参阅支持函数部分，了解一些可供调用的实用函数。

出于向后兼容性考虑，PyModuleDef.m_slots 数组可以包含多个 Py_mod_exec 槽位；这些槽位将按照在数组中出现的顺序依次处理。在其他位置（即 PyModule_FromSlotsAndSpec() 的参数和 PyModExport_<name> 的返回值中），不允许重复使用同一个槽位。

在 3.5 版本加入.

在 3.15 版本发生变更: 除 PyModuleDef.m_slots 外，不允许重复出现 Py_mod_exec 槽位。

Py_mod_methods¶

属于稳定 ABI 自 3.15 版起.

Slot ID 用于提供模块级函数表，该表以 PyMethodDef 值的数组形式呈现，可作为 PyModule_AddFunctions() 的 functions 参数。

与其他 slot ID 一样，slots 数组中只能包含一个 Py_mod_methods 条目。若要从多个 PyMethodDef 数组中添加函数，请在 Py_mod_exec 函数中调用 PyModule_AddFunctions()。

该表必须采用静态分配（或以其他方式确保其生命周期超过模块对象的生命周期）。

在 3.15 版本加入: 请使用 PyModuleDef.m_methods 以支持旧版本。

模块状态¶

扩展模块可以拥有*模块状态*——即在模块创建时分配的一块内存，当模块对象被释放时，该内存会被释放。模块状态通过 dedicated slots 指定。

模块状态的典型用途之一是存储异常类型——或者更准确地说，存储由该模块定义的*任何*类型对象——

与模块的 Python 属性不同，Python 代码无法替换或删除存储在模块状态中的数据。

将每个模块的信息存储在属性中以及模块状态中，而不是存储在静态全局变量中，可以使模块对象实现*隔离*，从而在多个子解释器中使用时更加安全。这也有助于 Python 在关闭时有序地进行清理。

将指向 Python 对象的引用保留在模块状态中的扩展模块必须实现 Py_mod_state_traverse 和 Py_mod_state_clear 函数，以避免引用泄漏。

要从指定的模块中获取状态，请使用以下函数：

void *PyModule_GetState(PyObject *module)¶

属于稳定 ABI.

返回模块的“状态”，即指向在模块创建时分配的内存块的指针，或 NULL。请参阅 Py_mod_state_size。

发生错误时，返回 NULL 并已设置异常。使用 PyErr_Occurred() 将这种情况与模块状态缺失区分开来。

int PyModule_GetStateSize(PyObject *module, Py_ssize_t *result)¶

属于稳定 ABI 自 3.15 版起.

将 *result 设置为 module 的状态大小，该大小由 Py_mod_state_size （或 PyModuleDef.m_size）指定，然后返回 0。

发生错误时，将 *result 设置为 -1，并返回 -1，同时设置一个异常。

在 3.15 版本加入.

用于定义模块状态的槽位¶

以下 slot IDs 可用于定义模块状态。

Py_mod_state_size¶

属于稳定 ABI 自 3.15 版起.

Slot ID 表示模块状态的大小，单位为字节。

将该值设置为非负值意味着该模块可以被重新初始化，同时指定了其状态所需的额外内存量。

请参阅 PEP 3121 了解详情。

使用 PyModule_GetStateSize() 获取指定模块的大小。

在 3.15 版本加入: 请使用 PyModuleDef.m_size 以支持旧版本。

Py_mod_state_traverse¶

属于稳定 ABI 自 3.15 版起.

Slot ID：用于在模块对象的 GC 遍历过程中调用遍历函数的函数。

该函数的签名以及参数的含义与 PyTypeObject.tp_traverse 类似：

int traverse_module_state(PyObject *module, visitproc visit, void *arg)¶

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

在 3.15 版本加入: 请使用 PyModuleDef.m_traverse 以支持旧版本。

Py_mod_state_clear¶

属于稳定 ABI 自 3.15 版起.

Slot ID 用于指定在模块对象进行 GC 清理期间调用的清理函数。

该函数的签名如下：

int clear_module_state(PyObject *module)¶

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

与 PyTypeObject.tp_clear 类似，该函数并不*总是*会在模块被释放之前被调用。例如，当引用计数足以确定某个对象已不再被使用，循环垃圾回收器便不会介入，而 Py_mod_state_free 函数则会直接被调用。

在 3.15 版本加入: 请使用 PyModuleDef.m_clear 以支持旧版本。

Py_mod_state_free¶

属于稳定 ABI 自 3.15 版起.

Slot ID：用于在模块对象释放期间调用的函数。

该函数的签名如下：

int free_module_state(PyObject *module)¶

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

在 3.15 版本加入: 请使用 PyModuleDef.m_free 以支持旧版本。

模块令牌¶

每个模块都可能有一个关联的 token：这是一个指针大小的值，用于标识模块状态的内存布局。这意味着，如果你拥有一个模块对象，但不确定它是否“属于”你的扩展，可以通过以下代码进行检查：

PyObject *module = <the module in question>;

void *module_token;
if (PyModule_GetToken(module, &module_token) < 0) {
    return NULL;
}
if (module_token != your_token) {
    PyErr_SetString(PyExc_ValueError, "unexpected module");
    return NULL;
}

// This module's state has the expected memory layout; it's safe to cast
struct my_state *state = (struct my_state*)PyModule_GetState(module);

模块的令牌——以及在上述代码中应使用的 your_token 值——为：

对于用 PyModuleDef 创建的模块：该 PyModuleDef 的地址；
对于使用 Py_mod_token 槽位定义的模块：该槽位的值；
对于由 PyModExport_* export hook 创建的模块：导出钩子返回的槽位数组（除非被 Py_mod_token 覆盖）。

Py_mod_token¶

属于稳定 ABI 自 3.15 版起.

Slot ID 用于模块令牌。

如果您使用此插槽来设置模块令牌（而非依赖默认值），则必须确保：

指针的寿命比类长，所以当类存在时，指针不能用于其他用途。
它“属于”类所在的扩展模块，因此它不会与其他扩展冲突。
如果令牌指向一个 PyModuleDef 结构体，则该模块应表现得如同是由该 PyModuleDef 创建的一样。具体而言，模块状态必须具有相匹配的布局和语义。

由 PyModuleDef 创建的模块始终使用 PyModuleDef 的地址作为令牌。这意味着 Py_mod_token 无法在 PyModuleDef.m_slots 中使用。

在 3.15 版本加入.

int PyModule_GetToken(PyObject *module, void **result)¶

属于稳定 ABI 自 3.15 版起.

将 *result 设置为 module 的模块令牌，并返回 0。

发生错误时，将 *result 设置为 NULL，并返回 -1，同时设置异常。

在 3.15 版本加入.

另请参阅 PyType_GetModuleByToken()。

动态创建扩展模块¶

以下函数可用于动态创建扩展模块，而不是通过扩展的 export hook 来创建。

PyObject *PyModule_FromSlotsAndSpec(const PySlot *slots, PyObject *spec)¶

返回值：新的引用。 属于稳定 ABI 自 3.15 版起.

在给定一个 slots 数组和 ModuleSpec spec 的情况下，创建一个新的模块对象。

slots 参数必须指向一个由 PySlot 结构体组成的数组，该数组以一个槽 ID 为 0 的条目结尾（通常写作 PySlot_END）。该数组必须包含一个 Py_mod_abi 条目。

spec 参数可以是任何类似于 ModuleSpec 的对象，具体如 Py_mod_create 文档所述。目前，spec 必须包含 name 属性。

成功时，返回新模块；出错时，返回 NULL 并设置异常。

请注意，此操作不会处理模块的执行槽（Py_mod_exec）。必须同时调用 PyModule_FromSlotsAndSpec() 和 PyModule_Exec()，才能完整初始化模块。（另请参阅多阶段初始化。）

在 3.15 版本加入.

int PyModule_Exec(PyObject *module)¶

属于稳定 ABI 自 3.15 版起.

执行 module 的 Py_mod_exec 槽位(s)。

成功时返回 0；发生错误时，在设置异常的情况下返回 -1。

为便于理解：如果 module 没有插槽，例如当它使用 legacy single-phase initialization 时，此函数将不执行任何操作并返回 0。

在 3.15 版本加入.

模块定义 struct¶

传统上，扩展模块通过 模块定义 来定义，将其作为“描述”，说明模块应如何创建。该定义并非直接使用 slots 数组，而是为大多数常用功能提供专用成员，并允许通过扩展机制添加额外槽位。

这种模块定义方式目前仍然可用，且暂无将其移除的计划。

type PyModuleDef¶

属于稳定 ABI (see below).

模块定义结构体，用于存储创建模块对象所需的各项信息。

该结构必须采用静态分配（或者在其他情况下确保在由其创建的任何模块存在期间始终有效）。通常，以这种方式定义的每个扩展模块仅会有一个此类变量。

该结构体包含所有成员，在非自由线程构建版本（abi3）中是 Stable ABI 的一部分。在自由线程构建版本的稳定 ABI（abi3t）中，该结构体是透明的，在实际应用中无法使用；有关替代方案，请参阅模块定义。

PyModuleDef_Base m_base¶

始终将此成员初始化为 PyModuleDef_HEAD_INIT：

type PyModuleDef_Base¶

属于稳定 ABI (see below).

PyModuleDef.m_base 的类型。

该结构体是非自由线程构建版本（abi3）中 Stable ABI 的一部分。在自由线程构建版本的稳定 ABI（abi3t）中，该结构体是透明的，在实际应用中无法使用。

PyModuleDef_HEAD_INIT¶: PyModuleDef.m_base 所需的初始值。

const char *m_name¶: 对应于 Py_mod_name 插槽。

const char *m_doc¶: 这些成员对应于 Py_mod_doc 插槽。将其设置为 NULL 相当于省略该插槽。

Py_ssize_t m_size¶

对应于 Py_mod_state_size 插槽。将此值设置为零，相当于忽略该插槽。

使用 legacy single-phase initialization，或使用 PyModule_Create() 或 PyModule_Create2() 动态创建模块时，可将 m_size 设置为 -1。这表明该模块不支持子解释器，因为它具有全局状态。

PyMethodDef *m_methods¶: 对应于 Py_mod_methods 插槽。将此值设置为 NULL 等同于省略该插槽。

PyModuleDef_Slot *m_slots¶

一系列附加槽位，以 {0, NULL} 条目作为终止点。请注意，这些条目采用较旧的 PyModuleDef_Slot 结构，而非 PySlot。

如果数组中包含与 PyModuleDef 成员相对应的槽位，则其值必须匹配。例如，若在 m_slots 中使用 Py_mod_name，则 PyModuleDef.m_name 必须设置为相同的指针（而不仅仅是字符串内容相等）。

在 3.5 版本发生变更: 在 3.5 版之前，此成员总是被设为 NULL，并被定义为：

inquiry m_reload¶

type PyModuleDef_Slot¶

属于稳定 ABI （包括所有成员）自 3.5 版起.

用于定义模块额外槽位的旧版结构。

请注意，可以使用 Py_mod_slots 将 PyModuleDef_Slot 数组包含在 PySlot 数组中；反之，也可以使用 Py_slot_subslots 实现这一操作。

每个 PyModuleDef_Slot 结构 modslot 被解释为以下 PySlot 结构:

(PySlot){
   .sl_id=modslot.slot,
   .sl_flags=PySlot_INTPTR | sub_static,
   .sl_ptr=modslot.value
}

其中，若该插槽需要该标志（例如对于 Py_mod_methods），则 sub_static 为 PySlot_STATIC；或者，若该标志存在于“父”插槽 Py_mod_slots 中（如有），则同样如此。

int slot¶: 对应于 PySlot.sl_id。

void *value¶: 对应于 PySlot.sl_ptr。

在 3.5 版本加入.

traverseproc m_traverse¶

inquiry m_clear¶

freefunc m_free¶

这些成员分别对应于 Py_mod_state_traverse、Py_mod_state_clear 和 Py_mod_state_free 槽位。

将这些成员设置为 NULL，等同于省略相应的槽位。

在 3.9 版本发生变更: m_traverse、m_clear 和 m_free 函数在模块状态分配之前将不再被调用。

PyTypeObject PyModuleDef_Type¶: 属于稳定 ABI 自 3.5 版起.
PyModuleDef 对象的类型。

Py_mod_slots¶: 属于稳定 ABI 自 3.15 版起.
Slot ID 的工作方式与 Py_slot_subslots 相同，不同之处在于它指定了一个由 PyModuleDef_Slot 结构体组成的数组。

在 3.15 版本加入.

可以使用以下 API 根据 PyModuleDef 结构体创建模块：

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 版本加入.

自 3.15 版起已处于 Soft deprecated 状态: 在新代码中优先选用 PyModule_FromSlotsAndSpec()。

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

返回值：新的引用。 属于稳定 ABI 自 3.7 版起.

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

当发生错误时将返回 NULL 并设置一个异常。

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

备注

大多数时候应该使用 PyModule_FromDefAndSpec() 代替使用此函数，除非你确定需要使用它。

在 3.5 版本加入.

自 3.15 版起已处于 Soft deprecated 状态: 在新代码中优先选用 PyModule_FromSlotsAndSpec()。

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)¶: 属于稳定 ABI 自 3.7 版起.
处理在 def 中给出的任何执行槽位 (Py_mod_exec)。

在 3.5 版本加入.

自 3.15 版起已处于 Soft deprecated 状态: 若要运行模块自身的执行槽，请优先使用 PyModule_Exec()；该槽适用于那些并非由 PyModuleDef 结构创建的模块。

PYTHON_API_VERSION¶

PYTHON_API_STRING¶

C API 版本分别以整型 (1013) 和字符串 ("1013") 形式提供。此定义旨在保持向后兼容性。

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

PYTHON_ABI_VERSION¶

PYTHON_ABI_STRING¶

为保持向后兼容性，分别定义为 3 和 "3"。

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

支持函数¶

以下函数用于帮助初始化模块对象。它们适用于模块的执行槽 (Py_mod_exec)、用于旧版 single-phase initialization 的初始化函数，或用于动态创建模块的代码。

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

属于稳定 ABI 自 3.10 版起.

将一个对象以 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)¶

属于稳定 ABI 自 3.13 版起.

类似于 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 的引用。

这意味着必须检查它的返回值，调用方代码必须在发生错误时手动为 value 执行 Py_XDECREF()。

用法示例：

PyObject *obj = PyBytes_FromString(value);
if (PyModule_AddObject(module, "spam", obj) < 0) {
    // 如果 'obj' 不为 NULL 且 PyModule_AddObject() 执行失败，
    // 则 'obj' 强引用必须使用 Py_XDECREF() 来删除。
    // 如果 'obj' 为 NULL，则 Py_XDECREF() 不做任何操作。
    Py_XDECREF(obj);
    goto error;
}
// PyModule_AddObject() 会偷取一个对 obj 的引用：
// 这里不需要 Py_XDECREF(obj)。

自 3.13 版起已处于 Soft deprecated 状态.

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 的整数常量 AF_INET 添加到 module 中。当发生错误时将返回 -1 并设置一个异常，成功时将返回 0。

PyModule_AddStringMacro(module, macro)¶: 将一个字符串常量添加到*module*模块中。

int PyModule_AddType(PyObject *module, PyTypeObject *type)¶: 属于稳定 ABI 自 3.10 版起.
将一个类型对象添加到 module 中。类型对象是通过在内部调用 PyType_Ready() 来最终化的。类型对象的名称取自 tp_name 在点号之后的部分。当发生错误时将返回 -1 并设置一个异常，成功时将返回 0。

在 3.9 版本加入.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)¶

属于稳定 ABI 自 3.7 版起.

将以 NULL 结尾的 functions 数组中的函数添加到 module 中。有关单个条目的更多细节，请参阅 PyMethodDef 文档（由于缺少共享的模块命名空间，在 C 中实现的模块级"函数"通常将模块作为其第一个形参，与 Python 类的实例方法类似）。

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

functions 数组必须被静态地分配（或者要保证比模块对象生存得更久）。

在 3.5 版本加入.

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

属于稳定 ABI 自 3.7 版起.

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

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

在 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)¶

属于稳定 ABI 自 3.3 版起.

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

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

Python 会在使用单阶段初始化导入一个模块后自动调用 PyState_AddModule，因此从模块初始化代码中调用它是没有必要的（但也没有害处）。显式的调用仅在模块自己的初始化代码后继调用了 PyState_FindModule 的情况下才是必要的。此函数主要是为了实现替代导入机制（或是通过直接调用它，或是通过引用它的实现来获取所需的状态更新详情）。

如果先前使用相同的 def 附加了一个模块，则将其替换为新的 module。

调用方必须有已附加的线程状态 attached thread state。

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

在 3.3 版本加入.

int PyState_RemoveModule(PyModuleDef *def)¶

属于稳定 ABI 自 3.3 版起.

从解释器状态中移除由 def 创建的模块对象。当发生错误时将返回 -1 并设置一个异常，成功时将返回 0。

调用方必须有已附加的线程状态 attached thread state。

在 3.3 版本加入.

模块对象¶

模块定义¶

元数据槽位¶

特征槽位¶

创建和初始化槽位¶

模块状态¶

用于定义模块状态的槽位¶

模块令牌¶

动态创建扩展模块¶

模块定义 struct¶

支持函数¶

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

目录

上一主题

下一主题

当前页