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__
Generator Iterator send, throw close, __iter__, __next__
Sized   __len__  
Callable   __call__  
Sequence Sized, Iterable, Container __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 Sized, Iterable, Container __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 Sized, Iterable, Container __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__
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 for classes that provide the __iter__() method. See also the definition of iterable.

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

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