You are here:  Home » Python » 模块对象 – 具体对象层(Python教程)(参考资料)

模块对象

 

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.

使用modulemodule属性返回加载__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_modulePyObject *  module

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

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

低级模块创建功能

使用多相初始化时,在引擎盖下调用以下功能。它们可以直接使用,例如在动态创建moduleobjects时。注意PyModule_FromDefAndSpecPyModule_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_FromDefAndSpec2PyModuleDef  *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
设置moduledocstring。从PyModuleDef,使用PyModule_Create要么PyModule_FromDefAndSpec.

版本3.5中的新功能

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

版本3.5中的新功能.

支持函数

模块初始化函数(如果使用单阶段初始化)ora函数从模块执行槽调用(如果使用多阶段初始化),可以使用以下函数来帮助初始化modulestate:

int PyModule_AddObject PyObject  *module,const char  *name,PyObject  *value
module添加一个对象name。这是一个便利功能,可以从模块的初始化功能中使用。这偷了对value的引用。错误地返回-10成功时
// PyModule_AddIntConstant PyObject  *module,const char  *name, 长 value
module的整数常量添加为name。这个便利功能可以从模块的初始化功能中使用。错误地返回-10 onsuccess.
int PyModule_AddStringConstant PyObject  *module,const char  *name,const char  *value
module中添加一个字符串常量name。这个便利功能可以从模块的初始化功能中使用。字符串value必须是NULL – 终止。错误地返回-10成功时
// PyModule_AddIntMacro PyObject  *module,宏
将一个int常量添加到module。名称和值取自macro。例如PyModule_AddIntMacro(module, AF_INET)将//常规AF_INET添加到AF_INET的值module。错误地回复-10 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_RemoveModulePyModuleDef  *def
删除从def来自翻译国.

3.3版本中的新功能

评论被关闭。