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.

An issubclass() or isinstance() test for an interface works in one of three ways.

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

In this example, class D does not need to define __contains__, __iter__, and __reversed__ because the in-operator, the iteration logic, and the reversed() function automatically fall back to using __getitem__ and __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

Complex interfaces do not support this last technique because an interface is more than just the presence of method names. Interfaces specify semantics and relationships between methods that cannot be inferred solely from the presence of specific method names. For example, knowing that a class supplies __getitem__, __len__, and __iter__ is insufficient for distinguishing a Sequence from a Mapping.

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

Footnotes

1(1,2,3,4,5,6,7,8,9,10,11,12,13,14)

These ABCs override object.__subclasshook__() to support testing an interface by verifying the required methods are present and have not been set to None. This only works for simple interfaces. More complex interfaces require registration or direct subclassing.

2

Checking isinstance(obj, Iterable) detects classes that are registered as Iterable or that have an __iter__() method, but it does not detect classes that iterate with the __getitem__() method. The only reliable way to determine whether an object is iterable is to call iter(obj).

Collections Abstract Base Classes – Detailed Descriptions

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.

Examples and Recipes

ABCs allow us to ask classes or instances if they provide particular functionality, for example:

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