匯入模組¶
-
PyObject*
PyImport_ImportModule
(const char *name)¶ - Return value: New reference.
这是下面
PyImport_ImportModuleEx()
的简化版接口,将 globals 和 locals 参数设为NULL
并将 level 设为 0。 当 name 参数包含一个点号(即指定了一个包的子模块)时,fromlist 参数会被设为列表['*']
这样返回值将为所指定的模块而不像在其他情况下那样为包含模块的最高层级包。 (不幸的是,这在 name 实际上是指定一个子包而非子模块时将有一个额外的副作用:在包的__all__
变量中指定的子模块会被加载。) 返回一个对所导入模块的新引用,或是在导入失败时返回NULL
并设置一个异常。 模块导入失败同模块不会留 在sys.modules
中。该函数总是使用绝对路径导入。
-
PyObject*
PyImport_ImportModuleNoBlock
(const char *name)¶ - Return value: New reference.
该函数是
PyImport_ImportModule()
的一个被弃用的别名。3.3 版更變: 在导入锁被另一线程掌控时此函数会立即失败。 但是从 Python 3.3 起,锁方案在大多数情况下都已切换为针对每个模块加锁,所以此函数的特殊行为已无必要。
-
PyObject*
PyImport_ImportModuleEx
(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)¶ - Return value: New reference.
导入一个模块。 请参阅内置 Python 函数
__import__()
获取完善的相关描述。返回值是一个对所导入模块或最高层级包的新引用,或是在导入失败时则为
NULL
并设置一个异常。 与__import__()
类似,当请求一个包的子模块时返回值通常为该最高层级包,除非给出了一个非空的 fromlist。导入失败将移动不完整的模块对象,就像
PyImport_ImportModule()
那样。
-
PyObject*
PyImport_ImportModuleLevelObject
(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)¶ - Return value: New reference.
导入一个模块。 关于此函数的最佳说明请参考内置 Python 函数
__import__()
,因为标准__import__()
函数会直接调用此函数。返回值是一个对所导入模块或最高层级包的新引用,或是在导入失败时则为
NULL
并设置一个异常。 与__import__()
类似,当请求一个包的子模块时返回值通常为该最高层级包,除非给出了一个非空的 fromlist。3.3 版新加入.
-
PyObject*
PyImport_ImportModuleLevel
(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)¶ - Return value: New reference.
类似于
PyImport_ImportModuleLevelObject()
,但其名称为 UTF-8 编码的字符串而不是 Unicode 对象。3.3 版更變: 不再接受 level 为负数值。
-
PyObject*
PyImport_Import
(PyObject *name)¶ - Return value: New reference.
这是一个调用了当前“导入钩子函数”的更高层级接口(显式指定 level 为 0,表示绝对导入)。 它将发起调用当前全局作用域下
__builtins__
中的__import__()
函数。 这意味着将使用当前环境下安装的任何导入钩子来完成导入。该函数总是使用绝对路径导入。
-
PyObject*
PyImport_ReloadModule
(PyObject *m)¶ - Return value: New reference.
重载一个模块。 返回一个指向被重载模块的新引用,或者在失败时返回
NULL
并设置一个异常(在此情况下模块仍然会存在)。
-
PyObject*
PyImport_AddModuleObject
(PyObject *name)¶ - Return value: Borrowed reference.
返回对应于某个模块名称的模块对象。 name 参数的形式可以为
package.module
。 如果存在 modules 字典则首先检查该字典,如果找不到,则创建一个新模块并将其插入到 modules 字典。 在失败时返回NULL
并设置一个异常。備註
此函数不会加载或导入指定模块;如果模块还未被加载,你将得到一个空的模块对象。 请使用
PyImport_ImportModule()
或它的某个变体形式来导入模块。 name 使用带点号名称的包结构如果尚不存在则不会被创建。3.3 版新加入.
-
PyObject*
PyImport_AddModule
(const char *name)¶ - Return value: Borrowed reference.
类似于
PyImport_AddModuleObject()
,但其名称为 UTF-8 编码的字符串而不是 Unicode 对象。object.
-
PyObject*
PyImport_ExecCodeModule
(const char *name, PyObject *co)¶ - Return value: New reference.
给定一个模块名称(可能为
package.module
形式)和一个从 Pyhon 字节码文件读取或从内置函数compile()
获取的代码对象,加载该模块。 返回对该模块对象的新引用,或者如果发生错误则返回NULL
并设置一个异常。 在发生错误的情况下 name 会从sys.modules
中被移除,即使 name 在进入PyImport_ExecCodeModule()
时已存在于sys.modules
中。 在sys.modules
中保留未完全初始化的模块是危险的,因为导入这样的模块没有办法知道模块对象是否处于一种未知的(对于模块作业的意图来说可能是已损坏的)状态。模块的
__spec__
和__loader__
如果尚未设置的话,将被设置为适当的值。 相应 spec 的加载器(如果已设置)将被设为模块的__loader__
而在其他情况下设为SourceFileLoader
的实例。模块的
__file__
属性将被设为代码对象的co_filename
。 如果适用,__cached__
也将被设置。如果模块已被导入则此函数将重载它。 请参阅
PyImport_ReloadModule()
了解重载模块的预定方式。如果 name 指向一个形式为
package.module
的带点号的名称,则任何尚未创建的包结构仍然不会被创建。另请参阅
PyImport_ExecCodeModuleEx()
和PyImport_ExecCodeModuleWithPathnames()
。
-
PyObject*
PyImport_ExecCodeModuleEx
(const char *name, PyObject *co, const char *pathname)¶ - Return value: New reference.
类似于
PyImport_ExecCodeModule()
,但如果 pathname 不为NULL
则会被设为模块对象的__file__
属性的值。
-
PyObject*
PyImport_ExecCodeModuleObject
(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)¶ - Return value: New reference.
类似于
PyImport_ExecCodeModuleEx()
,但如果 cpathname 不为NULL
则会被设为模块对象的__cached__
值。 在三个函数中,这是推荐使用的一个。3.3 版新加入.
-
PyObject*
PyImport_ExecCodeModuleWithPathnames
(const char *name, PyObject *co, const char *pathname, const char *cpathname)¶ - Return value: New reference.
类似于
PyImport_ExecCodeModuleObject()
,但 name, pathname 和 cpathname 为 UTF-8 编码的字符串。如果 pathname 也被设为NULL
则还会尝试根据 cpathname 推断出前者的值。3.2 版新加入.
3.3 版更變: 如果只提供了字节码路径则会使用
imp.source_from_cache()
来计算源路径。
-
long
PyImport_GetMagicNumber
()¶ 返回 Python 字节码文件(即
.pyc
文件)的魔数。 此魔数应当存在于字节码文件的开头四个字节中,按照小端字节序。 出错时返回-1
。3.3 版更變: 失败时返回值
-1
。
-
const char *
PyImport_GetMagicTag
()¶ 针对 PEP 3147 格式的 Python 字节码文件名返回魔术标签字符串。 请记住在
sys.implementation.cache_tag
上的值是应当被用来代替此函数的更权威的值。3.2 版新加入.
-
PyObject*
PyImport_GetModuleDict
()¶ - Return value: Borrowed reference.
返回用于模块管理的字典 (即
sys.modules
)。 请注意这是针对每个解释器的变量。
-
PyObject*
PyImport_GetModule
(PyObject *name)¶ - Return value: New reference.
返回给定名称的已导入模块。 如果模块尚未导入则返回
NULL
但不会设置错误。 如果查找失败则返回NULL
并设置错误。3.7 版新加入.
-
PyObject*
PyImport_GetImporter
(PyObject *path)¶ - Return value: New reference.
返回针对一个
sys.path
/pkg.__path__
中条目 path 的查找器对象,可能会通过sys.path_importer_cache
字典来获取。 如果它尚未被缓存,则会遍历sys.path_hooks
直至找到一个能处理该 path 条目的钩子。 如果没有可用的钩子则返回None
;这将告知调用方 path based finder 无法为该 path 条目找到查找器。 结果将缓存到sys.path_importer_cache
。 返回一个指向查找器对象的新引用。
-
int
PyImport_ImportFrozenModuleObject
(PyObject *name)¶ - Return value: New reference.
加载名称为 name 的已冻结模块。 成功时返回
1
,如果未找到模块则返回0
,如果初始化失败则返回-1
并设置一个异常。 要在加载成功后访问被导入的模块,请使用PyImport_ImportModule()
。 (请注意此名称有误导性 --- 如果模块已被导入此函数将重载它。)3.3 版新加入.
3.4 版更變:
__file__
属性将不再在模块上设置。
-
int
PyImport_ImportFrozenModule
(const char *name)¶ 类似于
PyImport_ImportFrozenModuleObject()
,但其名称为 UTF-8 编码的字符串而不是 Unicode 对象。
-
struct
_frozen
¶ 这是针对已冻结模块描述器的结构类型定义,与由 freeze 工具所生成的一致 (请参看 Python 源代码发行版中的
Tools/freeze/
)。 其定义可在Include/import.h
中找到:struct _frozen { const char *name; const unsigned char *code; int size; };
-
const struct _frozen*
PyImport_FrozenModules
¶ 该指针被初始化为指向
struct _frozen
数组,以NULL
或者 0 作为结束标记。当一个冻结模块被导入,首先要在这个表中搜索。第三方库可以以此来提供动态创建的冻结模块集合。
-
int
PyImport_AppendInittab
(const char *name, PyObject* (*initfunc)(void))¶ 向现有的内置模块表添加一个模块。 这是对
PyImport_ExtendInittab()
的便捷包装,如果无法扩展表则返回-1
。 新的模块可使用名称 name 来导入,并使用函数 initfunc 作为在第一次尝试导入时调用的初始化函数。 此函数应当在Py_Initialize()
之前调用。
-
struct
_inittab
¶ 描述内置模块列表中的一个条目的结构体。 每个结构体都给出了内置在解释器中的某个模块的名称和初始化函数。 名称是一个 ASCII 编码的字符串。 嵌入了 Python 的程序可以使用该结构体的数组来与
PyImport_ExtendInittab()
相结合以提供额外的内置模块。 该结构体在Include/import.h
中被定义为:struct _inittab { const char *name; /* ASCII encoded string */ PyObject* (*initfunc)(void); };
-
int
PyImport_ExtendInittab
(struct _inittab *newtab)¶ 将内置模块表添加一组模块。 newtab 数组必须以一个包含以
NULL
作为name
字段的岗哨条目结束;未能提供岗哨值会导致内存错误。 成功时返回0
或者如果无法分配足够内存来扩展内部表则返回-1
。 当发生失败时,将不会添加模块到内部表。 此函数必须在Py_Initialize()
之前调用。如果 Python 要被多次初始化,则
PyImport_AppendInittab()
或PyImport_ExtendInittab()
必须在每次 Python 初始化之前调用。