8.4. collections.abc — Classes Base Abstratas para Contêineres

Novo na versão 3.3: Formerly, this module was part of the collections module. Anteriormente, esse módulo fazia parte do módelu 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.

8.4.1. Coleções Abstratas Classes Base

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, Container	__contains__, __iter__, __len__
Sequence	Reversible, Collection	__getitem__, __len__	__contains__, __iter__, __reversed__, index, and count
MutableSequence	Sequence	__getitem__, __setitem__, __delitem__, __len__, insert	Herda os métodos da Sequence e append, reverse, extend, pop, remove, e __iadd__
ByteString	Sequence	__getitem__, __len__	Herdado Sequence métodos
Set	Collection	__contains__, __iter__, __len__	__le__, __lt__, __eq__, __ne__, __gt__, __ge__, __and__, __or__, __sub__, __xor__, 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		__len__
ItemsView	MappingView, Set		__contains__, __iter__
KeysView	MappingView, Set		__contains__, __iter__
ValuesView	MappingView		__contains__, __iter__
Awaitable		__await__
Coroutine	Awaitable	send, throw	close
AsyncIterable		__aiter__
AsyncIterator	AsyncIterable	__anext__	__aiter__
AsyncGenerator	AsyncIterator	asend, athrow	aclose, __aiter__, __anext__

class collections.abc.Container

class collections.abc.Hashable

class collections.abc.Sized

class collections.abc.Callable

ABCs para classes que fornecem respectivamente os métodos __contains__(), __hash__(), __len__(), e __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 é iterable é chamar iter(obj).

class collections.abc.Collection

ABC para classes de contêineres iteráveis 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 generator.

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ável :term:` <sequence>`.

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ão ser substituídos.

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 awaitable, que podem ser usados em expressões de await. Implementações personalizadas devem fornecer o método __await__() method.

Coroutine objetos e instâncias do Coroutine ABC são todas instâncias dessa ABC.

Nota

No CPython, as corotinas 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 coroutine. Eles implementam os seguintes métodos, definidos em Objetos Coroutine: 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 coroutine.

Nota

Em CPython, as corotinas 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 asynchronous iterable.

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

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