这个文档所针对的是一个已不再受支持的 Python 旧版本。 你应当升级版本，并阅读 Python 当前稳定版本的文档.

# `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__)

  This will add to the package's `__path__` all subdirectories of directories on `sys.path` named after the package. This is useful if one wants to distribute different parts of a single logical package as multiple directories.

  它还会查找开头部分 `*` 与 name 参数相匹配的 `*.pkg` 文件。 此特性与 `*.pth` 文件类似（请参阅 `site` 模块了解更多信息），区别在于它不会对以 `import` 开头的行做特别对待。 将按外在值对 `*.pkg` 文件添加信任：除了检查重复项，，所有在 `*.pkg` 文件中找到的条目都会被添加到路径中，不管它们是否存在于文件系统中。 （这是特性而非缺陷。）

  如果输入路径不是一个列表（已冻结包就是这种情况）则它将被原样返回。 输入路径不会被修改；将返回一个扩展的副本。 条目将被添加到副本的末尾。

  `sys.path` 会被假定为一个序列。 `sys.path` 中的条目如果不是指向现有目录的字符串则会被忽略。 `sys.path` 上当用作文件名时会导致错误的 Unicode 条目可以会使得此函数引发异常（与 `os.path.isdir()` 的行为一致）。

class `pkgutil.``ImpImporter`(dirname=None)

  包装了 Python 的 "经典" 导入算法的 PEP 302 查找器

  如果 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)

  包装了 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 对象。

  If fullname contains a '.', the finders will be for the package containing fullname, otherwise they will be all registered top level finders (i.e. those on both sys.meta_path and sys.path_hooks).

  如果指定的模块位于一个包内，则该包会作为发起调用此函数的附带影响被导入。

  如果未指定模块名称，则会产生所有的最高层级查找器。

  在 3.3 版更改: 更新为直接基于 `importlib` 而不是依赖于包内部的 PEP 302 导入模拟。

`pkgutil.``iter_modules`(path=None, prefix='')

  Yields `ModuleInfo` for all submodules on path, or, if path is `None`, all top-level modules on `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 (而不是 所有的模块！)，以便能访问 `__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`。 特别地，针对 命名空间包 的 loader 不支持 `get_data`。