importlib.resources – Leitura, abertura e acesso aos recursos de pacote

Código-fonte: Lib/importlib/resources/__init__.py

Novo na versão 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.

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.Package

Sempre que uma função aceitar um argumento Package, você poderá passar um objeto módulo ou um nome de módulo como uma string. Você só pode passar objetos de módulo cujo __spec__.submodule_search_locations não seja None.

O tipo Package é definido como 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.

Novo na versão 3.9.

importlib.resources.as_file(traversable)

Given a Traversable object representing a file, typically from importlib.resources.files(), return a context manager for use in a with statement. The context manager provides a pathlib.Path object.

Exiting the context manager cleans up any temporary file created when the resource was extracted from e.g. a zip file.

Use as_file when the Traversable methods (read_text, etc) are insufficient and an actual file on the file system is required.

Novo na versão 3.9.

Funções descontinuadas

Um conjunto de funções mais antigo e descontinuado ainda está disponível, mas está programado para ser removido em uma versão futura do Python. A principal desvantagem dessas funções é que elas não oferecem suporte a diretórios: elas presumem que todos os recursos estão localizados diretamente em um package.

importlib.resources.Resource

Para os argumentos resource das funções abaixo, você pode passar o nome de um recurso como uma string ou um objeto caminho ou similar.

O tipo Resource é definido como Union[str, os.PathLike].

importlib.resources.open_binary(package, resource)

Abre para leitura binária o resource dentro do package.

package é um nome ou um objeto módulo que está em conformidade com os requisitos do Package. resource é o nome do recurso a ser aberto dentro de package; ele não pode conter separadores de caminho e não pode ter sub-recursos (ou seja, não pode ser um diretório). Essa função retorna uma instância de typing.BinaryIO, um fluxo de E/S binário aberto para leitura.

Obsoleto desde a versão 3.11: Chamadas para essa função podem ser substituídas por:

files(package).joinpath(resource).open('rb')
importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')

Abre para leitura de texto o resource dentro do package. Por padrão, o recurso é aberto para leitura como UTF-8.

package é um nome ou um objeto módulo que está em conformidade com os requisitos do Package. resource é o nome do recurso a ser aberto dentro de package; ele não pode conter separadores de caminho e não pode ter sub-recursos (ou seja, não pode ser um diretório). encoding e errors têm o mesmo significado que com open() embutido.

Essa função retorna uma instância de typing.TextIO, um fluxo de E/S de texto aberto para leitura.

Obsoleto desde a versão 3.11: Chamadas para essa função podem ser substituídas por:

files(package).joinpath(resource).open('r', encoding=encoding)
importlib.resources.read_binary(package, resource)

Lê e retorna o conteúdo do resource dentro do package como bytes.

package é um nome ou um objeto módulo que está em conformidade com os requisitos do Package. resource é o nome do recurso a ser aberto dentro de package; ele não pode conter separadores de caminho e não pode ter sub-recursos (ou seja, não pode ser um diretório). Essa função retorna o conteúdo do recurso como bytes.

Obsoleto desde a versão 3.11: Chamadas para essa função podem ser substituídas por:

files(package).joinpath(resource).read_bytes()
importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')

Lê e retorna o conteúdo de resource em package como str. Por padrão, o conteúdo é lido como UTF-8 estrito.

package é um nome ou um objeto módulo que está em conformidade com os requisitos do Package. resource é o nome do recurso a ser aberto dentro de package; ele não pode conter separadores de caminho e não pode ter sub-recursos (ou seja, não pode ser um diretório). encoding e errors têm o mesmo significado que com open() embutido. Esta função retorna o conteúdo do recurso como str.

Obsoleto desde a versão 3.11: Chamadas para essa função podem ser substituídas por:

files(package).joinpath(resource).read_text(encoding=encoding)
importlib.resources.path(package, resource)

Retorna o caminho para o resource como um caminho real do sistema de arquivos. Essa função retorna um gerenciador de contexto para uso em uma instrução with. O gerenciador de contexto fornece um objeto pathlib.Path.

Sair do gerenciador de contexto limpa qualquer arquivo temporário criado quando o recurso precisa ser extraído, por exemplo, de um arquivo zip.

package é um nome ou um objeto módulo que está em conformidade com os requisitos do Package. resource é o nome do recurso a ser aberto dentro de package; ele não pode conter separadores de caminho e não pode ter sub-recursos (ou seja, não pode ser um diretório).

Obsoleto desde a versão 3.11: Chamadas para essa função podem ser substituídas usando as_file():

as_file(files(package).joinpath(resource))
importlib.resources.is_resource(package, name)

Retorna True se houver um recurso chamado name no pacote; caso contrário, retorna False. Essa função não considera os diretórios como recursos. package é um nome ou um objeto módulo que está em conformidade com os requisitos de Package.

Obsoleto desde a versão 3.11: Chamadas para essa função podem ser substituídas por:

files(package).joinpath(resource).is_file()
importlib.resources.contents(package)

Retorna um iterável sobre os itens nomeados no pacote. O iterável retorna str recursos (por exemplo, arquivos) e não recursos (por exemplo, diretórios). O iterável não recorre a subdiretórios.

package é um nome ou um objeto módulo que está em conformidade com os requisitos de Package.

Obsoleto desde a versão 3.11: Chamadas para essa função podem ser substituídas por:

(resource.name for resource in files(package).iterdir() if resource.is_file())