pkgutil — 包扩展实用程序¶
源代码： Lib/pkgutil.py
此模块为导入系统提供实用程序，特别是包支持。
- class pkgutil.ModuleInfo(module_finder, name, ispkg)¶
一个保存模块信息摘要的命名元组。
在版本 3.6 中添加。
- pkgutil.extend_path(path, name)¶
扩展构成包的模块的搜索路径。预期用途是在包的
__init__.py中放置以下代码from pkgutil import extend_path __path__ = extend_path(__path__, __name__)
对于
sys.path上的每个具有与包名称匹配的子目录的目录，将子目录添加到包的__path__中。如果希望将单个逻辑包的不同部分作为多个目录分发，这将非常有用。它还查找从
*匹配name 参数开头的*.pkg文件。此功能类似于*.pth文件（有关详细信息，请参阅site模块），除了它不特殊处理以import开头的行。一个*.pkg文件被视为面值：除了检查重复项之外，在*.pkg文件中找到的所有条目都将添加到路径中，无论它们是否存在于文件系统中。（这是一个功能。）如果输入路径不是列表（如冻结包的情况），则返回不变。输入路径不会被修改；返回一个扩展的副本。项目只追加到副本的末尾。
假设
sys.path是一个序列。sys.path中不引用现有目录的项目将被忽略。sys.path中的 Unicode 项目在用作文件名时导致错误，可能会导致此函数引发异常（与os.path.isdir()行为一致）。
- pkgutil.find_loader(fullname)¶
为给定的fullname检索模块 加载器。
这是
importlib.util.find_spec()的向后兼容包装器，它将大多数失败转换为ImportError，并且只返回加载器，而不是完整的importlib.machinery.ModuleSpec。在 3.4 版中更改： 更新为基于 PEP 451
从 3.12 版开始弃用，将在 3.14 版中删除： 改用
importlib.util.find_spec()。
- pkgutil.get_importer(path_item)¶
为给定的path_item检索 查找器。
如果路径挂钩新创建了返回的查找器，则将其缓存到
sys.path_importer_cache中。如果需要重新扫描
sys.path_hooks，可以手动清除缓存（或部分缓存）。
- pkgutil.get_loader(module_or_name)¶
获取module_or_name 的 加载器 对象。
如果可以通过常规导入机制访问模块或包，则返回该机制相关部分的包装器。如果找不到或无法导入模块，则返回
None。如果尚未导入命名模块，则导入其包含的包（如果有），以便建立包__path__。在版本 3.4 中更改：更新为基于 PEP 451
从 3.12 版开始弃用，将在 3.14 版中删除： 改用
importlib.util.find_spec()。
- pkgutil.iter_importers(fullname='')¶
为给定的模块名称生成 查找器 对象。
如果 fullname 包含
'.'，则查找器将用于包含 fullname 的包，否则它们将是所有已注册的顶级查找器（即sys.meta_path和sys.path_hooks上的查找器）。如果命名模块在包中，则在调用此函数时会导入该包作为副作用。
如果没有指定模块名称，则会生成所有顶级查找器。
- pkgutil.iter_modules(path=None, prefix='')¶
对path 上的所有子模块（如果 path 为
None，则对sys.path上的所有顶级模块）生成ModuleInfo。path 应为
None或用于查找模块的路径列表。prefix 是输出时要输出在每个模块名称前面的字符串。
注意
仅适用于定义
iter_modules()方法的 查找器。此接口是非标准的，因此该模块还为importlib.machinery.FileFinder和zipimport.zipimporter提供实现。
- pkgutil.walk_packages(path=None, prefix='', onerror=None)¶
对 path 上的所有模块（递归）生成
ModuleInfo（如果 path 为None，则对所有可访问的模块生成）。path 应为
None或用于查找模块的路径列表。prefix 是输出时要输出在每个模块名称前面的字符串。
请注意，此函数必须导入给定 path 上的所有包（不是所有模块！），才能访问
__path__属性以查找子模块。onerror 是一个函数，如果在尝试导入包时发生任何异常，则会使用一个参数（正在导入的包的名称）调用此函数。如果没有提供 onerror 函数，则会捕获并忽略
ImportError，而所有其他异常都会传播，从而终止搜索。示例
# list all modules python can access walk_packages() # list all submodules of ctypes walk_packages(ctypes.__path__, ctypes.__name__ + '.')
注意
仅适用于定义
iter_modules()方法的 查找器。此接口是非标准的，因此该模块还为importlib.machinery.FileFinder和zipimport.zipimporter提供实现。
- pkgutil.get_data(package, resource)¶
从包中获取资源。
这是 加载器
get_dataAPI 的包装器。package 参数应该是包的名称，采用标准模块格式 (foo.bar)。resource 参数应采用相对文件名形式，使用/作为路径分隔符。不允许使用父目录名称..，也不允许使用根名称（以/开头）。该函数返回一个二进制字符串，即指定资源的内容。
对于位于文件系统中且已导入的包，这大致相当于
d = os.path.dirname(sys.modules[package].__file__) data = open(os.path.join(d, resource), 'rb').read()
如果无法找到或加载包，或者它使用的 加载器 不支持
get_data，则返回None。特别是，加载器 对于 命名空间包 不支持get_data。
- pkgutil.resolve_name(name)¶
将名称解析为对象。
此功能在标准库中的许多地方使用（请参阅 bpo-12915） - 并且同等功能也存在于广泛使用的第三方包中，例如 setuptools、Django 和 Pyramid。
name 预计为以下格式之一的字符串，其中 W 是有效 Python 标识符的缩写，点表示这些伪正则表达式中的文字句点
W(.W)*W(.W)*:(W(.W)*)?
第一种形式仅用于向后兼容。它假定点分名称的某些部分是包，其余部分是包中某个位置的对象，可能嵌套在其他对象中。由于包的停止位置和对象层次结构的开始位置无法通过检查推断出来，因此必须使用此形式重复尝试导入。
在第二种形式中，调用者通过提供单个冒号明确划分点：冒号左侧的点分名称是要导入的包，冒号右侧的点分名称是该包中的对象层次结构。此形式中只需要一次导入。如果以冒号结尾，则返回模块对象。
该函数将返回一个对象（可能是模块），或引发以下异常之一
ValueError– 如果 name 不属于已识别的格式。ImportError– 如果导入失败，而本不应该失败。AttributeError– 如果在遍历导入包中的对象层次结构以获取所需对象时发生故障。在版本 3.9 中添加。