"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

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

This module provides *abstract base classes* that can be used to test
whether a class provides a particular interface; for example, whether
it is *hashable* or whether it is a mapping.

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".

Nouveau dans la version 3.9: These abstract classes now support "[]".
See Generic Alias Type and **PEP 585**.


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

Le module collections apporte les *ABC* suivantes :

+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| ABC                            | Hérite de              | Méthodes abstraites     | Méthodes *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",   | "__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" [1]                |                        | "__await__"             |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "Coroutine" [1]                | "Awaitable"            | "send", "throw"         | "close"                                              |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "AsyncIterable" [1]            |                        | "__aiter__"             |                                                      |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "AsyncIterator" [1]            | "AsyncIterable"        | "__anext__"             | "__aiter__"                                          |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+
| "AsyncGenerator" [1]           | "AsyncIterator"        | "asend", "athrow"       | "aclose", "__aiter__", "__anext__"                   |
+--------------------------------+------------------------+-------------------------+------------------------------------------------------+

-[ Notes ]-

[1] 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 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.


Exemples et recettes
====================

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)

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. The "Set" mixin provides a "_hash()" method to compute a hash value
   for the set; however, "__hash__()" is not defined because not all
   sets are *hashable* or immutable.  To add set hashability using
   mixins, inherit from both "Set()" and "Hashable()", then define
   "__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**.
