Nota

¡Ayúdanos a traducir la documentación oficial de Python al Español! Puedes encontrar más información en Como contribuir. Ayuda a acercar Python a más personas de habla hispana.

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.

Una prueba issubclass() o isinstance() para una interfaz funciona de tres formas.

1) A newly written class can inherit directly from one of the abstract base classes. The class must supply the required abstract methods. The remaining mixin methods come from inheritance and can be overridden if desired. Other methods may be added as needed:

class C(Sequence):                      # Direct inheritance
    def __init__(self): ...             # Extra method not required by the ABC
    def __getitem__(self, index):  ...  # Required abstract method
    def __len__(self):  ...             # Required abstract method
    def count(self, value): ...         # Optionally override a mixin method

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

2) Existing classes and built-in classes can be registered as «virtual subclasses» of the ABCs. Those classes should define the full API including all of the abstract methods and all of the mixin methods. This lets users rely on issubclass() or isinstance() tests to determine whether the full interface is supported. The exception to this rule is for methods that are automatically inferred from the rest of the API:

class D:                                 # No inheritance
    def __init__(self): ...              # Extra method not required by the ABC
    def __getitem__(self, index):  ...   # Abstract method
    def __len__(self):  ...              # Abstract method
    def count(self, value): ...          # Mixin method
    def index(self, value): ...          # Mixin method

Sequence.register(D)                     # Register instead of inherit

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

En este ejemplo, la clase D no necesita definir __contains__, __iter__ y __reversed__ porque el operador in, la lógica de iteración y la función reversed() recurren automáticamente al uso de __getitem__ y __len__.

3) Some simple interfaces are directly recognizable by the presence of the required methods (unless those methods have been set to None):

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

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

Las interfaces complejas no admiten esta última técnica porque una interfaz es más que la simple presencia de nombres de métodos. Las interfaces especifican la semántica y las relaciones entre métodos que no se pueden inferir únicamente de la presencia de nombres de métodos específicos. Por ejemplo, saber que una clase proporciona __getitem__, __len__ y __iter__ no es suficiente para distinguir un Sequence de un Mapping.

Nuevo en la versión 3.9: Estas clases abstractas ahora soportan []. Vea Tipo Alias Genérico y 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 [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

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 [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 al pie

Colecciones Clases base abstractas - Descripciones detalladas

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.

Obsoleto desde la versión 3.12, se eliminará en la versión 3.14: La ABC ByteString está obsoleta. Para usar con type hints, mejor use una unión del tipo bytes | bytearray, o collections.abc.Buffer. Para usar como una ABC, mejor use Sequence o collections.abc.Buffer.

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()) son awaitables, a pesar de que no tienen un método __await__(). El uso de isinstance(gencoro, Awaitable) para ellas retornará False. Use inspect.isawaitable() para detectarlas.

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()) son awaitables, a pesar de que no tienen un método __await__(). El uso de isinstance(gencoro, Coroutine) para ellas retornará False. Use inspect.isawaitable() para detectarlas.

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.

class collections.abc.Buffer

ABC para clases que proveen el método __buffer__(), implementando el protocolo búfer. Ver PEP 688.

Nuevo en la versión 3.12.

Ejemplos y Recetas

Los ABC nos permiten preguntar a las clases o instancias si brindan 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 hashable o inmutables. Para agregar la capacidad de encadenamiento en conjuntos usando métodos mixin, herede de ambos Set() y Hashable(), luego defina __hash__ = Set._hash.

Ver también