"importlib.resources" -- Leitura, abertura e acesso a recursos de pacotes
*************************************************************************

**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 como "Union[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 omitida, 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 usar "importlib_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 de "importlib.resources.files()", 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 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.


API funcional
=============

An older, previously deprecated set of functions is still available.
The main drawback of these functions is that they do not support
directories: they assume all resources are located directly within a
*package*.

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

   Esta função é mais ou menos equivalente a:

      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.

   Esta função é mais ou menos equivalente a:

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

   Esta função é mais ou menos equivalente a:

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

   Esta função é mais ou menos equivalente a:

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

   This function is roughly equivalent to

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

   Esta função é mais ou menos equivalente a:

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

   Esta função é mais ou menos equivalente a:

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