collections.abc — Clases Base Abstractas para Contenedores

Nuevo en la versión 3.3: Anteriormente, este módulo formaba parte del módulo collections.

Código fuente: Lib/_collections_abc.py

Este módulo proporciona clases base abstractas que pueden usarse para probar si una clase proporciona una interfaz específica; por ejemplo, si es hashable o si es un mapeo.

Nuevo en la versión 3.9: These abstract classes now support []. See Tipo Alias Genérico and PEP 585.

Colecciones Clases Base Abstractas

El módulo de colecciones ofrece lo siguiente ABCs:

ABC

Hereda de

Métodos Abstractos

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

Métodos heredados Sequence y append, reverse, extend, pop, remove, and __iadd__

ByteString

Sequence

__getitem__, __len__

Métodos heredados Sequence

Set

Collection

__contains__, __iter__, __len__

__le__, __lt__, __eq__, __ne__, __gt__, __ge__, __and__, __or__, __sub__, __xor__, and isdisjoint

MutableSet

Set

__contains__, __iter__, __len__, add, discard

Métodos heredados Set y clear, pop, remove, __ior__, __iand__, __ixor__, and __isub__

Mapping

Collection

__getitem__, __iter__, __len__

__contains__, keys, items, values, get, __eq__, and __ne__

MutableMapping

Mapping

__getitem__, __setitem__, __delitem__, __iter__, __len__

Métodos heredados Mapping y pop, popitem, clear, update, and 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 para clases que proporcionan el método __contains__().

class collections.abc.Hashable

ABC para clases que proporcionan el método __hash__().

class collections.abc.Sized

ABC para clases que proporcionan el método __len__().

class collections.abc.Callable

ABC para clases que proporcionan el método __call__().

class collections.abc.Iterable

ABC para clases que proporcionan el método __iter__().

Al marcar isinstance(obj, Iterable) se detectan las clases que están registradas como Iterable o que tienen un método __iter__(), pero no detecta clases que iteran con el método __getitem__(). La única forma confiable de determinar si un objeto es iterable es llamar a iter(obj).

class collections.abc.Collection

ABC para clases de contenedor iterables de tamaño.

Nuevo en la versión 3.6.

class collections.abc.Iterator

ABC para clases que proporcionan el método __iter__() y __next__(). Ver también la definición de iterator.

class collections.abc.Reversible

ABC para clases iterables que también proporcionan __reversed__() method.

Nuevo en la versión 3.6.

class collections.abc.Generator

ABC para clases generadoras que implementan el protocolo definido en PEP 342 que extiende los iteradores con los métodos send(), throw() and close(). Ver también la definición de generator.

Nuevo en la versión 3.5.

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

ABC para solo lectura y mutable secuencias.

Nota de implementación: algunos de los métodos mixin, tales como __iter__(), __reversed__() and index(), hacen llamadas repetidas al subyacente __getitem__() method. En consecuencia, si __getitem__() se implementa con velocidad de acceso constante, los métodos mixin tendrán un rendimiento lineal; sin embargo, si el método subyacente es lineal (como lo sería con una lista vinculada), los mixins tendrán un rendimiento cuadrático y probablemente deberán ser anulados.

Distinto en la versión 3.5: El método index() agregó soporte para los argumentos stop y start.

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

ABC para conjuntos de solo lectura y mutables.

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

ABC para solo lectura y mutable mapeos.

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

ABC para mapeo, elementos, claves y valores vistas.

class collections.abc.Awaitable

ABC para objetos awaitable, que pueden ser usados en expresiones await. Las implementaciones personalizadas deben proporcionar el método __await__().

Coroutine objetos e instancias de la clase Coroutine ABC son todas las instancias de este ABC.

Nota

En CPython, las corrutinas basadas en generador (generadores decorados con types.coroutine() o asyncio.coroutine()) son awaitables, a pesar de que no tienen un método __await__(). El uso de isinstance(gencoro, Awaitable) para ellos retornará False. Use inspect.isawaitable() para detectarlos.

Nuevo en la versión 3.5.

class collections.abc.Coroutine

ABC para clases corrutinas compatibles. Estos implementan los siguientes métodos, definidos en Objetos de Corrutina: send(), throw(), and close(). Las implementaciones personalizadas también deben implementar __await__(). Todas las instancias de Coroutine también son instancias de Awaitable. Ver también la definición de coroutine.

Nota

En CPython, las corrutinas basadas en generador (generadores decorados con types.coroutine() o asyncio.coroutine()) son awaitables, a pesar de que no tienen un método __await__(). El uso de isinstance(gencoro, Coroutine) para ellos retornará False. Use inspect.isawaitable() para detectarlos.

Nuevo en la versión 3.5.

class collections.abc.AsyncIterable

ABC para las clases que proporcionan el método __aiter__. Ver también la definición de asynchronous iterable.

Nuevo en la versión 3.5.

class collections.abc.AsyncIterator

ABC para clases que proveen métodos __aiter__ and __anext__. Ver también la definición de asynchronous iterator.

Nuevo en la versión 3.5.

class collections.abc.AsyncGenerator

ABC para clases generadoras asincrónicas que implementan el protocolo definido en PEP 525 y PEP 492.

Nuevo en la versión 3.6.

Estos ABC nos permiten preguntar a clases o instancias si proporcionan una funcionalidad particular, por ejemplo:

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

Varios ABCs también son útiles como mixins que facilitan el desarrollo de clases que admiten APIs de contenedor. Por ejemplo, para escribir una clase que admita toda la API Set, solo es necesario proporcionar los tres métodos abstractos subyacentes: __contains__(), __iter__(), y __len__(). El ABC proporciona los métodos restantes, como __and__() y 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 el uso de Set y MutableSet como un mixin:

  1. Dado que algunas operaciones de conjuntos crean nuevos conjuntos, los métodos mixin predeterminados necesitan una forma de crear nuevas instancias a partir de un iterable. Se supone que el constructor de la clase tiene una firma con el formato ClassName(iterable). Esa suposición se factoriza en un método de clase interno llamado _from_iterable() que llama a cls(iterable) para producir un nuevo conjunto. Si el mixin Set se está usando en una clase con una firma de constructor diferente, necesitarás anular _from_iterable() con un método de clase o método regular que pueda construir nuevas instancias a partir de un argumento iterable.

  2. Para reemplazar las comparaciones (presumiblemente para la velocidad, ya que las semánticas son fijas), redefinir __le__() y __ge__(), luego las otras operaciones seguirán automáticamente su ejemplo.

  3. El mixin Set proporciona un método _hash() para calcular un valor hash para el conjunto; sin embargo, __hash__() no está definido porque no todos los conjuntos son encadenados o inmutables. Para agregar capacidad de encadenamiento en conjuntos que usan mixin, herede de ambos Set() y Hashable(), luego defina __hash__ = Set._hash.

Ver también