"importlib.resources.abc" -- Classes base abstratas para recursos
*****************************************************************

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

======================================================================

Adicionado na versão 3.11.

class importlib.resources.abc.ResourceReader

   *Substituída por TraversableResources*

   Uma *classe base abstrata* para fornecer a capacidade de ler
   *recursos*.

   Da perspectiva deste ABC, um *recurso* é um artefato binário que é
   enviado dentro de um pacote. Normalmente isso é algo como um
   arquivo de dados que fica próximo ao arquivo "__init__.py" do
   pacote. O objetivo desta classe é ajudar a abstrair o acesso a tais
   arquivos de dados para que não importe se o pacote e seu(s)
   arquivo(s) de dados estão armazenados, por exemplo, em um arquivo
   zip versus no sistema de arquivos.

   Para qualquer um dos métodos desta classe, espera-se que o
   argumento *resource* seja um *objeto caminho ou similar* que
   representa conceitualmente apenas um nome de arquivo. Isso
   significa que nenhum caminho de subdiretório deve ser incluído no
   argumento *resource*. Isso ocorre porque a localização do pacote
   para o qual o leitor se destina, atua como o "diretório". Portanto,
   a metáfora para diretórios e nomes de arquivos são pacotes e
   recursos, respectivamente. É também por isso que se espera que as
   instâncias dessa classe se correlacionem diretamente a um pacote
   específico (em vez de representar potencialmente vários pacotes ou
   um módulo).

   Carregadores que desejam oferecer suporte à leitura de recursos
   devem fornecer um método chamado
   "get_resource_reader(nomecompleto)" que retorna um objeto
   implementando esta interface ABC. Se o módulo especificado por
   nomecompleto não for um pacote, este método deve retornar "None".
   Um objeto compatível com este ABC só deve ser retornado quando o
   módulo especificado for um pacote.

   Descontinuado desde a versão 3.12: Use
   "importlib.resources.abc.TraversableResources".

   abstractmethod open_resource(resource)

         Retorna um *objeto arquivo ou similar* aberto para leitura
         binária de *resource*.

         Se o recurso não puder ser encontrado, "FileNotFoundError" é
         levantada.

   abstractmethod resource_path(resource)

         Retorna o caminho do sistema de arquivos para *resource*.

         Se o recurso não existir concretamente no sistema de
         arquivos, levanta "FileNotFoundError".

   abstractmethod is_resource(name)

         Retorna "True" se o *name* nomeado for considerado um
         recurso. "FileNotFoundError" é levantada se *name* não
         existir.

   abstractmethod contents()

         Retorna um *iterável* de strings sobre o conteúdo do pacote.
         Observe que não é necessário que todos os nomes retornados
         pelo iterador sejam recursos reais, por exemplo, é aceitável
         retornar nomes para os quais "is_resource()" seria falso.

         Permitir que nomes que não são recursos sejam retornados é
         permitir situações em que a forma como um pacote e seus
         recursos são armazenados é conhecida a priori e os nomes que
         não são recursos seriam úteis. Por exemplo, o retorno de
         nomes de subdiretórios é permitido para que, quando se souber
         que o pacote e os recursos estão armazenados no sistema de
         arquivos, esses nomes de subdiretórios possam ser usados
         diretamente.

         O método abstrato retorna um iterável sem itens.

class importlib.resources.abc.Traversable

   Um objeto com um subconjunto de métodos de "pathlib.Path" adequados
   para percorrer diretórios e abrir arquivos.

   Para uma representação do objeto no sistema de arquivos, use
   "importlib.resources.as_file()".

   name

      Abstrato. O nome base deste objeto sem nenhuma referência pai.

   abstractmethod iterdir()

      Produz objetos Traversable em self.

   abstractmethod is_dir()

      Retorna "True" se self for um diretório.

   abstractmethod is_file()

      Retorna "True" se self for um arquivo.

   abstractmethod joinpath(*pathsegments)

      Percorre os diretórios de acordo com *pathsegments* e retorna o
      resultado como "Traversable".

      Cada argumento *pathsegments* pode conter vários nomes separados
      por barras ("/", "posixpath.sep"). Por exemplo, os seguintes são
      equivalentes:

         files.joinpath('subdir', 'subsuddir', 'arquivo.txt')
         files.joinpath('subdir/subsuddir/arquivo.txt')

      Observe que algumas implementações de "Traversable" podem não
      ser atualizadas para a versão mais recente do protocolo. Para
      compatibilidade com tais implementações, forneça um único
      argumento sem separadores de caminho para cada chamada para
      "joinpath". Por exemplo:

         files.joinpath('subdir').joinpath('subsubdir').joinpath('arquivo.txt')

      Alterado na versão 3.11: "joinpath" aceita múltiplos
      *pathsegments*, e estes segmentos podem conter barras como
      separadores de caminho. Anteriormente, apenas um único argumento
      *child* era aceito.

   abstractmethod __truediv__(child)

      Retorna um filho Traversable em si mesmo. Equivalente a
      "joinpath(child)".

   abstractmethod open(mode='r', *args, **kwargs)

      *mode* pode ser 'r' ou 'rb' para abrir como texto ou binário.
      Retorna um manipulador adequado para leitura (o mesmo que
      "pathlib.Path.open").

      Ao abrir como texto, aceita parâmetros de codificação como os
      aceitos por "io.TextIOWrapper".

   read_bytes()

      Lê o conteúdo de self como bytes.

   read_text(encoding=None)

      Lê o conteúdo de self como texto.

class importlib.resources.abc.TraversableResources

   Uma classe base abstrata para leitores de recursos capaz de servir
   a interface "importlib.resources.files()". É uma subclasse de
   "ResourceReader" e fornece implementações concretas dos métodos
   abstratos de "ResourceReader". Portanto, qualquer carregador que
   forneça "TraversableResources" também fornece "ResourceReader".

   Espera-se que os carregadores que desejam oferecer suporte à
   leitura de recursos implementem essa interface.

   abstractmethod files()

      Retorna um objeto "importlib.resources.abc.Traversable" para o
      pacote carregado.
