模块对象 ¶

单阶段初始化 ¶

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

PyObject * PyModule_Create ( PyModuleDef *def ) ¶

返回值：新引用。

创建新的模块对象，给定定义在 def 。这的举动像 PyModule_Create2() with module_api_version 设为 PYTHON_API_VERSION .

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

返回值：新引用。

创建新的模块对象，给定定义在 def ，假定 API 版本 module_api_version 。若该版本不匹配正运行解释器版本， RuntimeWarning 被发射。

注意

此函数的大多数用途应该是使用 PyModule_Create() 代替；才使用这若确定需要它。

在从初始化函数中返回之前，通常填充产生的模块对象使用函数像 PyModule_AddObject() .

多阶段初始化 ¶

指定扩展的替代方式是请求多阶段初始化。这种方式创建的扩展模块的行为更像 Python 模块：初始化被拆分成 创建阶段 ，当模块对象被创建时，和 执行阶段 ，当它被填充时。区别类似于 __new__() and __init__() 方法对于类。

不像使用单阶段初始化创建的模块，这些模块不是单例：若 sys.modules entry is removed and the module is re-imported, a new module object is created, and the old module is subject to normal garbage collection – as with Python modules. By default, multiple modules created from the same definition should be independent: changes to one should not affect the others. This means that all state should be specific to the module object (using e.g. using PyModule_GetState() ), or its contents (such as the module’s __dict__ or individual classes created with PyType_FromSpec() ).

All modules created using multi-phase initialization are expected to support 子解释器 . Making sure multiple modules are independent is typically enough to achieve this.

To request multi-phase initialization, the initialization function (PyInit_modulename) returns a PyModuleDef 实例采用非空 m_slots 。在返回它之前， PyModuleDef 实例必须采用以下函数被初始化：

PyObject * PyModuleDef_Init ( PyModuleDef *def ) ¶

返回值：借位引用。

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

返回 def 铸造到 PyObject* ，或 NULL 若发生错误。

3.5 版新增。

m_slots member of the module definition must point to an array of PyModuleDef_Slot 结构：

PyModuleDef_Slot ¶

int slot ¶

A slot ID, chosen from the available values explained below.

void* value ¶

Value of the slot, whose meaning depends on the slot ID.

3.5 版新增。

m_slots 数组必须被终止通过槽采用 ID 0。

可用槽类型：

Py_mod_create ¶

Specifies a function that is called to create the module object itself. value pointer of this slot must point to a function of the signature:

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

函数接收 ModuleSpec 实例，作为定义在 PEP 451 , and the module definition. It should return a new module object, or set an error and return NULL .

This function should be kept minimal. In particular, it should not call arbitrary Python code, as trying to import the same module again may result in an infinite loop.

Multiple Py_mod_create slots may not be specified in one module definition.

若 Py_mod_create is not specified, the import machinery will create a normal module object using PyModule_New() . The name is taken from spec , not the definition, to allow extension modules to dynamically adjust to their place in the module hierarchy and be imported under different names through symlinks, all while sharing a single module definition.

There is no requirement for the returned object to be an instance of PyModule_Type . Any type can be used, as long as it supports setting and getting import-related attributes. However, only PyModule_Type instances may be returned if the PyModuleDef has non- NULL m_traverse , m_clear , m_free ; non-zero m_size ; or slots other than Py_mod_create .

Py_mod_exec ¶

Specifies a function that is called to execute the module. This is equivalent to executing the code of a Python module: typically, this function adds classes and constants to the module. The signature of the function is:

int exec_module ( PyObject * 模块 ) ¶

若多个 Py_mod_exec slots are specified, they are processed in the order they appear in the m_slots array.

见 PEP 489 了解多阶段初始化的更多细节。

低级模块创建函数 ¶

在幕后调用以下函数，当使用多阶段初始化时。可以直接使用它们 (譬如：当动态创建模块对象时)。注意 PyModule_FromDefAndSpec and PyModule_ExecDef 必须被调用以完全初始化模块。

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

返回值：新引用。

创建新的模块对象，给定定义在 模块 和 ModuleSpec spec 。这的举动像 PyModule_FromDefAndSpec2() with module_api_version 设为 PYTHON_API_VERSION .

3.5 版新增。

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

返回值：新引用。

创建新的模块对象，给定定义在 模块 和 ModuleSpec spec ，假定 API 版本 module_api_version 。若该版本不匹配正运行解释器版本， RuntimeWarning 被发射。

注意

此函数的大多数用途应该是使用 PyModule_FromDefAndSpec() 代替；才使用这若确定需要它。

3.5 版新增。

int PyModule_ExecDef ( PyObject *module , PyModuleDef *def ) ¶

处理任何执行槽 ( Py_mod_exec ) 给定在 def .

3.5 版新增。

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

设置 docstring 对于 模块 to docstring 。自动调用此函数当创建模块从 PyModuleDef ，使用 PyModule_Create or PyModule_FromDefAndSpec .

3.5 版新增。

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

添加函数从 NULL terminated 函数 数组到 模块 。参考 PyMethodDef documentation for details on individual entries (due to the lack of a shared module namespace, module level “functions” implemented in C typically receive the module as their first parameter, making them similar to instance methods on Python classes). This function is called automatically when creating a module from PyModuleDef ，使用 PyModule_Create or PyModule_FromDefAndSpec .

3.5 版新增。

支持函数 ¶

模块初始化函数 (若使用单阶段初始化) 或从模块执行槽调用的函数 (若使用多阶段初始化)，可以使用下列函数以帮助初始化模块状态：

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

将对象添加到 模块 as name 。这是可以从模块初始化函数中使用的方便函数。这窃取引用对于 value on success. Return -1 当出错时， 0 当成功时。

注意

Unlike other functions that steal references, PyModule_AddObject() only decrements the reference count of value on success .

This means that its return value must be checked, and calling code must Py_DECREF() value manually on error. Example usage:

Py_INCREF(spam);
if (PyModule_AddObject(module, "spam", spam) < 0) {
    Py_DECREF(module);
    Py_DECREF(spam);
    return NULL;
}
												

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

将整数常量添加到 模块 as name 。这是可以从模块初始化函数中使用的方便函数。返回 -1 当出错时， 0 当成功时。

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

将字符串常量添加到 模块 as name 。这是可以从模块初始化函数中使用的方便函数。字符串 value 必须是 NULL 结尾。返回 -1 当出错时， 0 当成功时。

int PyModule_AddIntMacro ( PyObject *module , macro ) ¶

将整数常量添加到 模块 。名称和值取自 macro 。例如 PyModule_AddIntMacro(module, AF_INET) 添加 int 常量 AF_INET 采用值的 AF_INET to 模块 。返回 -1 当出错时， 0 当成功时。

int PyModule_AddStringMacro ( PyObject *module , macro ) ¶

将字符串常量添加到 模块 .

int PyModule_AddType ( PyObject *module , PyTypeObject *type ) ¶

Add a type object to 模块 . The type object is finalized by calling internally PyType_Ready() . The name of the type object is taken from the last component of tp_name after dot. Return -1 当出错时， 0 当成功时。

3.9 版新增。