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()