importlib.resources
– Leitura, abertura e acesso aos recursos de pacote¶
Código-fonte: Lib/importlib/resources/__init__.py
Adicionado na versão 3.7.
Esse módulo aproveita o sistema de importação do Python para fornecer acesso a recursos dentro de pacotes.
“Recursos” são recursos de arquivos ou similares associados a um módulo ou pacote em Python. Os recursos podem estar contidos diretamente em um pacote, em um subdiretório contido nesse pacote ou adjacentes a módulos fora de um pacote. Os recursos podem ser de texto ou binários. Como resultado, os códigos-fonte do módulo Python (.py) de um pacote e os artefatos de compilação (pycache) são tecnicamente recursos de fato desse pacote. Na prática, entretanto, os recursos são principalmente os artefatos não-Python expostos especificamente pelo autor do pacote.
Os recursos podem ser abertos ou lidos no modo binário ou de texto.
Os recursos são mais ou menos semelhantes a arquivos dentro de diretórios, embora seja importante ter em mente que isso é apenas uma metáfora. Recursos e pacotes não precisam existir como arquivos e diretórios físicos no sistema de arquivos: por exemplo, um pacote e seus recursos podem ser importados de um arquivo zip usando zipimport
.
Nota
Esse módulo fornece funcionalidade semelhante ao Basic Resource Access do pkg_resources sem a sobrecarga de desempenho desse pacote. Isso facilita a leitura de recursos incluídos em pacotes, com uma semântica mais estável e consistente.
O backport autônomo desse módulo fornece mais informações sobre uso do importlib.resources e migração do pkg_resources para o importlib.resources.
Loaders
que desejam oferecer suporte à leitura de recursos devem implementar um método get_resource_reader(fullname)
conforme especificado por importlib.resources.abc.ResourceReader
.
- class importlib.resources.Anchor¶
Representa uma âncora para recursos, seja um
objeto módulo
ou um nome de módulo como uma string. Definido comoUnion[str, ModuleType]
.
- importlib.resources.files(anchor: Anchor | None = None)¶
Retorna um objeto
Traversable
que representa o contêiner de recursos (pense em diretório) e seus recursos (pense em arquivos). Um Traversable pode conter outros contêineres (pense em subdiretórios).anchor é um
Anchor
opcional. Se a âncora for um pacote, os recursos são resolvidos a partir desse pacote. Se for um módulo, os recursos são resolvidos ao lado desse módulo (no mesmo pacote ou na raiz do pacote). Se a âncora for omitido, o módulo do chamador é usado.Adicionado na versão 3.9.
Alterado na versão 3.12: O parâmetro package foi renomeado para anchor. anchor agora pode ser um módulo sem ser pacote e, se omitido, será o módulo do chamador por padrão. package ainda é aceito por compatibilidade, mas irá levantar um
DeprecationWarning
. Considere passar a posição da âncora de forma posicional ou usarimportlib_resources >= 5.10
para uma interface compatível em versões mais antigas do Python.
- importlib.resources.as_file(traversable)¶
Dado um objeto
Traversable
que representa um arquivo ou diretório, normalmente deimportlib.resources.files()
, retorna um gerenciador de contexto para uso em uma instruçãowith
. O gerenciador de contexto fornece um objetopathlib.Path
.Sair do gerenciador de contexto limpa qualquer arquivo ou diretório temporário criado quando o recurso foi extraído, por exemplo, de um arquivo zip.
Use
as_file
quando os métodos de Traversable (read_text
, etc.) forem insuficientes e for necessário um arquivo ou diretório real no sistema de arquivos.Adicionado na versão 3.9.
Alterado na versão 3.12: Adicionado suporte para traversable representando um diretório.
Functional API¶
A set of simplified, backwards-compatible helpers is available. These allow common operations in a single function call.
For all the following functions:
anchor is an
Anchor
, as infiles()
. Unlike infiles
, it may not be omitted.path_names are components of a resource’s path name, relative to the anchor. For example, to get the text of resource named
info.txt
, use:importlib.resources.read_text(my_module, "info.txt")
Like
Traversable.joinpath
, The individual components should use forward slashes (/
) as path separators. For example, the following are equivalent:importlib.resources.read_binary(my_module, "pics/painting.png") importlib.resources.read_binary(my_module, "pics", "painting.png")
For backward compatibility reasons, functions that read text require an explicit encoding argument if multiple path_names are given. For example, to get the text of
info/chapter1.txt
, use:importlib.resources.read_text(my_module, "info", "chapter1.txt", encoding='utf-8')
- importlib.resources.open_binary(anchor, *path_names)¶
Open the named resource for binary reading.
See the introduction for details on anchor and path_names.
This function returns a
BinaryIO
object, that is, a binary stream open for reading.This function is roughly equivalent to:
files(anchor).joinpath(*path_names).open('rb')
Alterado na versão 3.13: Multiple path_names are accepted.
- importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')¶
Open the named resource for text reading. By default, the contents are read as strict UTF-8.
See the introduction for details on anchor and path_names. encoding and errors have the same meaning as in built-in
open()
.For backward compatibility reasons, the encoding argument must be given explicitly if there are multiple path_names. This limitation is scheduled to be removed in Python 3.15.
This function returns a
TextIO
object, that is, a text stream open for reading.This function is roughly equivalent to:
files(anchor).joinpath(*path_names).open('r', encoding=encoding)
Alterado na versão 3.13: Multiple path_names are accepted. encoding and errors must be given as keyword arguments.
- importlib.resources.read_binary(anchor, *path_names)¶
Read and return the contents of the named resource as
bytes
.See the introduction for details on anchor and path_names.
This function is roughly equivalent to:
files(anchor).joinpath(*path_names).read_bytes()
Alterado na versão 3.13: Multiple path_names are accepted.
- importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')¶
Read and return the contents of the named resource as
str
. By default, the contents are read as strict UTF-8.See the introduction for details on anchor and path_names. encoding and errors have the same meaning as in built-in
open()
.For backward compatibility reasons, the encoding argument must be given explicitly if there are multiple path_names. This limitation is scheduled to be removed in Python 3.15.
This function is roughly equivalent to:
files(anchor).joinpath(*path_names).read_text(encoding=encoding)
Alterado na versão 3.13: Multiple path_names are accepted. encoding and errors must be given as keyword arguments.
- importlib.resources.path(anchor, *path_names)¶
Provides the path to the resource as an actual file system path. This function returns a context manager for use in a
with
statement. The context manager provides apathlib.Path
object.Exiting the context manager cleans up any temporary files created, e.g. when the resource needs to be extracted from a zip file.
For example, the
stat()
method requires an actual file system path; it can be used like this:with importlib.resources.path(anchor, "resource.txt") as fspath: result = fspath.stat()
See the introduction for details on anchor and path_names.
This function is roughly equivalent to:
as_file(files(anchor).joinpath(*path_names))
Alterado na versão 3.13: Multiple path_names are accepted. encoding and errors must be given as keyword arguments.
- importlib.resources.is_resource(anchor, *path_names)¶
Return
True
if the named resource exists, otherwiseFalse
. This function does not consider directories to be resources.See the introduction for details on anchor and path_names.
This function is roughly equivalent to:
files(anchor).joinpath(*path_names).is_file()
Alterado na versão 3.13: Multiple path_names are accepted.
- importlib.resources.contents(anchor, *path_names)¶
Return an iterable over the named items within the package or path. The iterable returns names of resources (e.g. files) and non-resources (e.g. directories) as
str
. The iterable does not recurse into subdirectories.See the introduction for details on anchor and path_names.
This function is roughly equivalent to:
for resource in files(anchor).joinpath(*path_names).iterdir(): yield resource.name
Obsoleto desde a versão 3.11: Prefer
iterdir()
as above, which offers more control over the results and richer functionality.