"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"。
