模块对象¶

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

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()。

初始化 C 模块¶

模块对象通常从扩展模块（导出初始化函数的共享库）或编译到内置模块（使用 PyImport_AppendInittab() 添加初始化函数）创建。请参阅构建 C 和 C++ 扩展或扩展嵌入式 Python 了解详细信息。

初始化函数可以将模块定义实例传递给 PyModule_Create()，并返回生成的模块对象，或者通过返回定义结构本身来请求“多阶段初始化”。

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 版本中更改: 在分配模块状态之前不再调用。

单阶段初始化¶

模块初始化函数可以直接创建并返回模块对象。这称为“单阶段初始化”，并使用以下两个模块创建函数之一

PyObject *PyModule_Create(PyModuleDef *def)¶: 返回值：新引用。
给定 def 中的定义，创建一个新的模块对象。这与将 module_api_version 设置为 PYTHON_API_VERSION 的 PyModule_Create2() 的行为类似。

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)¶

返回值：新引用。属于稳定 ABI 的一部分。

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

如果发生错误，则返回 NULL 并设置异常。

注意

大多数使用此函数的场景都应该使用 PyModule_Create() 代替；仅在确定需要时才使用此函数。

在从初始化函数返回之前，通常使用 PyModule_AddObjectRef() 等函数填充生成的模块对象。

多阶段初始化¶

指定扩展的另一种方法是请求“多阶段初始化”。以这种方式创建的扩展模块的行为更像 Python 模块：初始化在模块对象创建时的创建阶段和填充时的执行阶段之间分开。这种区别类似于类的 __new__() 和 __init__() 方法。

与使用单阶段初始化创建的模块不同，这些模块不是单例：如果删除了 sys.modules 条目并重新导入该模块，则会创建一个新的模块对象，并且旧模块会像 Python 模块一样进行正常的垃圾回收。默认情况下，从同一定义创建的多个模块应该是独立的：对一个模块的更改不应影响其他模块。这意味着所有状态都应特定于模块对象（例如，使用 PyModule_GetState()），或其内容（例如模块的 __dict__ 或使用 PyType_FromSpec() 创建的单个类）。

所有使用多阶段初始化创建的模块都应支持子解释器。确保多个模块独立通常足以实现这一点。

要请求多阶段初始化，初始化函数（PyInit_modulename）返回一个 PyModuleDef 实例，其中非空的 m_slots。在返回之前，必须使用以下函数初始化 PyModuleDef 实例

PyObject *PyModuleDef_Init(PyModuleDef *def)¶

返回值：借用的引用。自 3.5 版本起，属于稳定 ABI的一部分。

确保模块定义是正确初始化的 Python 对象，可以正确报告其类型和引用计数。

返回强制转换为 PyObject* 的 def，如果发生错误，则返回 NULL。

在 3.5 版本中添加。

模块定义的 m_slots 成员必须指向 PyModuleDef_Slot 结构的数组

type PyModuleDef_Slot¶

int slot¶: 槽 ID，从下面解释的可用值中选择。

void *value¶: 槽的值，其含义取决于槽 ID。

在 3.5 版本中添加。

m_slots 数组必须以 ID 为 0 的槽终止。

可用的槽类型是

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_NOT_SUPPORTED。

在 3.12 版本中添加。

Py_mod_gil¶

指定以下值之一

Py_MOD_GIL_USED¶: 该模块依赖于全局解释器锁（GIL）的存在，并且可以访问全局状态而无需同步。

Py_MOD_GIL_NOT_USED¶: 该模块在没有活动的 GIL 的情况下运行是安全的。

此槽会被未配置 --disable-gil 的 Python 构建忽略。否则，它会确定导入此模块是否会导致 GIL 自动启用。有关更多详细信息，请参阅自由线程 CPython。

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

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

在 3.13 版本中添加。

有关多阶段初始化的更多详细信息，请参阅 PEP 489。

底层模块创建函数¶

以下函数在使用多阶段初始化时在底层被调用。它们可以直接使用，例如在动态创建模块对象时。请注意，必须调用 PyModule_FromDefAndSpec 和 PyModule_ExecDef 才能完全初始化模块。

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)¶: 返回值：新引用。
给定 def 中的定义和 ModuleSpec spec，创建一个新的模块对象。此行为类似于 PyModule_FromDefAndSpec2()，其中 module_api_version 设置为 PYTHON_API_VERSION。

在 3.5 版本中添加。

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

返回值：新引用。自 3.7 版本以来属于稳定 ABI 的一部分。

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

如果发生错误，则返回 NULL 并设置异常。

注意

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

在 3.5 版本中添加。

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)¶: 自 3.7 版本起成为稳定 ABI 的一部分。
处理 def 中给出的任何执行槽 (Py_mod_exec)。

在 3.5 版本中添加。

int PyModule_SetDocString(PyObject *module, const char *docstring)¶: 自 3.7 版本起成为稳定 ABI 的一部分。
将 module 的文档字符串设置为 docstring。当使用 PyModule_Create 或 PyModule_FromDefAndSpec 从 PyModuleDef 创建模块时，会自动调用此函数。

在 3.5 版本中添加。

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)¶: 自 3.7 版本起成为稳定 ABI 的一部分。
将以 NULL 结尾的 functions 数组中的函数添加到 module。有关各个条目的详细信息，请参阅 PyMethodDef 文档（由于缺少共享的模块命名空间，用 C 实现的模块级“函数”通常会接收模块作为其第一个参数，使其类似于 Python 类上的实例方法）。当使用 PyModule_Create 或 PyModule_FromDefAndSpec 从 PyModuleDef 创建模块时，会自动调用此函数。

在 3.5 版本中添加。

支持函数¶

模块初始化函数（如果使用单阶段初始化）或从模块执行槽调用的函数（如果使用多阶段初始化）可以使用以下函数来帮助初始化模块状态

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

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

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

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

如果 value 为 NULL，则返回 -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;
 }

也可以在不显式检查 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 的一部分。

将字符串常量 value 作为 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 PyUnstable_Module_SetGIL(PyObject *module, void *gil)¶: 这是不稳定 API。它可能会在次要版本中更改，恕不另行通知。

使用 Py_mod_gil 中的一个值来指示 module 是否支持在没有全局解释器锁 (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 时才需要显式调用。该函数主要用于实现替代的导入机制（通过直接调用它，或通过参考其实现来了解所需的状态更新的详细信息）。

调用者必须持有 GIL。

如果发生错误，返回 -1 并设置一个异常，成功时返回 0。

在 3.3 版本中添加。

int PyState_RemoveModule(PyModuleDef *def)¶

自 3.3 版本以来属于稳定 ABI 的一部分。

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

调用者必须持有 GIL。

在 3.3 版本中添加。

模块对象¶

初始化 C 模块¶

单阶段初始化¶

多阶段初始化¶

底层模块创建函数¶

支持函数¶

模块查找¶

目录

上一主题

下一主题

本页