导入模块¶
-
PyObject *PyImport_ImportModule(const char *name)¶
- 返回值:新引用。 属于 稳定 ABI 的一部分。
这是
PyImport_Import()
的包装器,它接受一个 const char* 作为参数,而不是 PyObject*。
-
PyObject *PyImport_ImportModuleNoBlock(const char *name)¶
- 返回值:新引用。 属于 稳定 ABI 的一部分。
此函数是
PyImport_ImportModule()
的已弃用别名。在 3.3 版本中变更: 此函数在另一个线程持有导入锁时会立即失败。但在 Python 3.3 中,锁定方案切换到大多数情况下使用每个模块锁,因此此函数的特殊行为不再需要。
-
PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)¶
- 返回值:新引用。
导入模块。这最好通过参考内置的 Python 函数
__import__()
来描述。返回值是对导入的模块或顶级包的新引用,或者在失败时为
NULL
,并设置异常。与__import__()
一样,当请求包的子模块时,返回值通常是顶级包,除非给出了非空的 fromlist。导入失败会删除不完整的模块对象,就像使用
PyImport_ImportModule()
一样。
-
PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)¶
- 返回值:新引用。自版本 3.7 起,是 稳定 ABI 的一部分。
导入模块。这最好通过参考内置 Python 函数
__import__()
来描述,因为标准__import__()
函数直接调用此函数。返回值是对导入的模块或顶级包的新引用,或者在失败时为
NULL
,并设置异常。与__import__()
一样,当请求包的子模块时,返回值通常是顶级包,除非给出了非空的 fromlist。在版本 3.3 中添加。
-
PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)¶
- 返回值:新引用。 属于 稳定 ABI 的一部分。
类似于
PyImport_ImportModuleLevelObject()
,但名称是 UTF-8 编码的字符串,而不是 Unicode 对象。在版本 3.3 中更改:不再接受 level 的负值。
-
PyObject *PyImport_Import(PyObject *name)¶
- 返回值:新引用。 属于 稳定 ABI 的一部分。
这是一个更高级别的接口,它调用当前的“导入钩子函数”(显式 level 为 0,表示绝对导入)。它调用当前全局变量的
__builtins__
中的__import__()
函数。这意味着导入是使用当前环境中安装的任何导入钩子完成的。此函数始终使用绝对导入。
-
PyObject *PyImport_ReloadModule(PyObject *m)¶
- 返回值:新引用。 属于 稳定 ABI 的一部分。
重新加载模块。返回对重新加载的模块的新引用,或者在失败时返回
NULL
并设置异常(在这种情况下,模块仍然存在)。
-
PyObject *PyImport_AddModuleObject(PyObject *name)¶
- 返回值:借用引用。 作为 稳定 ABI 的一部分,自版本 3.7 起。
返回与模块名称对应的模块对象。name 参数可以是
package.module
的形式。首先检查模块字典中是否存在该模块,如果不存在,则创建一个新的模块并将其插入模块字典中。如果失败,则返回NULL
并设置异常。注意
此函数不会加载或导入模块;如果模块尚未加载,您将获得一个空模块对象。使用
PyImport_ImportModule()
或其变体之一来导入模块。如果不存在,则不会创建由name 的点分名称隐含的包结构。在版本 3.3 中添加。
-
PyObject *PyImport_AddModule(const char *name)¶
- 返回值:借用引用。 作为 稳定 ABI 的一部分。
类似于
PyImport_AddModuleObject()
,但名称是 UTF-8 编码的字符串而不是 Unicode 对象。
-
PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)¶
- 返回值:新引用。 属于 稳定 ABI 的一部分。
给定一个模块名称(可能是
package.module
的形式)和一个从 Python 字节码文件读取或从内置函数compile()
获得的代码对象,加载模块。返回对模块对象的新的引用,或者如果发生错误,则返回NULL
并设置异常。name 在错误情况下从sys.modules
中删除,即使name 在进入PyImport_ExecCodeModule()
时已经在sys.modules
中。将未完全初始化的模块留在sys.modules
中是危险的,因为导入此类模块的方式无法知道模块对象处于未知(并且可能相对于模块作者的意图而言已损坏)状态。模块的
__spec__
和__loader__
将被设置,如果尚未设置,则使用适当的值。规范的加载器将被设置为模块的__loader__
(如果设置)以及SourceFileLoader
的实例(否则)。模块的
__file__
属性将被设置为代码对象的co_filename
。如果适用,__cached__
也将被设置。如果模块已经导入,此函数将重新加载它。有关重新加载模块的预期方法,请参见
PyImport_ReloadModule()
。如果 name 指向形式为
package.module
的点分名称,则任何尚未创建的包结构仍然不会创建。另请参见
PyImport_ExecCodeModuleEx()
和PyImport_ExecCodeModuleWithPathnames()
。在 3.12 版本中变更: 设置
__cached__
和__loader__
已被弃用。有关替代方案,请参见ModuleSpec
。
-
PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)¶
- 返回值:新引用。 属于 稳定 ABI 的一部分。
与
PyImport_ExecCodeModule()
相似,但如果 pathname 非NULL
,则模块对象的__file__
属性将被设置为 pathname。
-
PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)¶
- 返回值:新引用。自版本 3.7 起,是 稳定 ABI 的一部分。
与
PyImport_ExecCodeModuleEx()
相似,但如果 cpathname 非NULL
,则模块对象的__cached__
属性将被设置为 cpathname。在这三个函数中,这是首选使用的函数。在版本 3.3 中添加。
在 3.12 版本中变更: 设置
__cached__
已被弃用。有关替代方案,请参见ModuleSpec
。
-
PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)¶
- 返回值:新引用。 属于 稳定 ABI 的一部分。
类似于
PyImport_ExecCodeModuleObject()
,但 name、pathname 和 cpathname 是 UTF-8 编码的字符串。如果 pathname 设置为NULL
,也会尝试从 cpathname 中推断出 pathname 的值。在 3.2 版本中添加。
在 3.3 版本中更改: 如果只提供字节码路径,则使用
imp.source_from_cache()
计算源路径。在 3.12 版本中更改: 不再使用已移除的
imp
模块。
-
long PyImport_GetMagicNumber()¶
- 是 稳定 ABI 的一部分。
返回 Python 字节码文件(也称为
.pyc
文件)的魔数。魔数应该以小端字节序出现在字节码文件的前四个字节中。如果出错,则返回-1
。在 3.3 版本中更改: 失败时返回
-1
。
-
const char *PyImport_GetMagicTag()¶
- 是 稳定 ABI 的一部分。
返回 PEP 3147 格式 Python 字节码文件名对应的魔数标签字符串。请记住,
sys.implementation.cache_tag
中的值是权威的,应该优先使用它,而不是这个函数。在 3.2 版本中添加。
-
PyObject *PyImport_GetModuleDict()¶
- 返回值:借用引用。 作为 稳定 ABI 的一部分。
返回用于模块管理的字典(也称为
sys.modules
)。请注意,这是一个解释器级别的变量。
-
PyObject *PyImport_GetModule(PyObject *name)¶
- 返回值:新引用。 从 3.8 版本开始是 稳定 ABI 的一部分。
返回已导入的具有给定名称的模块。如果模块尚未导入,则返回
NULL
,但不设置错误。如果查找失败,则返回NULL
并设置错误。在 3.7 版本中添加。
-
PyObject *PyImport_GetImporter(PyObject *path)¶
- 返回值:新引用。 属于 稳定 ABI 的一部分。
返回
sys.path
/pkg.__path__
项目 path 的查找器对象,可能从sys.path_importer_cache
字典中获取。如果它还没有被缓存,则遍历sys.path_hooks
直到找到一个可以处理路径项目的钩子。如果找不到钩子,则返回None
;这告诉我们的调用者,基于路径的查找器 无法为该路径项目找到查找器。将结果缓存到sys.path_importer_cache
中。返回对查找器对象的新的引用。
-
int PyImport_ImportFrozenModuleObject(PyObject *name)¶
- 自版本 3.7 起,是 稳定 ABI 的一部分。
加载名为 name 的冻结模块。如果成功,则返回
1
,如果未找到模块,则返回0
,如果初始化失败,则返回-1
,并设置异常。要访问成功加载的导入模块,请使用PyImport_ImportModule()
。(注意这个误称——如果模块已经导入,这个函数会重新加载它。)在版本 3.3 中添加。
在版本 3.4 中更改: 模块不再设置
__file__
属性。
-
int PyImport_ImportFrozenModule(const char *name)¶
- 是 稳定 ABI 的一部分。
类似于
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; bool is_package; };
在版本 3.11 中更改: 新的
is_package
字段指示模块是否是包。这取代了将size
字段设置为负值。
-
const struct _frozen *PyImport_FrozenModules¶
此指针初始化为指向
_frozen
记录的数组,以所有成员都为NULL
或零的记录结束。当导入冻结模块时,会在该表中搜索它。第三方代码可以利用此功能来提供动态创建的冻结模块集合。
-
int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))¶
- 是 稳定 ABI 的一部分。
将单个模块添加到现有的内置模块表中。这是对
PyImport_ExtendInittab()
的便捷包装器,如果无法扩展表,则返回-1
。新模块可以通过名称 name 导入,并使用函数 initfunc 作为在第一次尝试导入时调用的初始化函数。这应该在Py_Initialize()
之前调用。
-
struct _inittab¶
描述内置模块列表中单个条目的结构。嵌入 Python 的程序可以使用这些结构的数组与
PyImport_ExtendInittab()
结合使用,以提供额外的内置模块。该结构包含两个成员-
const char *name¶
模块名称,作为 ASCII 编码的字符串。
-
const char *name¶
-
int PyImport_ExtendInittab(struct _inittab *newtab)¶
将一组模块添加到内置模块表中。newtab 数组必须以一个包含
NULL
的哨兵条目结束,该条目对应于name
字段;如果未提供哨兵值,可能会导致内存故障。如果成功,则返回0
,如果无法分配足够的内存来扩展内部表,则返回-1
。如果失败,则不会将任何模块添加到内部表中。这必须在Py_Initialize()
之前调用。如果 Python 初始化多次,则必须在每次 Python 初始化之前调用
PyImport_AppendInittab()
或PyImport_ExtendInittab()
。