"importlib.resources" -- 包资源的读取、打开和访问
*************************************************

**源代码:** Lib/importlib/resources/__init__.py

======================================================================

在 3.7 版本加入.

这个模块使得Python的导入系统提供了访问 *包* 内的 *资源* 的功能。如果能
够导入一个包，那么就能够访问那个包里面的资源。资源可以以二进制或文本模
式方式被打开或读取。

资源大致相当于目录内的文件，不过需要记住这只是一个比喻。 资源和包 **不
是** 必须如文件系统上的物理文件和目录那样存在的：例如，一个包及其资源
可使用 "zipimport" 从一个 ZIP 文件导入。

备注:

  本模块提供了类似于 pkg_resources Basic Resource Access 的功能而没有
  那样高的性能开销。 这使得读取包中的资源更为容易，并具有更为稳定和一
  致的语义。此模块的独立向下移植版本在 using importlib.resources 和
  migrating from pkg_resources to importlib.resources 中提供了更多信息
  。

想要支持资源读取的 "加载器" 应当实现
"importlib.resources.abc.ResourceReader" 中规定的
"get_resource_reader(fullname)" 方法。

class importlib.resources.Package

   只要一个函数接受 "Package" 参数，你就可以传入 "模块对象" 或字符串形
   式的模块名称。 你只能传入 "__spec__.submodule_search_locations" 不
   为 "None" 的模块对象。

   "Package" 类型是作为 "Union[str, ModuleType]" 定义的。

importlib.resources.files(package)

   Returns a "Traversable" object representing the resource container
   for the package (think directory) and its resources (think files).
   A Traversable may contain other containers (think subdirectories).

   *package* is either a name or a module object which conforms to the
   "Package" requirements.

   在 3.9 版本加入.

importlib.resources.as_file(traversable)

   给出代表某个文件的 "Traversable" 对象，通常是来自
   "importlib.resources.files()"，返回一个上下文管理器以供 "with" 语句
   使用。 该上下文管理器提供一个 "pathlib.Path" 对象。

   退出上下文管理程序时，可以清理所有临时文件，比如从压缩文件中提取资
   源时创建的那些文件。

   如果 Traversable 方法（"read_text" 等）不够用，需要文件系统中的实际
   文件时，请使用 "as_file"。

   在 3.9 版本加入.


弃用的函数
==========

一组旧式的，已被弃用的函数仍然可用，但预计会在未来的 Python 版本中被移
除。 这些函数的主要缺点是它们不支持目录：它们假定所有资源都直接位于
*package* 之下。

importlib.resources.Resource

   对于下列函数的 *resource* 参数，你可以传入字符串形式的资源名称或 "
   路径类对象"。

   "Resource" 类型是作为 "Union[str, os.PathLike]" 定义的。

importlib.resources.open_binary(package, resource)

   以二进制读方式打开 *package* 内的 *resource*。

   *package* 是包名或符合 "Package" 要求的模块对象。 *resource* 是要在
   *package* 内打开的资源名；不能包含路径分隔符，也不能有子资源（即不
   能为目录）。本函数将返回一个 "typing.BinaryIO" 实例以供读取，即一个
   已打开的二进制 I/O 流。

   自 3.11 版本弃用: 对此函数的调用可以被替换为:

      files(package).joinpath(resource).open('rb')

importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')

   以文本读方式打开 *package* 内的 *resource*。默认情况下，资源将以
   UTF-8 格式打开以供读取。

   *package* 是包名或符合 "Package" 要求的模块对象。 *resource* 是要在
   *package* 内打开的资源名；不能包含路径分隔符，也不能有子资源（即不
   能是目录）。*encoding* 和 *errors* 的含义与内置 "open()" 的一样。

   本函数返回一个 "typing.TextIO" 实例，即一个打开的文本 I/O  流对象以
   供读取。

   自 3.11 版本弃用: 对此函数的调用可以被替换为:

      files(package).joinpath(resource).open('r', encoding=encoding)

importlib.resources.read_binary(package, resource)

   读取并返回 *package* 中的 *resource* 内容，格式为 "bytes"。

   *package* 是包名或符合 "Package" 要求的模块对象。 *resource* 是要在
   *package* 内打开的资源名；不能包含路径分隔符，也不能有子资源（即不
   能是目录）。资源内容以 "bytes" 的形式返回。

   自 3.11 版本弃用: 对此函数的调用可以被替换为:

      files(package).joinpath(resource).read_bytes()

importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')

   读取并返回 *package* 中 *resource* 的内容，格式为 "str"。默认情况下
   ，资源内容将以严格的 UTF-8 格式读取。

   *package* 是包名或符合 "Package" 要求的模块对象。 *resource* 是要在
   *package* 内打开的资源名；不能包含路径分隔符，也不能有子资源（即不
   能是目录）。*encoding* 和 *errors* 的含义与内置 "open()" 的一样。资
   源内容将以 "str" 的形式返回。

   自 3.11 版本弃用: 对此函数的调用可以被替换为:

      files(package).joinpath(resource).read_text(encoding=encoding)

importlib.resources.path(package, resource)

   返回 *resource* 实际的文件系统路径。本函数返回一个上下文管理器，以
   供 "with" 语句中使用。上下文管理器提供一个 "pathlib.Path" 对象。

   退出上下文管理程序时，可以清理所有临时文件，比如从压缩文件中提取资
   源时创建的那些文件。

   *package* 是包名或符合 "Package" 要求的模块对象。 *resource* 是要在
   *package* 内打开的资源名；不能包含路径分隔符，也不能有子资源（即不
   能是目录）。

   自 3.11 版本弃用: 对此函数的调用可以使用 "as_file()" 来替换:

      as_file(files(package).joinpath(resource))

importlib.resources.is_resource(package, name)

   如果包中存在名为 *name* 的资源则返回 "True"，否则返回 "False"。 此
   函数不会将目录视为资源。 *package* 是包名或符合 "Package" 要求的模
   块对象。

   自 3.11 版本弃用: 对此函数的调用可以被替换为:

      files(package).joinpath(resource).is_file()

importlib.resources.contents(package)

   返回一个用于遍历包内各命名项的可迭代对象。该可迭代对象将返回 "str"
   资源（如文件）及非资源（如目录）。该迭代器不会递归进入子目录。

   *package* 是包名或符合 "Package" 要求的模块对象。

   自 3.11 版本弃用: 对此函数的调用可以被替换为:

      (resource.name for resource in files(package).iterdir() if resource.is_file())
