模块对象

 

PyTypeObject PyModule_Type

PyTypeObject的这个实例表示Python模块类型。这是暴露于Python程序types.ModuleType.

int PyModule_Check（ PyObject  *p）
如果p是模块对象，或模块对象的子类型.
int PyModule_CheckExact（ PyObject  *p）
如果是，则返回truep是一个模块对象，但不是PyModule_Type.
PyObject * PyModule_NewObject的子类型（ PyObject  *name）
Return value: New reference.

返回一个新的模块对象，__name__属性设置为name。模块的__name__, __doc__, __package__和__loader__属性被填入（除了__name__以外都是None）;调用者负责提供__file__属性

新版本3.3.

更改版本3.4：__package__和__loader__设置为None.

PyObject * PyModule_New（ const char  *name）
Return value: New reference.

类似于PyModule_NewObject()，但名称是UTF-8编码字符串而不是Unicode对象.

PyObject* PyModule_GetDict（ PyObject  *module）
Return value: Borrowed reference.

返回实现module命名空间;这个对象与模块对象的__dict__属性相同。如果module不是模块对象（或模块对象的子类型），则SystemError被引发和NULL退回了

建议扩展使用其他PyModule_*()和PyObject_*()函数而不是直接操作模块的__dict__.

PyObject * PyModule_GetNameObject（ PyObject  *module）
Return value: New reference.

返回module的__name__值。如果模块没有提供一个，或者它不是一个字符串，则SystemError被抬起并且NULL被返回.

新版本3.3.

const char * PyModule_GetName（ PyObject  *module）
类似于PyModule_GetNameObject()但是返回编码的名称为"utf-8".
void * PyModule_GetState（ PyObject  *module）
返回模块的“状态”，也就是说，指向在模块创建时分配的内存块的指针，或NULL。见PyModuleDef.m_size.
PyModuleDef * PyModule_GetDef（ PyObject  *module）
返回指向PyModuleDef结构的指针模块是创建的，或NULL如果模块不是从定义创建的.
PyObject * PyModule_GetFilenameObject（ PyObject  *module）
Return value: New reference.

使用module的module属性返回加载__file__的文件的名称。如果没有定义，或者它不是aunicode字符串，则引发SystemError并返回NULL;否则返回对Unicode对象的引用.

新版本3.2.

const char * PyModule_GetFilename（ PyObject  *module）
类似于PyModule_GetFilenameObject()但返回filenameencoded为’utf-8′.

自版本3.2以后不推荐使用：PyModule_GetFilename()引发UnicodeEncodeError onunencodable filenames，使用PyModule_GetFilenameObject()代替

 

初始化C模块

模块对象通常是从扩展模块（导出初始化函数的共享库）或编译模块（其中初始化函数是使用PyImport_AppendInittab()）添加的。参见构建C和C ++扩展或扩展嵌入式Python 了解详情。

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

PyModuleDef
模块定义结构，它包含创建模块对象所需的所有信息。每个模块通常只有一个静态初始化的变量.

PyModuleDef_Base m_base
总是将这个成员初始化为PyModuleDef_HEAD_INIT.
const char * m_name
new module.
const char * m_doc
模块的文档字符串;通常使用PyDoc_STRVAR()创建的docstring变量.
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，并定义为：

查询m_reload
traverseproc m_traverse
在GC遍历模块对象期间调用的遍历函数，如果不需要则调用NULL。在分配模块状态之前可以调用此函数（PyModule_GetState()可以返回NULL ），并在Py_mod_exec函数执行之前.
inquiry m_clear
在GC清除模块对象期间调用的清除函数，或NULL如果不需要的话。可以在分配模块状态之前调用此函数（PyModule_GetState()可以返回 NULL ），并在执行Py_mod_exec函数之前调用
// freefunc m_free
在取消分配模块对象时调用的函数，或NULL如果不需要。可以在分配模块状态之前调用此函数（PyModule_GetState()可以返回 NULL ），并在执行Py_mod_exec函数之前调用

//单相初始化

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

PyObject * PyModule_Create（ PyModuleDef  *def）
Return value: New reference.

根据def中的定义创建一个新的模块对象。这表现得像PyModule_Create2() module_api_version设置为PYTHON_API_VERSION.

PyObject * PyModule_Create2（ PyModuleDef  *def，int  module_api_version）
Return value: New reference.

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

注意

这个函数的大多数用法应该是使用PyModule_Create()代替;如果您确定需要它，请使用它.

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

 

多相初始化

指定扩展的另一种方法是请求“多阶段初始化”。以这种方式创建的扩展模块更像Python模块：初始化分为creation phase，当模块对象被创建时，和execution phase，当它被填充时。区别类似于__new__()和__init__()类的方法.

与使用单相初始化创建的模块不同，这些模块是notsingletons：如果sys.modules删除条目并重新导入模块，创建一个新模块对象，并且旧模块受普通垃圾收集的限制 – 与Python模块一样。默认情况下，从同一定义创建的多个模块应该是独立的：对一个模块的更改应该是不影响其他人。这意味着所有状态都应该特定于模块对象（使用egusing PyModule_GetState()）或其内容（如模块的__dict__或用PyType_FromSpec()）.

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

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

PyObject * PyModuleDef_Init（ PyModuleDef  *def）
Return value: Borrowed reference.

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

返回def转换为PyObject*，或NULL如果出错发生了。

版本3.5中的新功能

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

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 中定义的，以及模块定义。它应该返回一个新的模块对象，或者设置一个errorand返回NULL.

这个功能应该保持最小。特别是它不应该调用任意Python代码，因为尝试再次导入同一个模块可能会导致无限循环.

多个Py_mod_create插槽可能没有在一个moduledefinition中指定.

如果没有指定Py_mod_create，导入机器将使用PyModule_New()创建一个普通的模块对象。该名称来自spec，而不是定义，允许扩展模块动态调整它们在模块层次结构中的位置，并通过符号链接在不同的名称下导入，同时共享单个模块定义.

不要求返回的对象是PyModule_Type的实例。可以使用任何类型，只要它支持设置和获取与导入相关的属性。但是，如果PyModule_Type具有非PyModuleDef，则只返回NULL m_traverse, m_clear,m_free实例;非零m_size;或Py_mod_create.

Py_mod_exec
以外的插槽指定调用execute这相当于执行Python模块的代码：通常，这个函数为模块添加类和常量。函数的签名是：

int exec_module（PyObject *  module）

如果指定多个Py_mod_exec槽，它们按照它们出现在m_slots数组中的顺序处理

//见 PEP 489 有关多相初始化的详细信息.

低级模块创建功能

使用多相初始化时，在引擎盖下调用以下功能。它们可以直接使用，例如在动态创建moduleobjects时。注意PyModule_FromDefAndSpec和PyModule_ExecDef必须调用才能完全初始化模块.

PyObject * PyModule_FromDefAndSpec（ PyModuleDef  *def，PyObject  *spec）
Return value: New reference.

根据module和theModuleSpec spec。这个行为就像PyModule_FromDefAndSpec2() module_api_version设置为PYTHON_API_VERSION.

版本3.5中的新功能.

PyObject * PyModule_FromDefAndSpec2（PyModuleDef  *def，PyObject  *spec，int  module_api_version）
Return value: New reference.

假设API版本为module，给定spec和theModuleSpec 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）
设置module至 docstring。从PyModuleDef，使用PyModule_Create要么PyModule_FromDefAndSpec.

版本3.5中的新功能

int PyModule_AddFunctions（的PyObject  *module，PyMethodDef  *functions）
将NULL终止functions数组中的函数添加到module。参考PyMethodDef有关Individualualentries的详细信息的文档（由于缺少共享模块命名空间，C中实现的模块级“函数”通常将模块作为其第一个参数接收，使它们类似于Python类上的实例方法）。此函数在创建时自动调用来自PyModuleDef的模块，使用PyModule_Create或PyModule_FromDefAndSpec.

版本3.5中的新功能.

支持函数

模块初始化函数（如果使用单阶段初始化）ora函数从模块执行槽调用（如果使用多阶段初始化），可以使用以下函数来帮助初始化modulestate：

int PyModule_AddObject（ PyObject  *module，const char  *name，PyObject  *value）
在module添加一个对象name。这是一个便利功能，可以从模块的初始化功能中使用。这偷了对value的引用。错误地返回-1，0成功时
// PyModule_AddIntConstant（ PyObject  *module，const char  *name， 长 value）
将module的整数常量添加为name。这个便利功能可以从模块的初始化功能中使用。错误地返回-1，0 onsuccess.
int PyModule_AddStringConstant（ PyObject  *module，const char  *name，const char  *value）
在module中添加一个字符串常量name。这个便利功能可以从模块的初始化功能中使用。字符串value必须是NULL – 终止。错误地返回-1，0成功时
// PyModule_AddIntMacro（ PyObject  *module，宏）
将一个int常量添加到module。名称和值取自macro。例如PyModule_AddIntMacro(module, AF_INET)将//常规AF_INET添加到AF_INET的值module。错误地回复-1，0 on success.
int PyModule_AddStringMacro（ PyObject  *module，macro ）
添加一个字符串常量到module.

模块查找

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

这些函数不适用于使用多阶段初始化创建的模块，因为可以从单个定义创建多个这样的模块.

PyObject* PyState_FindModule（ PyModuleDef  *def）
Return value: Borrowed reference.

返回从def为当前解释器创建的模块对象。此方法要求模块对象已使用PyState_AddModule()预先。如果相应的模块对象尚未发现或尚未附加到解释器状态，则返回NULL.

int PyState_AddModule（ PyObject  *module，PyModuleDef *def）
将传递给函数的模块对象附加到解释器状态。这允许通过PyState_FindModule().

访问模块对象仅对使用单相初始化创建的模块有效.

3.3版本中的新功能

int PyState_RemoveModule（PyModuleDef  *def）
删除从def来自翻译国.

3.3版本中的新功能

评论被关闭。