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