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, Container

__contains__, __iter__, __len__

Sequence

Reversible, Collection

__getitem__, __len__

__contains__, __iter__, __reversed__, index, and count

MutableSequence

Sequence

__getitem__, __setitem__, __delitem__, __len__, insert

Herdado 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, Collection

__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

ABC for classes that provide the __contains__() method.

class collections.abc.Hashable

ABC for classes that provide the __hash__() method.

class collections.abc.Sized

ABC for classes that provide the __len__() method.

class collections.abc.Callable

ABC for classes that provide the __call__() method.

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

Coroutine objects and instances of the Coroutine ABC are all instances of this 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