"collections.abc" --- Classes de base abstraites pour les conteneurs
********************************************************************

Nouveau dans la version 3.3: Auparavant, ce module faisait partie du
module "collections".

**Code source :** Lib/_collections_abc.py

======================================================================

Ce module fournit *des classes de base abstraites* qui peuvent être
utilisées pour vérifier si une classe fournit une interface
particulière (par exemple, savoir s'il s'agit d'un hachable ou d'une
table de correspondance).


Classes de base abstraites de collections
=========================================

Le module collections apporte les *ABC* suivantes :

+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| ABC                        | Hérite de              | Méthodes abstraites     | Méthodes *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__"               | et "count"                                           |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableSequence"          | "Sequence"             | "__getitem__",          | Méthodes héritées de "Sequence", et "append",        |
|                            |                        | "__setitem__",          | "reverse", "extend", "pop", "remove" et "__iadd__"   |
|                            |                        | "__delitem__",          |                                                      |
|                            |                        | "__len__", "insert"     |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "ByteString"               | "Sequence"             | "__getitem__",          | Méthodes héritées de "Sequence"                      |
|                            |                        | "__len__"               |                                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Set"                      | "Collection"           | "__contains__",         | "__le__", "__lt__", "__eq__", "__ne__", "__gt__",    |
|                            |                        | "__iter__", "__len__"   | "__ge__", "__and__", "__or__", "__sub__", "__xor__"  |
|                            |                        |                         | et "isdisjoint"                                      |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableSet"               | "Set"                  | "__contains__",         | Méthodes héritées de "Set", et "clear", "pop",       |
|                            |                        | "__iter__", "__len__",  | "remove", "__ior__", "__iand__", "__ixor__" et       |
|                            |                        | "add", "discard"        | "__isub__"                                           |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Mapping"                  | "Collection"           | "__getitem__",          | "__contains__", "keys", "items", "values", "get",    |
|                            |                        | "__iter__", "__len__"   | "__eq__" et "__ne__"                                 |
+----------------------------+------------------------+-------------------------+------------------------------------------------------+
| "MutableMapping"           | "Mapping"              | "__getitem__",          | Méthodes héritées de "Mapping", et "pop", "popitem", |
|                            |                        | "__setitem__",          | "clear", "update" et "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 pour les classes qui définissent la méthode "__contains__()".

class collections.abc.Hashable

   ABC pour les classes qui définissent la méthode "__hash__()".

class collections.abc.Sized

   ABC pour les classes qui définissent la méthode "__len__()".

class collections.abc.Callable

   ABC pour les classes qui définissent la méthode "__call__()".

class collections.abc.Iterable

   ABC pour les classes qui définissent la méthode "__iter__()".

   Évaluer "isinstance(obj, Iterable)" détecte les classes qui sont
   enregistrées comme "Iterable" ou qui possèdent une méthode
   "__iter__()", mais ne détecte pas les classes qui itèrent avec la
   méthode "__getitem__()". Le seul moyen fiable de déterminer si un
   objet est *itérable* est d'appeler "iter(obj)".

class collections.abc.Collection

   ABC pour les classes de conteneurs itérables et *sized*.

   Nouveau dans la version 3.6.

class collections.abc.Iterator

   ABC pour les classes qui définissent les méthodes "__iter__()" et
   "__next__()". Voir aussi la définition d'*itérateur*.

class collections.abc.Reversible

   ABC pour les classes d'itérables qui implémentent également la
   méthode "__reversed__()".

   Nouveau dans la version 3.6.

class collections.abc.Generator

   ABC pour les classes de générateurs qui implémentent le protocole
   défini dans la **PEP 342** qui étend les itérateurs avec les
   méthodes "send()", "throw()" et "close()". Voir aussi la définition
   de *générateur*.

   Nouveau dans la version 3.5.

class collections.abc.Sequence
class collections.abc.MutableSequence
class collections.abc.ByteString

   ABC pour les *séquences* immuables et muables.

   Note pour l'implémentation : quelques méthodes *mixin*, comme
   "__iter__()", "__reversed__()" et "index()", font des appels
   répétés à la méthode sous-jacente "__getitem__()". Ainsi, si
   "__getitem__()" est implémentée avec une vitesse d'accès constante,
   les méthodes *mixin* auront une performance linéaire ; cependant,
   si elle est linéaire, les *mixin* auront une performance
   quadratique, il serait alors judicieux de les surcharger.

   Modifié dans la version 3.5: La méthode index() a ajouté le support
   des arguments *start* et *stop*.

class collections.abc.Set
class collections.abc.MutableSet

   ABC pour les ensembles immuables et muables.

class collections.abc.Mapping
class collections.abc.MutableMapping

   ABC pour les *tables de correspondances* immuables et muables.

class collections.abc.MappingView
class collections.abc.ItemsView
class collections.abc.KeysView
class collections.abc.ValuesView

   ABC pour les *vues* de *mappings* (tableaux de correspondances),
   d'éléments, de clés et de valeurs.

class collections.abc.Awaitable

   ABC pour les objets *awaitables*, qui peuvent être utilisés dans
   les expressions "await". Les implémentations personnalisées doivent
   définir la méthode "__await__()".

   Les objets *coroutines* et les instances de l'ABC "Coroutine" sont
   tous des instances de cette ABC.

   Note:

     En CPython, les coroutines basées sur les générateurs (les
     générateurs décorés avec "types.coroutine()" ou
     "asyncio.coroutine()") sont *awaitables*, bien qu'elles n'aient
     pas de méthode "__await__()". Évaluer "isinstance(gencoro,
     Awaitable)" où "gencoro" est un générateur décoré va renvoyer
     "False". Utilisez "inspect.isawaitable()" pour les détecter.

   Nouveau dans la version 3.5.

class collections.abc.Coroutine

   ABC pour les classes compatibles avec les coroutines. Elles
   implémentent les méthodes suivantes, définies dans Objets
   coroutines : "send()", "throw()" et "close()". Les implémentations
   personnalisées doivent également fournir "__await__()". Toutes les
   instances de "Coroutine" sont également des instances de
   "Awaitable". Voir aussi la définition de *coroutine*.

   Note:

     En CPython, les coroutines basées sur les générateurs (les
     générateurs décorés avec "types.coroutine()" ou
     "asyncio.coroutine()") sont *awaitables*, bien qu'elles n'aient
     pas de méthode "__await__()". Évaluer "isinstance(gencoro,
     Corourine)" où "gencoro" est un générateur décoré va renvoyer
     "False". Utilisez "inspect.isawaitable()" pour les détecter.

   Nouveau dans la version 3.5.

class collections.abc.AsyncIterable

   ABC pour les classes qui définissent la méthode "__aiter__". Voir
   aussi la définition d'*itérable asynchrone*.

   Nouveau dans la version 3.5.

class collections.abc.AsyncIterator

   ABC pour les classes qui définissent les méthodes "__aiter__" et
   "__anext__". Voir aussi la définition d'*itérateur asynchrone*.

   Nouveau dans la version 3.5.

class collections.abc.AsyncGenerator

   ABC pour les classes de générateurs asynchrones qui implémentent le
   protocole défini dans la **PEP 525** et dans la **PEP 492**.

   Nouveau dans la version 3.6.

Ces ABC permettent de demander à des classes ou à des instances si
elles fournissent des fonctionnalités particulières, par exemple :

   size = None
   if isinstance(myvar, collections.abc.Sized):
       size = len(myvar)

Une partie des ABC sont également utiles en tant que *mixins* : cela
rend plus facile le développement de classes qui gèrent des API de
conteneurs. Par exemple, pour écrire une classe qui gère l'API entière
de "Set", il est uniquement nécessaire de fournir les trois méthodes
sous-jacentes abstraites "__contains__()", "__iter__()" et
"__len__()". L'ABC apporte les méthodes restantes, comme "__and__()"
et "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

Notes à propos de l'utilisation de "Set" et "MutableSet" comme *mixin*
:

1. Comme une partie des opérations sur les ensembles créent de
   nouveaux ensembles, les méthodes *mixins* par défaut ont besoin
   d'un moyen de créer de nouvelles instances à partir d'un itérable.
   Le constructeur de classe est supposé avoir une signature de la
   forme "ClassName(iterable)". Cette supposition est faite par une
   méthode de classe interne appelée "_from_iterable()" qui appelle
   "cls(iterable)" pour construire un nouvel ensemble. Si le "Set"
   *mixin* est utilisé dans une classe avec un constructeur de
   signature différente, vous devez surcharger "_from_iterable()" avec
   une méthode de classe ou une méthode ordinaire qui peut construire
   de nouvelles instances à partir d'un argument itérable.

2. Pour surcharger les comparaisons (a priori pour la rapidité,
   puisque la sémantique est fixe), il faut redéfinir "__le__()" et
   "__ge__()", puis les autres opérations seront automatiquement
   adaptées.

3. La classe *mixin* "Set" apporte une méthode "_hash()" pour calculer
   une valeur de hachage pour l'ensemble ; cependant "__hash__()"
   n'est pas défini car tous les ensembles ne sont pas hachables ou
   immuables. Pour rendre un ensemble hachable en utilisant les
   *mixins*, héritez de "Set()" et de "Hashable()", puis définissez
   "__hash__ = Set._hash".

Voir aussi:

  * OrderedSet recipe pour un exemple construit sur "MutableSet".

  * Pour plus d'informations à propos des ABC, voir le module "abc" et
    la **PEP 3119**.
