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