导入模块 — Python 文档

来自菜鸟教程
Python/docs/3.10/c-api/import
跳转至:导航、​搜索

导入模块

PyObject *PyImport_ImportModule(const char *name)

这是下面 PyImport_ImportModuleEx() 的简化接口,将 globalslocals 参数设置为 NULLXlevel ] 设置为 0。 当 name 参数包含一个点时(当它指定一个包的子模块时),fromlist 参数被设置为列表 ['*'] 以便返回值是命名模块而不是包含它的顶级包,否则会出现这种情况。 (不幸的是,当 name 实际上指定子包而不是子模块时,这会产生额外的副作用:加载包的 __all__ 变量中指定的子模块。)返回对导入的模块,或 NULL 在失败时设置异常。 模块导入失败不会将该模块留在 sys.modules 中。

此函数始终使用绝对导入。

PyObject *PyImport_ImportModuleNoBlock(const char *name)

此函数是 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)

导入一个模块。 这最好通过参考内置的 Python 函数 __import__() 来描述,因为标准的 __import__() 函数直接调用这个函数。

返回值是对导入的模块或顶级包的新引用,或在失败时设置异常的 NULL。 与 __import__() 一样,请求包的子模块时的返回值通常是顶级包,除非给出了非空的 fromlist

3.3 版中的新功能。

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)

类似于 PyImport_ImportModuleLevelObject(),但名称是 UTF-8 编码的字符串,而不是 Unicode 对象。

3.3 版更改: 不再接受 级别 的负值。

PyObject *PyImport_Import(PyObject *name)

这是一个调用当前“导入钩子函数”的高级接口(显式 level 为 0,表示绝对导入)。 它从当前全局变量的 __builtins__ 调用 __import__() 函数。 这意味着使用当前环境中安装的任何导入钩子完成导入。

此函数始终使用绝对导入。

PyObject *PyImport_ReloadModule(PyObject *m)
重新加载一个模块。 返回对重新加载的模块的新引用,或在失败时设置异常的 NULL(在这种情况下模块仍然存在)。
PyObject *PyImport_AddModuleObject(PyObject *name)

返回与模块名称对应的模块对象。 name 参数可以采用 package.module 的形式。 首先检查模块字典是否有,如果没有,创建一个新的并将其插入模块字典。 返回 NULL 并在失败时设置异常。

笔记

该函数不加载或导入模块; 如果模块尚未加载,您将获得一个空模块对象。 使用 PyImport_ImportModule() 或其变体之一导入模块。 name 的虚线名称暗示的包结构如果不存在,则不会创建。

3.3 版中的新功能。

PyObject *PyImport_AddModule(const char *name)
类似于 PyImport_AddModuleObject(),但名称是 UTF-8 编码的字符串,而不是 Unicode 对象。
PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)

给定模块名称(可能采用 package.module 形式)和从 Python 字节码文件读取或从内置函数 compile() 获得的代码对象,加载模块。 如果发生错误,则返回对模块对象的新引用,或 NULL 并设置异常。 name 在错误情况下从 sys.modules 中删除,即使 name 已经在 sys.modules 进入 PyImport_ExecCodeModule()。 将未完全初始化的模块留在 sys.modules 中是危险的,因为此类模块的导入无法知道模块对象是未知(并且可能根据模块作者的意图而损坏)状态。

模块的 __spec____loader__ 将使用适当的值进行设置(如果尚未设置)。 规范的加载器将设置为模块的 __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)

PyImport_ExecCodeModule()类似,但是模块对象的__file__属性设置为pathname,如果不是NULL

另见 PyImport_ExecCodeModuleWithPathnames()

PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)

PyImport_ExecCodeModuleEx()类似,但模块对象的__cached__属性设置为cpathname,如果不是NULL。 在这三个函数中,这是首选使用的一个。

3.3 版中的新功能。

PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)

类似于 PyImport_ExecCodeModuleObject(),但 namepathnamecpathname 是 UTF-8 编码的字符串。 还尝试找出 pathname 的值应该来自 cpathname,如果前者设置为 NULL

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()
返回用于模块管理的字典(又名 sys.modules)。 请注意,这是每个解释器的变量。
PyObject *PyImport_GetModule(PyObject *name)

返回具有给定名称的已导入模块。 如果模块尚未导入,则返回 NULL 但不会设置错误。 如果查找失败,则返回 NULL 并设置错误。

3.7 版中的新功能。

PyObject *PyImport_GetImporter(PyObject *path)
sys.path/pkg.__path__ 项目 path 返回一个 finder 对象,可能通过从 sys.path_importer_cache dict 中获取它。 如果尚未缓存,则遍历 sys.path_hooks 直到找到可以处理路径项的钩子。 如果没有钩子,则返回 None; 这告诉我们的调用者基于 路径的查找器 无法找到此路径项的查找器。 将结果缓存在 sys.path_importer_cache 中。 返回对 finder 对象的新引用。
int PyImport_ImportFrozenModuleObject(PyObject *name)

加载名为 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 或零的记录终止。 导入冻结模块时,将在此表中搜索。 第三方代码可以利用此技巧来提供动态创建的冻结模块集合。
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 数组必须以包含 name 字段的 NULL 的标记条目结束; 未能提供标记值可能会导致内存故障。 成功时返回 0,如果没有足够的内存来扩展内部表,则返回 -1。 如果发生故障,则不会向内部表添加任何模块。 这必须在 Py_Initialize() 之前调用。

如果 Python 被多次初始化,则必须在每次 Python 初始化之前调用 PyImport_AppendInittab()PyImport_ExtendInittab()