"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",   | "__contains__",         |                                                      |
|                            | "Container"            | "__iter__", "__len__"   |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Sequence"                 | "Reversible",          | "__getitem__",          | "__contains__", "__iter__", "__reversed__", "index", |
|                            | "Collection"           | "__len__"               | and "count"                                          |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableSequence"          | "Sequence"             | "__getitem__",          | Métodos heredados "Sequence" y "append", "reverse",  |
|                            |                        | "__setitem__",          | "extend", "pop", "remove", and "__iadd__"            |
|                            |                        | "__delitem__",          |                                                      |
|                            |                        | "__len__", "insert"     |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ByteString"               | "Sequence"             | "__getitem__",          | Métodos heredados "Sequence"                         |
|                            |                        | "__len__"               |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Set"                      | "Collection"           | "__contains__",         | "__le__", "__lt__", "__eq__", "__ne__", "__gt__",    |
|                            |                        | "__iter__", "__len__"   | "__ge__", "__and__", "__or__", "__sub__", "__xor__", |
|                            |                        |                         | and "isdisjoint"                                     |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableSet"               | "Set"                  | "__contains__",         | Métodos heredados "Set" y "clear", "pop", "remove",  |
|                            |                        | "__iter__", "__len__",  | "__ior__", "__iand__", "__ixor__", and "__isub__"    |
|                            |                        | "add", "discard"        |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Mapping"                  | "Collection"           | "__getitem__",          | "__contains__", "keys", "items", "values", "get",    |
|                            |                        | "__iter__", "__len__"   | "__eq__", and "__ne__"                               |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableMapping"           | "Mapping"              | "__getitem__",          | Métodos heredados "Mapping" y "pop", "popitem",      |
|                            |                        | "__setitem__",          | "clear", "update", and "setdefault"                  |
|                            |                        | "__delitem__",          |                                                      |
|                            |                        | "__iter__", "__len__"   |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MappingView"              | "Sized"                |                         | "__len__"                                            |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ItemsView"                | "MappingView", "Set"   |                         | "__contains__", "__iter__"                           |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "KeysView"                 | "MappingView", "Set"   |                         | "__contains__", "__iter__"                           |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ValuesView"               | "MappingView",         |                         | "__contains__", "__iter__"                           |
|                            | "Collection"           |                         |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "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**.
