模块对象 ¶

PyTypeObject PyModule_Type ¶: 属于稳定 ABI (应用程序二进制接口) .
此实例的 PyTypeObject 表示 Python 模块类型。暴露这给 Python 程序作为 types.ModuleType .

int PyModule_Check ( PyObject * p ) ¶: 返回 True 若 p is a module object, or a subtype of a module object. This function always succeeds.

int PyModule_CheckExact ( PyObject * p ) ¶: 返回 True 若 p 是模块对象，但不是子类型的 PyModule_Type . This function always succeeds.

PyObject * PyModule_NewObject ( PyObject * 名称 ) ¶

返回值：新引用。 属于稳定 ABI (应用程序二进制接口) since version 3.7.

Return a new module object with module.__name__ 设为 name 。模块的 __name__ , __doc__ , __package__ and __loader__ 属性被填充（除了 __name__ 被设为 None ). The caller is responsible for setting a __file__ 属性。

返回 NULL with an exception set on error.

Added in version 3.3.

3.4 版改变： __package__ and __loader__ are now set to None .

PyObject * PyModule_New ( const char * 名称 ) ¶: 返回值：新引用。 属于稳定 ABI (应用程序二进制接口) .
类似于 PyModule_NewObject() ，但名称是 UTF-8 编码字符串，而不是 Unicode 对象。

PyObject * PyModule_GetDict ( PyObject * 模块 ) ¶

返回值：借位引用。 属于稳定 ABI (应用程序二进制接口) .

Return the dictionary object that implements 模块 ’s namespace; this object is the same as the __dict__ attribute of the module object. If 模块 is not a module object (or a subtype of a module object), SystemError is raised and NULL 被返回。

It is recommended extensions use other PyModule_* and PyObject_* functions rather than directly manipulate a module’s __dict__ .

PyObject * PyModule_GetNameObject ( PyObject * 模块 ) ¶

返回值：新引用。 属于稳定 ABI (应用程序二进制接口) since version 3.7.

返回模块 ’s __name__ value. If the module does not provide one, or if it is not a string, SystemError is raised and NULL 被返回。

Added in version 3.3.

const char * PyModule_GetName ( PyObject * 模块 ) ¶: 属于稳定 ABI (应用程序二进制接口) .
类似于 PyModule_GetNameObject() but return the name encoded to 'utf-8' .

void * PyModule_GetState ( PyObject * 模块 ) ¶: 属于稳定 ABI (应用程序二进制接口) .
Return the “state” of the module, that is, a pointer to the block of memory allocated at module creation time, or NULL 。见 PyModuleDef.m_size .

PyModuleDef * PyModule_GetDef ( PyObject * 模块 ) ¶: 属于稳定 ABI (应用程序二进制接口) .
返回指针指向 PyModuleDef struct from which the module was created, or NULL if the module wasn’t created from a definition.

PyObject * PyModule_GetFilenameObject ( PyObject * 模块 ) ¶

返回值：新引用。 属于稳定 ABI (应用程序二进制接口) .

Return the name of the file from which 模块 was loaded using 模块 ’s __file__ attribute. If this is not defined, or if it is not a string, raise SystemError 并返回 NULL ; otherwise return a reference to a Unicode object.

Added in version 3.2.

const char * PyModule_GetFilename ( PyObject * 模块 ) ¶: 属于稳定 ABI (应用程序二进制接口) .
类似于 PyModule_GetFilenameObject() 但返回 UTF-8 编码的文件名。

从 3.2 版起弃用： PyModule_GetFilename() 引发 UnicodeEncodeError 当文件名不可编码时，使用 PyModule_GetFilenameObject() 代替。

初始化 C 模块 ¶

Modules objects are usually created from extension modules (shared libraries which export an initialization function), or compiled-in modules (where the initialization function is added using PyImport_AppendInittab() )。见构建 C/C++ 扩展 or 扩展嵌入式 Python 了解细节。

The initialization function can either pass a module definition instance to PyModule_Create() , and return the resulting module object, or request “multi-phase initialization” by returning the definition struct itself.

type PyModuleDef ¶

属于稳定 ABI (应用程序二进制接口) (including all members).

The module definition struct, which holds all information needed to create a module object. There is usually only one statically initialized variable of this type for each module.

PyModuleDef_Base m_base ¶: 始终将此成员初始化为 PyModuleDef_HEAD_INIT .

const char * m_name ¶: 新模块的名称。

const char * m_doc ¶: Docstring for the module; usually a docstring variable created with PyDoc_STRVAR 被使用。

Py_ssize_t m_size ¶

Module state may be kept in a per-module memory area that can be retrieved with PyModule_GetState() , rather than in static globals. This makes modules safe for use in multiple sub-interpreters.

This memory area is allocated based on m_size on module creation, and freed when the module object is deallocated, after the m_free function has been called, if present.

设置 m_size to -1 means that the module does not support sub-interpreters, because it has global state.

Setting it to a non-negative value means that the module can be re-initialized and specifies the additional amount of memory it requires for its state. Non-negative m_size is required for multi-phase initialization.

见 PEP 3121 了解更多细节。

PyMethodDef * m_methods ¶: A pointer to a table of module-level functions, described by PyMethodDef values. Can be NULL if no functions are present.

PyModuleDef_Slot * m_slots ¶

An array of slot definitions for multi-phase initialization, terminated by a {0, NULL} entry. When using single-phase initialization, m_slots 必须为 NULL .

3.5 版改变： Prior to version 3.5, this member was always set to NULL , and was defined as:

inquiry m_reload ¶

traverseproc m_traverse ¶

A traversal function to call during GC traversal of the module object, or NULL if not needed.

This function is not called if the module state was requested but is not allocated yet. This is the case immediately after the module is created and before the module is executed ( Py_mod_exec function). More precisely, this function is not called if m_size is greater than 0 and the module state (as returned by PyModule_GetState() ) is NULL .

3.9 版改变： No longer called before the module state is allocated.

inquiry m_clear ¶

A clear function to call during GC clearing of the module object, or NULL if not needed.

像 PyTypeObject.tp_clear , this function is not always called before a module is deallocated. For example, when reference counting is enough to determine that an object is no longer used, the cyclic garbage collector is not involved and m_free is called directly.

3.9 版改变： No longer called before the module state is allocated.

freefunc m_free ¶

A function to call during deallocation of the module object, or NULL if not needed.

3.9 版改变： No longer called before the module state is allocated.

单阶段初始化 ¶

模块初始化函数可以直接创建并返回模块对象。这被称为单阶段初始化，并使用以下 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 ) ¶

返回值：新引用。 属于稳定 ABI (应用程序二进制接口) .

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

返回 NULL with an exception set on error.

注意

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

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

多阶段初始化 ¶

指定扩展的替代方式是请求多阶段初始化。这种方式创建的扩展模块的行为更像 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 ) ¶

返回值：借位引用。 属于稳定 ABI (应用程序二进制接口) since version 3.5.

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

返回 def 铸造成 PyObject* ，或 NULL 若出现错误。

Added in version 3.5.

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

type PyModuleDef_Slot ¶

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

void * 值 ¶: Value of the slot, whose meaning depends on the slot ID.

Added in version 3.5.

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

可用槽类型：

Py_mod_create ¶

Specifies a function that is called to create the module object itself. The 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.

多 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.

Py_mod_multiple_interpreters ¶

Specifies one of the following values:

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED ¶: The module does not support being imported in subinterpreters.

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED ¶: The module supports being imported in subinterpreters, but only when they share the main interpreter’s GIL. (See 隔离扩展模块 )。

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED ¶: The module supports being imported in subinterpreters, even when they have their own GIL. (See 隔离扩展模块 )。

This slot determines whether or not importing this module in a subinterpreter will fail.

多 Py_mod_multiple_interpreters slots may not be specified in one module definition.

若 Py_mod_multiple_interpreters is not specified, the import machinery defaults to Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED .

3.12 版添加。

Py_mod_gil ¶

Specifies one of the following values:

Py_MOD_GIL_USED ¶: The module depends on the presence of the global interpreter lock (GIL), and may access global state without synchronization.

Py_MOD_GIL_NOT_USED ¶: The module is safe to run without an active GIL.

This slot is ignored by Python builds not configured with --disable-gil . Otherwise, it determines whether or not importing this module will cause the GIL to be automatically enabled. See Free-threaded CPython for more detail.

多 Py_mod_gil slots may not be specified in one module definition.

若 Py_mod_gil is not specified, the import machinery defaults to Py_MOD_GIL_USED .

3.13 版添加。

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

低级模块创建函数 ¶

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

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

返回值：新引用。

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

Added in version 3.5.

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

返回值：新引用。 属于稳定 ABI (应用程序二进制接口) since version 3.7.

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

返回 NULL with an exception set on error.

注意

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

Added in version 3.5.

int PyModule_ExecDef ( PyObject * 模块 , PyModuleDef * def ) ¶

属于稳定 ABI (应用程序二进制接口) since version 3.7.

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

Added in version 3.5.

int PyModule_SetDocString ( PyObject * 模块 , const char * docstring ) ¶

属于稳定 ABI (应用程序二进制接口) since version 3.7.

设置 docstring (文档字符串) 为模块 to docstring 。自动调用此函数当创建模块从 PyModuleDef ，使用 PyModule_Create or PyModule_FromDefAndSpec .

Added in version 3.5.

int PyModule_AddFunctions ( PyObject * 模块 , PyMethodDef * 函数 ) ¶

属于稳定 ABI (应用程序二进制接口) since version 3.7.

添加函数从 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 .

Added in version 3.5.

支持函数 ¶

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

int PyModule_AddObjectRef ( PyObject * 模块 , const char * 名称 , PyObject * 值 ) ¶

属于稳定 ABI (应用程序二进制接口) since version 3.10.

将对象添加到模块 as name . This is a convenience function which can be used from the module’s initialization function.

On success, return 0 . On error, raise an exception and return -1 .

返回 -1 if value is NULL . It must be called with an exception raised in this case.

用法范例：

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;
 }

The example can also be written without checking explicitly if obj is 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() should be used instead of Py_DECREF() in this case, since obj 可以是 NULL .

The number of different name strings passed to this function should be kept small, usually by only using statically allocated strings as name . For names that aren’t known at compile time, prefer calling PyUnicode_FromString() and PyObject_SetAttr() directly. For more details, see PyUnicode_InternFromString() , which may be used internally to create a key object.

3.10 版添加。

int PyModule_Add ( PyObject * 模块 , const char * 名称 , PyObject * 值 ) ¶

属于稳定 ABI (应用程序二进制接口) since version 3.13.

类似于 PyModule_AddObjectRef() , but “steals” a reference to value . It can be called with a result of function that returns a new reference without bothering to check its result or even saving it to a variable.

用法范例：

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

3.13 版添加。

int PyModule_AddObject ( PyObject * 模块 , const char * 名称 , PyObject * 值 ) ¶

属于稳定 ABI (应用程序二进制接口) .

类似于 PyModule_AddObjectRef() , but steals a reference to value on success (if it returns 0 ).

新的 PyModule_Add() or PyModule_AddObjectRef() functions are recommended, since it is easy to introduce reference leaks by misusing the PyModule_AddObject() 函数。

注意

Unlike other functions that steal references, PyModule_AddObject() only releases the reference to value on success .

This means that its return value must be checked, and calling code must Py_XDECREF() value manually on error.

用法范例：

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.

Deprecated since version 3.13: PyModule_AddObject() is soft deprecated .

int PyModule_AddIntConstant ( PyObject * 模块 , const char * 名称 , long 值 ) ¶

属于稳定 ABI (应用程序二进制接口) .

将整数常量添加到模块 as name 。这是可以从模块初始化函数中使用的方便函数。返回 -1 with an exception set on error, 0 当成功时。

This is a convenience function that calls PyLong_FromLong() and PyModule_AddObjectRef() ; see their documentation for details.

int PyModule_AddStringConstant ( PyObject * 模块 , const char * 名称 , const char * 值 ) ¶

属于稳定 ABI (应用程序二进制接口) .

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

This is a convenience function that calls PyUnicode_InternFromString() and PyModule_AddObjectRef() ; see their documentation for details.

PyModule_AddIntMacro ( 模块 , macro ) ¶: 将整数常量添加到模块。名称和值取自 macro 。例如 PyModule_AddIntMacro(module, AF_INET) 添加 int 常量 AF_INET 采用值的 AF_INET to 模块。返回 -1 with an exception set on error, 0 当成功时。

PyModule_AddStringMacro ( 模块 , macro ) ¶: 将字符串常量添加到模块 .

int PyModule_AddType ( PyObject * 模块 , PyTypeObject * type ) ¶

属于稳定 ABI (应用程序二进制接口) since version 3.10.

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 with an exception set on error, 0 当成功时。

Added in version 3.9.

int PyUnstable_Module_SetGIL ( PyObject * 模块 , void * gil ) ¶

这为 Unstable API . It may change without warning in minor releases.

Indicate that 模块 does or does not support running without the global interpreter lock (GIL), using one of the values from Py_mod_gil . It must be called during 模块 ’s initialization function. If this function is not called during module initialization, the import machinery assumes the module does not support running without the GIL. This function is only available in Python builds configured with --disable-gil 。返回 -1 with an exception set on error, 0 当成功时。

3.13 版添加。

模块查找 ¶

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

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

PyObject * PyState_FindModule ( PyModuleDef * def ) ¶: 返回值：借位引用。 属于稳定 ABI (应用程序二进制接口) .
Returns the module object that was created from def for the current interpreter. This method requires that the module object has been attached to the interpreter state with PyState_AddModule() beforehand. In case the corresponding module object is not found or has not been attached to the interpreter state yet, it returns NULL .

int PyState_AddModule ( PyObject * 模块 , PyModuleDef * def ) ¶

属于稳定 ABI (应用程序二进制接口) since version 3.3.

Attaches the module object passed to the function to the interpreter state. This allows the module object to be accessible via PyState_FindModule() .

才有效当使用单阶段初始化创建模块时。

Python calls PyState_AddModule automatically after importing a module, so it is unnecessary (but harmless) to call it from module initialization code. An explicit call is needed only if the module’s own init code subsequently calls PyState_FindModule . The function is mainly intended for implementing alternative import mechanisms (either by calling it directly, or by referring to its implementation for details of the required state updates).

调用者必须保持 GIL (全局解释器锁)。

返回 -1 with an exception set on error, 0 当成功时。

Added in version 3.3.

int PyState_RemoveModule ( PyModuleDef * def ) ¶

属于稳定 ABI (应用程序二进制接口) since version 3.3.

移除创建的模块对象自 def from the interpreter state. Return -1 with an exception set on error, 0 当成功时。

调用者必须保持 GIL (全局解释器锁)。

Added in version 3.3.

内容表

上一话题

下一话题

本页

模块对象 ¶

初始化 C 模块 ¶

单阶段初始化 ¶

多阶段初始化 ¶

低级模块创建函数 ¶

支持函数 ¶

模块查找 ¶

内容表

上一话题

下一话题

本页