importlib.resources — 包资源的读取、打开和访问

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

Added in version 3.7.

此模块调整了 Python 的导入系统以便提供对 包 内部的 资源 的访问。

“资源”是指 Python 中与模块或包相关联的文件类资源。 资源可以直接包含在某个包中，包含在某个包的子目录中，或是与某个包外部的模块相邻。 资源可以是文本或二进制数据。 因此，从技术上说 Python 包的模块源代码文件 (.py) 和编译结果文件 (pycache) 就是包实际所包含的资源。 但是，在实践中，资源主要是指包作者专门公开的非 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.Anchor

代表资源的锚点，可以是一个 模块对象 或字符串形式的模块名称不。 定义为 Union[str, ModuleType]。

importlib.resources.files(anchor: Anchor | None = None)

返回一个代表资源容器（相当于目录）及其资源（相当于文件）的 Traversable 对象。 Traversable 可以包含其他容器（相当于子目录）。

anchor 是一个可选的 Anchor。 如果 anchor 是一个包，则会从这个包获取资源。 如果是一个模块，则会从这个模块的相邻位置获取资源（在同一个包或包的根目录中）。 如果省略了 anchor,则会使用调用方的模块。

Added in version 3.9.

在 3.12 版本发生变更: package 形参被重命名为 anchor。 anchor 现在可以是一个不为包的模块，如果被省略则默认为调用方的模块。 为保持兼容性 package 仍然被接受但会引发 DeprecationWarning。 请考虑以位置参数方式传入或使用 importlib_resources >= 5.10 作为针对旧版 Python 的兼容接口。

importlib.resources.as_file(traversable)

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

退出上下文管理器后会清除从 zip 文件等提取资源时创建的任何临时文件或目录。

当 Traversable 的方法（如 read_text 等）不足以满足需要而需要文件系统中的真实文件或目录时请使用 as_file。

Added in version 3.9.

在 3.12 版本发生变更: 增加了对代表目录的 traversable 的支持。

函数式 API

提供了一套简化的、向下兼容的辅助工具。 这些工具使得常用操作只需一次函数调用即可完成。

对于以下所有函数：

  • anchor 是一个 Anchor，就像在 files() 中的一样。 与在 files 中不同，它不可被省略。

  • path_names 是相对于 anchor 的资源的路径名的各个组成部分。 例如，要获取名为 info.txt 的资源的文本，则使用:

    1. importlib.resources.read_text(my_module, "info.txt")

    类似于 Traversable.joinpath，单独的组成部分应当使用正斜杠 (/) 作为路径分隔符。 例如，下面这些条目是等价的:

    1. importlib.resources.read_binary(my_module, "pics/painting.png")
    2. importlib.resources.read_binary(my_module, "pics", "painting.png")

    出于保持向下兼容性的理由，如果给出了多个 path_names 则读取文本的函数需要一个显式的 encoding 参数。 例如，要获取 info/chapter1.txt 的文本，则使用:

    1. importlib.resources.read_text(my_module, "info", "chapter1.txt",
    2.                               encoding='utf-8')

importlib.resources.open_binary(anchor, *path_names)

打开指定的资源用于二进制读取。

请参阅 说明文档 了解 anchor 和 path_names 的详情。

此函数返回一个 BinaryIO 对象，即一个打开供读取的二进制流。

此函数大致等价于:

  1. files(anchor).joinpath(*path_names).open('rb')

在 3.13 版本发生变更: 可接受多个 path_names。

importlib.resources.open_text(anchor, *path_names, encoding=’utf-8’, errors=’strict’)

打开指定的资源用于文本读取。 在默认情况下，将使用严格 UTF-8 编码读取内容。

请参阅 说明文档 了解 anchor 和 path_names 的详情。 encoding 和 errors 的含义与在内置 open() 中的相同。

出于保持向下兼容性的理由，如果有多个 path_names 则需要显式地给出 encoding 参数。 此限制计划在 Python 3.15 中去除。

此函数返回一个 TextIO 对象，即一个打开供读取的文本流。

此函数大致等价于:

  1. files(anchor).joinpath(*path_names).open('r', encoding=encoding)

在 3.13 版本发生变更: 可接受多个 path_names。 必须以关键字参数形式给出 encoding 和 errors。

importlib.resources.read_binary(anchor, *path_names)

以 bytes 形式读取并返回指定资源的内容。

请参阅 说明文档 了解 anchor 和 path_names 的详情。

此函数大致等价于:

  1. files(anchor).joinpath(*path_names).read_bytes()

在 3.13 版本发生变更: 可接受多个 path_names。

importlib.resources.read_text(anchor, *path_names, encoding=’utf-8’, errors=’strict’)

以 str 形式读取并返回指定资源的内容。 在默认情况下，将使用严格 UTF-8 编码读取内容。

请参阅 说明文档 了解 anchor 和 path_names 的详情。 encoding 和 errors 的含义与在内置 open() 中的相同。

出于保持向下兼容性的理由，如果有多个 path_names 则需要显式地给出 encoding 参数。 此限制计划在 Python 3.15 中去除。

此函数大致等价于:

  1. files(anchor).joinpath(*path_names).read_text(encoding=encoding)

在 3.13 版本发生变更: 可接受多个 path_names。 必须以关键字参数形式给出 encoding 和 errors。

importlib.resources.path(anchor, *path_names)

以实际文件系统路径的形式提供 resource 的路径。 此函数返回一个可在 with 语句中使用的上下文管理器。 该上下文管理器将提供一个 pathlib.Path 对象。

退出上下文管理器时将清理已创建的任何临时文件，例如在需要从 zip 文件提取资源时就将创建临时文件。

例如，stat() 方法需要一个实际的文件系统路径；可以这样使用它:

  1. with importlib.resources.path(anchor, "resource.txt") as fspath:
  2.     result = fspath.stat()

请参阅 说明文档 了解 anchor 和 path_names 的详情。

此函数大致等价于:

  1. as_file(files(anchor).joinpath(*path_names))

在 3.13 版本发生变更: 可接受多个 path_names。 必须以关键字参数形式给出 encoding 和 errors。

importlib.resources.is_resource(anchor, *path_names)

如果指定的资源存在则返回 True，否则返回 False。 此函数不会考虑目录作为资源的情况。

请参阅 说明文档 了解 anchor 和 path_names 的详情。

此函数大致等价于:

  1. files(anchor).joinpath(*path_names).is_file()

在 3.13 版本发生变更: 可接受多个 path_names。

importlib.resources.contents(anchor, *path_names)

返回一个用于遍历指定的包或路径内条目的可迭代对象。 该可迭代对象将以 str 的形式返回资源（例如文件）和非资源（例如目录）。 该迭代器不会递归进入子目录。

请参阅 说明文档 了解 anchor 和 path_names 的详情。

此函数大致等价于:

  1. for resource in files(anchor).joinpath(*path_names).iterdir():
  2.     yield resource.name

自 3.11 版本弃用: 首选上面的 iterdir()，它提供了对结果的更多控制和更丰富的功能。