# `collections.abc` — Classes Base Abstratas para Contêineres

Adicionado 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 é hasheável ou se é um mapeamento.

Um teste `issubclass()` ou `isinstance()` para uma interface funciona em uma das três formas.

1. Uma classe recém-escrita pode herdar diretamente de uma das classes base abstratas. A classe deve fornecer os métodos abstratos necessários. Os métodos mixin restantes vêm da herança e podem ser substituídos se desejado. Outros métodos podem ser adicionados conforme necessário:

       class C(Sequence):                      # Herança direta
           def __init__(self): ...             # Método extra não exigido pela ABC
           def __getitem__(self, index):  ...  # Método abstrato exigido
           def __len__(self):  ...             # Método abstrato exigido
           def count(self, value): ...         # Opcionalmente substitui um método mixin

       >>> issubclass(C, Sequence)
       True
       >>> isinstance(C(), Sequence)
       True

2. Classes existentes e classes embutidas podem ser registradas como “subclasses virtuais” dos ABCs. Essas classes devem definir a API completa, incluindo todos os métodos abstratos e todos os métodos mixin. Isso permite que os usuários confiem nos testes `issubclass()` ou `isinstance()` para determinar se a interface completa é suportada. A exceção a essa regra é para métodos que são automaticamente inferidos do restante da API:

       class D:                                 # Sem herança
           def __init__(self): ...              # Método extra exigido pela ABC
           def __getitem__(self, index):  ...   # Método abstrato
           def __len__(self):  ...              # Método abstrato
           def count(self, value): ...          # Método mixin
           def index(self, value): ...          # Método mixin

       Sequence.register(D)                     # Registra ao invés de herdar

       >>> issubclass(D, Sequence)
       True
       >>> isinstance(D(), Sequence)
       True

   Neste exemplo, a classe `D` não precisa definir `__contains__`, `__iter__` e `__reversed__` porque o operador in, a lógica iteration e a função `reversed()` retornam automaticamente para o uso de `__getitem__` e `__len__`.

3. Algumas interfaces simples são diretamente reconhecíveis pela presença dos métodos necessários (a menos que esses métodos tenham sido definidos como `None`):

       class E:
           def __iter__(self): ...
           def __next__(self): ...

       >>> issubclass(E, Iterable)
       True
       >>> isinstance(E(), Iterable)
       True

   Interfaces complexas não oferecem suporte a esta última técnica porque uma interface é mais do que apenas a presença de nomes de métodos. Interfaces especificam semântica e relacionamentos entre métodos que não podem ser inferidos somente da presença de nomes de métodos específicos. Por exemplo, saber que uma classe fornece `__getitem__`, `__len__` e `__iter__` é insuficiente para distinguir uma `Sequence` de uma `Mapping`.

Adicionado na versão 3.9: Essas classes abstratas agora oferecem suporte a `[]`. Veja Tipo Generic Alias e PEP 585.

## 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` [1] |  | `__contains__` |
`Hashable` [1] |  | `__hash__` |
`Iterable` [1] [2] |  | `__iter__` |
`Iterator` [1] | `Iterable` | `__next__` | `__iter__`
`Reversible` [1] | `Iterable` | `__reversed__` |
`Generator` [1] | `Iterator` | `send`, `throw` | `close`, `__iter__`, `__next__`
`Sized` [1] |  | `__len__` |
`Callable` [1] |  | `__call__` |
`Collection` [1] | `Sized`, `Iterable`, `Container` | `__contains__`, `__iter__`, `__len__` |
`Sequence` | `Reversible`, `Collection` | `__getitem__`, `__len__` | `__contains__`, `__iter__`, `__reversed__`, `index`, and `count`
`MutableSequence` | `Sequence` | `__getitem__`, `__setitem__`, `__delitem__`, `__len__`, `insert` | Herdados métodos de `Sequence` e `append`, `clear`, `reverse`, `extend`, `pop`, `remove` e `__iadd__`
`ByteString` | `Sequence` | `__getitem__`, `__len__` | Métodos herdados de `Sequence`
`Set` | `Collection` | `__contains__`, `__iter__`, `__len__` | `__le__`, `__lt__`, `__eq__`, `__ne__`, `__gt__`, `__ge__`, `__and__`, `__or__`, `__sub__`, `__rsub__`, `__xor__`, `__rxor__` e `isdisjoint`
`MutableSet` | `Set` | `__contains__`, `__iter__`, `__len__`, `add`, `discard` | Herdado `Set` métodos e `clear`, `pop`, `remove`, `__ior__`, `__iand__`, `__ixor__`, e `__isub__`
`Mapping` | `Collection` | `__getitem__`, `__iter__`, `__len__` | `__contains__`, `keys`, `items`, `values`, `get`, `__eq__`, e `__ne__`
`MutableMapping` | `Mapping` | `__getitem__`, `__setitem__`, `__delitem__`, `__iter__`, `__len__` | Herdado `Mapping` métodos e `pop`, `popitem`, `clear`, `update`, e `setdefault`
`MappingView` | `Sized` |  | `__init__`, `__len__` e `__repr__`
`ItemsView` | `MappingView`, `Set` |  | `__contains__`, `__iter__`
`KeysView` | `MappingView`, `Set` |  | `__contains__`, `__iter__`
`ValuesView` | `MappingView`, `Collection` |  | `__contains__`, `__iter__`
`Awaitable` [1] |  | `__await__` |
`Coroutine` [1] | `Awaitable` | `send`, `throw` | `close`
`AsyncIterable` [1] |  | `__aiter__` |
`AsyncIterator` [1] | `AsyncIterable` | `__anext__` | `__aiter__`
`AsyncGenerator` [1] | `AsyncIterator` | `asend`, `athrow` | `aclose`, `__aiter__`, `__anext__`
`Buffer` [1] |  | `__buffer__` |

Notas de rodapé

[1] (1,2,3,4,5,6,7,8,9,10,11,12,13,14,15)

Essas ABCs substituem `__subclasshook__()` para dar suporte ao teste de uma interface verificando se os métodos necessários estão presentes e não foram definidos como `None`. Isso só funciona para interfaces simples. Interfaces mais complexas exigem registro ou subclassificação direta.

[2]

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

## Classes Base Abstrata de Coleções – Descrições Detalhadas

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__()`.

  Veja Anotações de objetos chamáveis para detalhes sobre como usar `Callable` em anotações de tipos.

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.

  Adicionado 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__()`.

  Adicionado 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()`.

  Consulte Anotando geradores e corrotinas para obter detalhes sobre como usar `Generator` em anotações de tipos.

  Adicionado 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 métodos mixin, como `__iter__()`, `__reversed__()` e `index()`, fazem chamadas repetidas ao 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ão ser substituídos.

  index(value, start=0, stop=None)

    Retorna o primeiro índice de valor.

    Levanta `ValueError` se o valor não estiver presente.

    Suporte aos argumentos start e stop é opcional, mas recomendado.

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

  Deprecated since version 3.12, will be removed in version 3.17: A ABC `ByteString` foi descontinuada.

  Use `isinstance(obj, collections.abc.Buffer)` para testar se `obj` implementa o protocolo de buffer em tempo de execução. Para uso em anotações de tipo, use `Buffer` ou uma união que especifique explicitamente os tipos suportados pelo seu código (por exemplo, `bytes | bytearray | memoryview`).

  `ByteString` foi originalmente concebido para ser uma classe abstrata que serviria como um supertipo de `bytes` e `bytearray`. No entanto, como o ABC nunca teve métodos, saber que um objeto era uma instância de `ByteString` nunca lhe dizia nada de útil sobre o objeto. Outros tipos comuns de buffer, como `memoryview`, também nunca foram entendidos como subtipos de `ByteString` (seja em tempo de execução ou por verificadores de tipo estáticos).

  Consulte PEP para mais detalhes.

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

  ABCs para conjuntos somente leitura e mutáveis.

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

  In CPython, generator-based coroutines (generators decorated with `@types.coroutine`) are awaitables, even though they do not have an `__await__()` method. Using `isinstance(gencoro, Awaitable)` for them will return `False`. Use `inspect.isawaitable()` to detect them.

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

  Nota

  In CPython, generator-based coroutines (generators decorated with `@types.coroutine`) are awaitables, even though they do not have an `__await__()` method. Using `isinstance(gencoro, Coroutine)` for them will return `False`. Use `inspect.isawaitable()` to detect them.

  Consulte Anotando geradores e corrotinas para obter detalhes sobre como usar `Coroutine` em anotações de tipos. A variância e a ordem dos parâmetros de tipo correspondem às de `Generator`.

  Adicionado na versão 3.5.

class collections.abc.AsyncIterable

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

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

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

  Consulte Anotando geradores e corrotinas para obter detalhes sobre como usar `AsyncGenerator` em anotações de tipos.

  Adicionado na versão 3.6.

class collections.abc.Buffer

  ABC para classes que fornecem o método `__buffer__()`, implementando o protocolo buffer. Veja PEP 688.

  Adicionado na versão 3.12.

## Exemplos e receitas

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            # O método __and__() é automaticamente suportado

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 um iterável. Supõe-se que a classe construtor tenha uma assinatura no formato `ClassName(iterable)`. Essa suposição é fatorada em um `classmethod` 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 ou um método regular 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 é definido porque nem todos os conjuntos são hasheáveis ou imutáveis. Para adicionar hasheabilidade 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.