This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# `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

- OrderedSet receta para un ejemplo basado en `MutableSet`.

- Para obtener más información sobre ABCs, ver el módulo `abc` y PEP 3119.