pkgutil — 包扩展实用程序 — Python 文档
pkgutil — 包扩展实用程序
该模块为导入系统提供实用程序,特别是包支持。
- 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__
。 如果想要将单个逻辑包的不同部分作为多个目录分发,这将非常有用。它还查找
*.pkg
文件,其中*
与 name 参数匹配。 此功能类似于*.pth
文件(有关更多信息,请参阅 site 模块),除了它不包含以import
开头的特殊行。*.pkg
文件从表面上看是可信的:除了检查重复项外,在*.pkg
文件中找到的所有条目都会添加到路径中,无论它们是否存在于文件系统中。 (这是一个功能。)如果输入路径不是列表(如冷冻包的情况),则返回不变。 输入路径未修改; 返回扩展副本。 项目仅附加到副本的末尾。
假设 sys.path 是一个序列。 sys.path 中不是引用现有目录的字符串的项目将被忽略。 sys.path 上的 Unicode 项目在用作文件名时会导致错误可能会导致此函数引发异常(符合 os.path.isdir() 行为)。
- class pkgutil.ImpImporter(dirname=None)
PEP 302 Finder 包装了 Python 的“经典”导入算法。
如果 dirname 是一个字符串,则会创建一个 PEP 302 查找器来搜索该目录。 如果 dirname 是
None
,则会创建一个 PEP 302 查找器来搜索当前的 sys.path,加上任何冻结或内置的模块。请注意,ImpImporter 目前不支持通过放置在 sys.meta_path 上使用。
自 3.3 版起已弃用:不再需要此模拟,因为标准导入机制现在完全符合 PEP 302 并且可在 importlib 中使用。
- class pkgutil.ImpLoader(fullname, file, filename, etc)
Loader 包装了 Python 的“经典”导入算法。
自 3.3 版起已弃用:不再需要此模拟,因为标准导入机制现在完全符合 PEP 302 并且可在 importlib 中使用。
- pkgutil.find_loader(fullname)
为给定的 fullname 检索模块 loader。
这是围绕 importlib.util.find_spec() 的向后兼容性包装器,它将大多数失败转换为 ImportError 并且只返回加载程序而不是完整的
ModuleSpec
。3.3 版更改: 更新为直接基于 importlib 而不是依赖包内部 PEP 302 导入仿真。
在 3.4 版更改:更新为基于 PEP 451
- pkgutil.get_importer(path_item)
检索给定 path_item 的 finder。
如果返回的查找器是由路径挂钩新创建的,则它会缓存在 sys.path_importer_cache 中。
如果需要重新扫描 sys.path_hooks,可以手动清除缓存(或其中的一部分)。
3.3 版更改: 更新为直接基于 importlib 而不是依赖包内部 PEP 302 导入仿真。
- pkgutil.get_loader(module_or_name)
获取 module_or_name 的 loader 对象。
如果模块或包可通过正常的导入机制访问,则返回该机器相关部分的包装器。 如果无法找到或导入模块,则返回
None
。 如果命名模块尚未导入,则导入其包含的包(如果有),以建立包__path__
。3.3 版更改: 更新为直接基于 importlib 而不是依赖包内部 PEP 302 导入仿真。
在 3.4 版更改:更新为基于 PEP 451
- pkgutil.iter_importers(fullname=)
为给定的模块名称生成 finder 对象。
如果 fullname 包含“.”,则查找器将针对包含全名的包,否则它们将是所有已注册的顶级查找器(即 sys.meta_path 和 sys.path_hooks 上的那些)。
如果命名模块在一个包中,则该包将作为调用此函数的副作用而被导入。
如果未指定模块名称,则生成所有顶级查找程序。
3.3 版更改: 更新为直接基于 importlib 而不是依赖包内部 PEP 302 导入仿真。
- pkgutil.iter_modules(path=None, prefix=)
为 path 上的所有子模块产生 ModuleInfo,或者,如果 path 是
None
,则sys.path
上的所有顶级模块.path 应该是
None
或查找模块的路径列表。prefix 是输出时在每个模块名称前面输出的字符串。
笔记
仅适用于定义
iter_modules()
方法的 finder。 此接口是非标准的,因此该模块还提供了 importlib.machinery.FileFinder 和 zipimport.zipimporter 的实现。3.3 版更改: 更新为直接基于 importlib 而不是依赖包内部 PEP 302 导入仿真。
- pkgutil.walk_packages(path=None, prefix=, onerror=None)
在 path 上递归地为所有模块产生 ModuleInfo,或者,如果 path 是
None
,所有可访问的模块。path 应该是
None
或查找模块的路径列表。prefix 是输出时在每个模块名称前面输出的字符串。
请注意,此函数必须在给定的 路径 上导入所有 包 ( 不是 所有模块!),以便访问
__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()
方法的 finder。 此接口是非标准的,因此该模块还提供了 importlib.machinery.FileFinder 和 zipimport.zipimporter 的实现。3.3 版更改: 更新为直接基于 importlib 而不是依赖包内部 PEP 302 导入仿真。
- pkgutil.get_data(package, resource)
从包中获取资源。
这是 loader
get_data
API 的包装器。 package 参数应该是包的名称,采用标准模块格式 (foo.bar
)。 resource 参数应该是相对文件名的形式,使用/
作为路径分隔符。 不允许使用父目录名称..
,也不允许使用根目录名称(以/
开头)。该函数返回一个二进制字符串,它是指定资源的内容。
对于位于文件系统中的已经导入的包,这大致相当于:
d = os.path.dirname(sys.modules[package].__file__) data = open(os.path.join(d, resource), 'rb').read()
如果无法定位或加载包,或者它使用了不支持
get_data
的 loader,则返回None
。 特别是,命名空间包的加载器不支持get_data
。