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

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

在 3.7 版本加入.

This module leverages Python's import system to provide access to resources within packages. If you can import a package, you can access resources within that package. Resources can be opened or read, in either binary or text mode.

资源大致相当于目录内的文件，不过需要记住这只是一个比喻。 资源和包 不是 必须如文件系统上的物理文件和目录那样存在的：例如，一个包及其资源可使用 `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())