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

## 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 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 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 objects and instances of the `Coroutine` ABC are all instances of this 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 Coroutine Objects: `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 desde un iterable. Se supone que el constructor de la clase tiene una firma en el formato `ClassName (iterable)`. Esa suposición se tiene en cuenta para una clase interna llamada `_from_iterable()` que llama a `cls(iterable)` para producir un nuevo conjunto. Si el mixin `Set` se está utilizando en una clase con una firma de constructor diferente, deberá reemplazar `_from_iterable()` con un método de clase 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.