"collections.abc" --- Classes Base Abstratas para Contêineres
*************************************************************

Novo na versão 3.3: Anteriormente, esse módulo fazia parte do módulo
"collections".

**Código-fonte:** Lib/_collections_abc.py

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

Esse módulo fornece *classes base abstratas* que podem ser usadas para
testar se uma classe fornece uma interface específica; por exemplo, se
é hashable ou se é um mapeamento.


Classes Base Abstratas de Coleções
==================================

O módulo de coleções oferece o seguinte *ABCs*:

+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| ABC                        | Herda de               | Métodos Abstratos       | Métodos Mixin                                        |
|============================|========================|=========================|======================================================|
| "Container"                |                        | "__contains__"          |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Hashable"                 |                        | "__hash__"              |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Iterable"                 |                        | "__iter__"              |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Iterator"                 | "Iterable"             | "__next__"              | "__iter__"                                           |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Reversible"               | "Iterable"             | "__reversed__"          |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Generator"                | "Iterator"             | "send", "throw"         | "close", "__iter__", "__next__"                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Sized"                    |                        | "__len__"               |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Callable"                 |                        | "__call__"              |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Collection"               | "Sized", "Iterable",   | "__contains__",         |                                                      |
|                            | "Container"            | "__iter__", "__len__"   |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Sequence"                 | "Reversible",          | "__getitem__",          | "__contains__", "__iter__", "__reversed__", "index", |
|                            | "Collection"           | "__len__"               | and "count"                                          |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableSequence"          | "Sequence"             | "__getitem__",          | Herdado os métodos da "Sequence" e "append",         |
|                            |                        | "__setitem__",          | "reverse", "extend", "pop", "remove", e "__iadd__"   |
|                            |                        | "__delitem__",          |                                                      |
|                            |                        | "__len__", "insert"     |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ByteString"               | "Sequence"             | "__getitem__",          | Herdado "Sequence" métodos                           |
|                            |                        | "__len__"               |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Set"                      | "Collection"           | "__contains__",         | "__le__", "__lt__", "__eq__", "__ne__", "__gt__",    |
|                            |                        | "__iter__", "__len__"   | "__ge__", "__and__", "__or__", "__sub__", "__xor__", |
|                            |                        |                         | e "isdisjoint"                                       |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableSet"               | "Set"                  | "__contains__",         | Herdado "Set" métodos e "clear", "pop", "remove",    |
|                            |                        | "__iter__", "__len__",  | "__ior__", "__iand__", "__ixor__", e "__isub__"      |
|                            |                        | "add", "discard"        |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Mapping"                  | "Collection"           | "__getitem__",          | "__contains__", "keys", "items", "values", "get",    |
|                            |                        | "__iter__", "__len__"   | "__eq__", e "__ne__"                                 |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableMapping"           | "Mapping"              | "__getitem__",          | Herdado "Mapping" métodos e "pop", "popitem",        |
|                            |                        | "__setitem__",          | "clear", "update", e "setdefault"                    |
|                            |                        | "__delitem__",          |                                                      |
|                            |                        | "__iter__", "__len__"   |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MappingView"              | "Sized"                |                         | "__len__"                                            |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ItemsView"                | "MappingView", "Set"   |                         | "__contains__", "__iter__"                           |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "KeysView"                 | "MappingView", "Set"   |                         | "__contains__", "__iter__"                           |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ValuesView"               | "MappingView",         |                         | "__contains__", "__iter__"                           |
|                            | "Collection"           |                         |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Awaitable"                |                        | "__await__"             |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Coroutine"                | "Awaitable"            | "send", "throw"         | "close"                                              |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "AsyncIterable"            |                        | "__aiter__"             |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "AsyncIterator"            | "AsyncIterable"        | "__anext__"             | "__aiter__"                                          |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "AsyncGenerator"           | "AsyncIterator"        | "asend", "athrow"       | "aclose", "__aiter__", "__anext__"                   |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+

class collections.abc.Container

   ABC para classes que fornecem o método "__contains__()".

class collections.abc.Hashable

   ABC para classes que fornecem o método "__hash__()".

class collections.abc.Sized

   ABC para classes que fornecem o método "__len__()".

class collections.abc.Callable

   ABC para classes que fornecem o método "__call__()".

class collections.abc.Iterable

   ABC para classes que fornecem o método "__iter__()".

   A verificação "isinstance(obj, Iterable)" detecta classes que são
   registradas como "Iterable" ou que possuem um método "__iter__()",
   mas que não detecta classes que iteram com o método
   "__getitem__()". A única maneira confiável de determinar se um
   objeto é *iterável* é chamar "iter(obj)".

class collections.abc.Collection

   ABC para classes de contêiner iterável de tamanho.

   Novo na versão 3.6.

class collections.abc.Iterator

   ABC para classes que fornecem os métodos "__iter__()" e métodos
   "__next__()". Veja também a definição de *iterator*.

class collections.abc.Reversible

   ABC para classes iteráveis que também fornecem o método
   "__reversed__()".

   Novo na versão 3.6.

class collections.abc.Generator

   ABC para classes geradores que implementam o protocolo definido em
   **PEP 342** que estende os iteradores com os métodos "send()",
   "throw()" e "close()". Veja também a definição de *gerador*.

   Novo na versão 3.5.

class collections.abc.Sequence
class collections.abc.MutableSequence
class collections.abc.ByteString

   ABCs para *sequências* somente de leitura e mutáveis.

   Nota de implementação: Alguns dos métodos mixin, como "__iter__()",
   "__reversed__()" e "index()", fazem chamadas repetidas para o
   método subjacente "__getitem__()". Consequentemente, se
   "__getitem__()" for implementado com velocidade de acesso
   constante, os métodos mixin terão desempenho linear; no entanto se
   o método subjacente for linear (como seria com uma lista
   encadeada), os mixins terão desempenho quadrático e provavelmente
   precisará ser substituído.

   Alterado na versão 3.5: O método index() adicionou suporte para os
   argumentos *stop* e *start*.

class collections.abc.Set
class collections.abc.MutableSet

   ABCs para sets somente leitura e mutável.

class collections.abc.Mapping
class collections.abc.MutableMapping

   ABCs para somente leitura e mutável *mappings*.

class collections.abc.MappingView
class collections.abc.ItemsView
class collections.abc.KeysView
class collections.abc.ValuesView

   ABCs para mapeamento, itens, chaves e valores *views*.

class collections.abc.Awaitable

   ABC para objetos *aguardáveis*, que podem ser usados em expressões
   de "await". Implementações personalizadas devem fornecer o método
   "__await__()".

   Objetos e instâncias de *corrotina* da ABC "Coroutine" são todas
   instâncias dessa ABC.

   Nota:

     No CPython, as corrotinas baseados em gerador (geradoras
     decorados com "types.coroutine()" ou "asyncio.coroutine()") são
     *awaitables*, embora não possuam o método "__await__()". Usar
     "isinstance(gencoro, Awaitable)" para eles retornará "False". Use
     "inspect.isawaitable()" para detectá-los.

   Novo na versão 3.5.

class collections.abc.Coroutine

   ABC para classes compatíveis com corrotina. Eles implementam os
   seguintes métodos, definidos em Objetos corrotina: "send()",
   "throw()", e "close()". Implementações personalizadas também devem
   implementar "__await__()". Todas as instâncias "Coroutine" também
   são instâncias de "Awaitable". Veja também a definição de
   *corrotina*.

   Nota:

     Em CPython, as corrotinas baseadas em gerador (geradores
     decorados com "types.coroutine()" ou "asyncio.coroutine()") são
     *awaitables*, embora não possuam o método "__await__()". Usar
     "isinstance(gencoro, Coroutine)" para eles retornará "False". Use
     "inspect.isawaitable()" para detectá-los.

   Novo na versão 3.5.

class collections.abc.AsyncIterable

   ABC para classes que fornecem o método "__aiter__". Veja também a
   definição de *iterável assíncrono*.

   Novo na versão 3.5.

class collections.abc.AsyncIterator

   ABC para classes que fornecem os métodos "__aiter__" e "__anext__".
   Veja também a definição de *iterador assíncrono*.

   Novo na versão 3.5.

class collections.abc.AsyncGenerator

   ABC para classes de gerador assíncrono que implementam o protocolo
   definido em **PEP 525** e **PEP 492**.

   Novo na versão 3.6.

Esses ABCs nos permitem perguntar a classes ou instâncias se elas
fornecem funcionalidades específicas, por exemplo:

   size = None
   if isinstance(myvar, collections.abc.Sized):
       size = len(myvar)

Vários ABCS também são também úteis como mixins que facilitam o
desenvolvimento de classes que suportam APIs de contêiner. Por
exemplo, para escrever uma classe que suporte toda a API "Set" , é
necessário fornecer apenas os três métodos abstratos subjacentes:
"__contains__()", "__iter__()", e "__len__()". O ABC fornece os
métodos restantes, como "__and__()" e "isdisjoint()":

   class ListBasedSet(collections.abc.Set):
       ''' Alternate set implementation favoring space over speed
           and not requiring the set elements to be hashable. '''
       def __init__(self, iterable):
           self.elements = lst = []
           for value in iterable:
               if value not in lst:
                   lst.append(value)

       def __iter__(self):
           return iter(self.elements)

       def __contains__(self, value):
           return value in self.elements

       def __len__(self):
           return len(self.elements)

   s1 = ListBasedSet('abcdef')
   s2 = ListBasedSet('defghi')
   overlap = s1 & s2            # The __and__() method is supported automatically

Notas sobre o uso de "Set" e "MutableSet" como um mixin:

1. Como algumas operações de conjunto criam novos conjuntos, os
   métodos de mixin padrão precisam de uma maneira de criar novas
   instâncias a partir de uma iterável. Supõe-se que a classe
   construtor tenha uma assinatura no formato "ClassName(iterable)".
   Essa suposição é fatorada em um método de classe interno chamado:
   "_from_iterable()" que chama "cls(iterable)" para produzir um novo
   conjunto. Se o mixin "Set" estiver sendo usado em uma classe com
   uma assinatura de construtor diferente, você precisará substituir
   "_from_iterable()" por um método de classe que possa construir
   novas instâncias a partir de um argumento iterável.

2. Para substituir as comparações (presumivelmente para velocidade, já
   que a semântica é fixa), redefina "__le__()" e "__ge__()", então as
   outras operações seguirão o exemplo automaticamente.

3. O mixin "Set" fornece um método "_hash()" para calcular um valor de
   hash para o conjunto; no entanto, "__hash__()" não pe definido
   porque nem todos os conjuntos são encadeados ou imutáveis. Para
   adicionar capacidade de encadeamento em conjuntos usando mixin,
   herde de ambos "Set()" e "Hashable()", e então defina "__hash__ =
   Set._hash".

Ver também:

  * OrderedSet receita para um exemplo baseado em "MutableSet".

  * Para mais informações sobre ABCs, consulte o módulo "abc" e **PEP
    3119**.
