模块对象

PyTypeObject PyModule_Type
属于 稳定 ABI.

这个 C 类型实例 PyTypeObject 用来表示Python中的模块类型。在 Python 程序中该实例被暴露为 types.ModuleType

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 并设置一个异常。

Added in version 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

Added in version 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 对象的引用。

Added in version 3.2.

const char *PyModule_GetFilename(PyObject *module)
属于 稳定 ABI.

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

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

模块定义

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

使用 C API 定义的模块通常使用一个 模块定义,即 PyModuleDef -- 有关模块应当如何被创建的静态分配的、常量形式的“描述”。

该定义通常被用来定义扩展的 “main” 模块对象(参阅 定义扩展模块 了解详情)。 它还会被用来 动态创建扩展模块

不同于 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

在模块对象的垃圾回收遍历期间所调用的遍历函数,如果不需要则为 NULL

如果模块状态已被请求但尚未分配则不会调用此函数。 在模块创建之后至模块执行之前(调用 Py_mod_exec 函数)就属于这种情况。 更确切地说,如果 m_size 大于 0 且模块状态(由 PyModule_GetState() 返回)为 NULL 则不会调用此函数。

在 3.9 版本发生变更: 在模块状态被分配之前不再调用。

inquiry m_clear

在模块对象的垃圾回收清理期间所调用的清理函数,如果不需要则为 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。

Added in version 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 具有非 NULLm_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

Added in version 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

Added in version 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 并设置一个异常。

此函数不支持槽位。 defm_slots 成员必须为 NULL

备注

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

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
返回值:新的引用。

这个宏调用 PyModule_FromDefAndSpec2()module_api_version 设置为 PYTHON_API_VERSION,或者如果使用 受限 API,则设置为 PYTHON_ABI_VERSION

Added in version 3.5.

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
返回值:新的引用。 属于 稳定 ABI 自 3.7 版起.

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

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

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

备注

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

Added in version 3.5.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
属于 稳定 ABI 自 3.7 版起.

执行参数*def*中给出的任意执行槽(Py_mod_exec)。

Added in version 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)
属于 稳定 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(),它可在内部用于创建键对象。

Added in version 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;
}

Added in version 3.13.

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
属于 稳定 ABI.

类似于 PyModule_AddObjectRef(),但会在成功时偷取一个对 value 的引用(如果它返回 0 值)。

推荐使用新的 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 版本弃用: PyModule_AddObject() 处于 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

Added in version 3.9.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
属于 稳定 ABI 自 3.7 版起.

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

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

Added in version 3.5.

int PyModule_SetDocString(PyObject *module, const char *docstring)
属于 稳定 ABI 自 3.7 版起.

module 的文档字符串设置为 docstring 。 此函数在使用 PyModuleDef 创建模块时自动调用(例如使用 多阶段初始化PyModule_CreatePyModule_FromDefAndSpec 时)。

Added in version 3.5.

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)
这是 不稳定 API。它可在次发布版中不经警告地改变。

指明 module 是否支持不带全局解释器锁 (GIL) 运行,使用一个来自 Py_mod_gil 的值 。 当使用 旧式的单阶段初始化 时它必须在 module 的初始化函数执行期间被调用。 如果此函数在模块初始化期间未被调用,导入机制将假定该模块不支持不带 GIL 运行。 此函数仅在配置了 --disable-gil 的 Python 构建版中可用。 当发生错误时将返回 -1 并设置一个异常,成功时将返回 0

Added in version 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

Added in version 3.3.

int PyState_RemoveModule(PyModuleDef *def)
属于 稳定 ABI 自 3.3 版起.

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

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

Added in version 3.3.