importlib.resources – 包资源读取、打开和访问¶
源代码: Lib/importlib/resources/__init__.py
在 3.7 版本中添加。
此模块利用 Python 的导入系统来提供对包内资源的访问。
“资源”是与 Python 中的模块或包关联的类文件资源。资源可以直接包含在包中，包含在该包内的子目录中，或与包外的模块相邻。资源可以是文本或二进制文件。因此，包的 Python 模块源 (.py) 和编译工件 (pycache) 在技术上是该包的事实资源。然而，在实践中，资源主要是由包作者专门公开的非 Python 工件。
资源可以在二进制或文本模式下打开或读取。
资源大致类似于目录内的文件，但重要的是要记住这只是一种比喻。资源和包不必作为文件系统上的物理文件和目录存在：例如，可以使用 zipimport 从 zip 文件导入包及其资源。
注意
此模块提供的功能类似于 pkg_resources 基本资源访问，而没有该包的性能开销。这使得读取包中包含的资源更容易，具有更稳定和一致的语义。
此模块的独立反向移植提供了有关 使用 importlib.resources 和 从 pkg_resources 迁移到 importlib.resources 的更多信息。
希望支持资源读取的 加载器 应该实现 importlib.resources.abc.ResourceReader 指定的 get_resource_reader(fullname) 方法。
- importlib.resources.files(anchor: Anchor | None = None)¶
返回一个
Traversable对象，该对象表示资源容器（可以认为是目录）及其资源（可以认为是文件）。Traversable 可能包含其他容器（可以认为是子目录）。anchor 是一个可选的
Anchor。如果 anchor 是一个包，则从该包解析资源。如果是一个模块，则在模块旁边（在同一个包或包根中）解析资源。如果省略 anchor，则使用调用者的模块。在 3.9 版本中添加。
在 3.12 版本中更改: package 参数已重命名为 anchor。anchor 现在可以是非包模块，如果省略则默认为调用者的模块。为了兼容性，仍然接受 package，但会引发
DeprecationWarning。考虑按位置传递 anchor 或对旧版 Python 使用importlib_resources >= 5.10以获得兼容的接口。
- importlib.resources.as_file(traversable)¶
给定一个表示文件或目录的
Traversable对象，通常来自importlib.resources.files()，返回一个上下文管理器，用于with语句中。上下文管理器提供一个pathlib.Path对象。退出上下文管理器会清理从 zip 文件等提取资源时创建的任何临时文件或目录。
当 Traversable 方法（
read_text等）不足并且需要文件系统上的实际文件或目录时，请使用as_file。在 3.9 版本中添加。
在 3.12 版本中更改: 添加了对表示目录的 traversable 的支持。
函数式 API¶
提供了一组简化的、向后兼容的帮助程序。这些允许在单个函数调用中执行常见操作。
对于以下所有函数
path_names 是相对于 anchor 的资源路径名称的组成部分。例如，要获取名为
info.txt的资源的文本，请使用importlib.resources.read_text(my_module, "info.txt")
与
Traversable.joinpath类似，各个组成部分应使用正斜杠 (/) 作为路径分隔符。例如，以下是等效的importlib.resources.read_binary(my_module, "pics/painting.png") importlib.resources.read_binary(my_module, "pics", "painting.png")
出于向后兼容性的原因，如果给定多个 path_names，则读取文本的函数需要显式的 encoding 参数。例如，要获取
info/chapter1.txt的文本，请使用importlib.resources.read_text(my_module, "info", "chapter1.txt", encoding='utf-8')
- importlib.resources.open_binary(anchor, *path_names)¶
打开指定名称的资源以进行二进制读取。
有关 anchor 和 path_names 的详细信息，请参阅 简介。
此函数返回一个
BinaryIO对象，即一个打开以进行读取的二进制流。此函数大致等效于
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对象，即用于读取的文本流。此函数大致等效于
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 的详细信息，请参阅 简介。
此函数大致等效于
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 中移除。
此函数大致等效于
files(anchor).joinpath(*path_names).read_text(encoding=encoding)
3.13 版本更改: 接受多个path_names。encoding和errors必须作为关键字参数给出。
- importlib.resources.path(anchor, *path_names)¶
提供作为实际文件系统路径的资源的路径。此函数返回一个上下文管理器，用于
with语句中。上下文管理器提供一个pathlib.Path对象。退出上下文管理器会清理创建的任何临时文件，例如，当需要从 zip 文件中提取资源时。
例如，
stat()方法需要实际的文件系统路径；它可以像这样使用with importlib.resources.path(anchor, "resource.txt") as fspath: result = fspath.stat()
有关 anchor 和 path_names 的详细信息，请参阅 简介。
此函数大致等效于
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 的详细信息，请参阅 简介。
此函数大致等效于
files(anchor).joinpath(*path_names).is_file()
在 3.13 版本中更改: 接受多个 path_names。
- importlib.resources.contents(anchor, *path_names)¶
返回包或路径中命名项的可迭代对象。此可迭代对象返回资源（例如文件）和非资源（例如目录）的名称，以
str形式。此可迭代对象不会递归到子目录中。有关 anchor 和 path_names 的详细信息，请参阅 简介。
此函数大致等效于
for resource in files(anchor).joinpath(*path_names).iterdir(): yield resource.name
3.11 版本起已弃用: 优先选择上面的
iterdir()，它可以提供对结果的更多控制和更丰富的功能。