31.2. 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__)
这将向包的
__path__
添加在包名后的sys.path
上的所有目录子目录。如果想要将单个逻辑包的不同部分分布为多个目录,这将非常有用。它还查找从
*
与 name 参数匹配开始的*.pkg
文件。此功能类似于*.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 finder。如果 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。
如果是通过路径钩子新创建的,则返回的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包含一个’。’,finders将用于包含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 上的所有 packages (not 所有模块!),以便访问
__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()