"abc" — Classes de Base Abstraites
**********************************

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

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

Le module fournit l'infrastructure pour définir les *classes de bases
abstraites* (*Abstract Base Class* ou *ABC* en anglais) en Python, tel
qu'indiqué dans la **PEP 3119**; voir la PEP pour la raison de son
ajout à Python. (Voir également la **PEP 3141** et le module "numbers"
pour ce qui concerne la hiérarchie de types pour les nombres basés sur
les classes de base abstraites). Par la suite nous utiliserons
l'abréviation ABC (*Abstract Base Class*) pour désigner une classe de
base abstraite.

Le module "collections" possède certaines classes concrètes qui
dérivent d'ABC. Celles-ci peuvent, bien sur, être elles-mêmes
dérivées. De plus, le sous-module "collections.abc" possède des ABC
qui peuvent être utilisées pour tester si une classe ou une instance
fournit une interface spécifique. Par exemple, est-elle hachable ou un
tableau associatif (*mapping* en anglais) ?

Ce module fournit la métaclasse "ABCMeta" pour définir les ABC ainsi
que la classe d'aide "ABC", cette dernière permettant de définir des
ABC en utilisant l'héritage :

class abc.ABC

   Classe d'aide qui a "ABCMeta" pour métaclasse. Avec cette classe,
   une ABC peut être créée simplement en héritant de "ABC" , ce qui
   permet d'éviter l'utilisation parfois déroutante de métaclasse, par
   exemple :

      from abc import ABC

      class MyABC(ABC):
          pass

   Il est à noter que le type de "ABC" reste "ABCMeta". En
   conséquence, hériter de "ABC" nécessite les précautions habituelles
   concernant l'utilisation de métaclasses : l'utilisation d'héritage
   multiple peut entrainer des conflits de métaclasses. Il est
   également possible de définir une ABC en passant l'argument nommé
   *metaclass* et en utilisant "ABCMeta" directement, par exemple :

      from abc import ABCMeta

      class MyABC(metaclass=ABCMeta):
          pass

   Nouveau dans la version 3.4.

class abc.ABCMeta

   Métaclasse pour définir des classes de base abstraites (ABC).

   Utilisez cette métaclasse pour créer une ABC. Il est possible
   d'hériter d'une ABC directement, cette classe de base abstraite
   fonctionne alors comme une classe *mixin*. Vous pouvez également
   enregistrer une classe concrète sans lien (même une classe native)
   et des ABC comme "sous-classes virtuelles" -- celles-ci et leur
   descendantes seront considérées comme des sous-classes de la classe
   de base abstraite par la fonction native "issubclass()", mais les
   ABC enregistrées n'apparaitront pas dans leur ordre de résolution
   des méthodes (*MRO* pour *Method Resolution Order* en anglais). Les
   implémentations de méthodes définies par l'ABC ne seront pas
   appelable (pas même via "super()"). [1]

   Les classes dont la métaclasse est "ABCMeta" possèdent les méthodes
   suivantes :

   register(subclass)

      Enregistrer *subclass* en tant que sous-classe virtuelle de
      cette ABC. Par exemple :

         from abc import ABC

         class MyABC(ABC):
             pass

         MyABC.register(tuple)

         assert issubclass(tuple, MyABC)
         assert isinstance((), MyABC)

      Modifié dans la version 3.3: Renvoie la sous-classe enregistrée
      pour permettre l'utilisation en tant que décorateur de classe.

      Modifié dans la version 3.4: Pour détecter les appels à
      "register()", vous pouvez utiliser la fonction
      "get_cache_token()".

   Vous pouvez également redéfinir cette méthode dans une ABC :

   __subclasshook__(subclass)

      (Doit être définie en tant que méthode de classe.)

      Vérifie si *subclass* est considérée comme une sous-classe de
      cette ABC. Cela signifie que vous pouvez personnaliser le
      comportement de "issubclass" sans nécessiter d'appeler
      "register()" pour chacune des classes que vous souhaitez
      considérer comme sous-classe de l'ABC. (Cette méthode de classe
      est appelée par la méthode "__subclasscheck__()" de la classe de
      base abstraite).

      Cette méthode doit renvoyer "True", "False" ou "NotImplemented".
      Si elle renvoie "True", *subclass* est considérée comme sous-
      classe de cette ABC. Si elle renvoie "False", la *subclass*
      n'est pas considérée une sous-classe de cette ABC même si elle
      l'aurait été en temps normal. Si elle renvoie "NotImplemented",
      la vérification d'appartenance à la sous-classe continue via le
      mécanisme habituel.

   Pour une illustration de ces concepts, voir cet exemple de
   définition de ABC :

      class Foo:
          def __getitem__(self, index):
              ...
          def __len__(self):
              ...
          def get_iterator(self):
              return iter(self)

      class MyIterable(ABC):

          @abstractmethod
          def __iter__(self):
              while False:
                  yield None

          def get_iterator(self):
              return self.__iter__()

          @classmethod
          def __subclasshook__(cls, C):
              if cls is MyIterable:
                  if any("__iter__" in B.__dict__ for B in C.__mro__):
                      return True
              return NotImplemented

      MyIterable.register(Foo)

   L'ABC "MyIterable" définit la méthode d'itération "__iter__()"
   comme méthode abstraite. L'implémentation qui lui est donnée ici
   peut être appelée depuis les sous-classes. La méthode
   "get_iterator()" fait également partie de la classe de base
   abstraite "MyIterable", mais elle n'a pas à être redéfinie dans les
   classes dérivées non-abstraites.

   La méthode de classe "__subclasshook__()" définie ici dit que toute
   classe qui possède la méthode "__iter__()" dans son "__dict__" (ou
   dans une de ses classes de base, accédée via la liste "__mro__")
   est considérée également comme un "MyIterable".

   Enfin, la dernière ligne fait de "Foo" une sous-classe virtuelle de
   "MyIterable", même si cette classe ne définit pas de méthode
   "__iter__()" (elle utilise l'ancien protocole d'itération qui se
   définit en termes de "__len__()" et "__getitem__()"). A noter que
   cela ne rendra pas le "get_iterator" de "MyIterable" disponible
   comme une méthode de "Foo", "get_iterator" est donc implémenté
   séparément.

Le module "abc" fournit aussi le décorateur :

@abc.abstractmethod

   Un décorateur marquant les méthodes comme abstraites.

   Utiliser ce décorateur nécessite que la métaclasse de la classe
   soit "ABCMeta" ou soit dérivée de celle-ci. Une classe qui possède
   une méta-classe dérivée de "ABCMeta" ne peut pas être instanciée à
   moins que toutes ses méthodes et propriétés abstraites soient
   redéfinies. Les méthodes abstraites peuvent être appelées en
   utilisant n'importe quel des mécanismes d'appel à 'super'.
   "abstractmethod()" peut être utilisée pour déclarer des méthodes
   abstraites pour les propriétés et descripteurs.

   Python ne gère pas l'ajout dynamique de méthodes abstraites à une
   classe, il n'est pas non plus possible de modifier l'état
   d'abstraction d'une méthode ou d'une classe une fois celle-ci
   créée. "abstractmethod()" n'affecte que les sous-classes dérivées
   utilisant l'héritage classique. Les "sous-classes virtuelles"
   enregistrées avec la méthode "register()" de l'ABC ne sont pas
   affectées.

   Quand le décorateur "abstractmethod()" est utilisé en même temps
   que d'autres descripteurs de méthodes, il doit être appliqué en
   tant que décorateur le plus interne. Voir les exemples
   d'utilisation suivants :

      class C(ABC):
          @abstractmethod
          def my_abstract_method(self, ...):
              ...
          @classmethod
          @abstractmethod
          def my_abstract_classmethod(cls, ...):
              ...
          @staticmethod
          @abstractmethod
          def my_abstract_staticmethod(...):
              ...

          @property
          @abstractmethod
          def my_abstract_property(self):
              ...
          @my_abstract_property.setter
          @abstractmethod
          def my_abstract_property(self, val):
              ...

          @abstractmethod
          def _get_x(self):
              ...
          @abstractmethod
          def _set_x(self, val):
              ...
          x = property(_get_x, _set_x)

   Afin d'interagir correctement avec le mécanisme de classe de base
   abstraite, un descripteur doit s'identifier comme abstrait en
   utilisant "__isabstractmethod__". En général, cet attribut doit
   être "True" si au moins une des méthodes faisant partie du
   descripteur est abstraite. Par exemple, la classe native "property"
   de python fait l'équivalent de :

      class Descriptor:
          ...
          @property
          def __isabstractmethod__(self):
              return any(getattr(f, '__isabstractmethod__', False) for
                         f in (self._fget, self._fset, self._fdel))

   Note:

     Contrairement aux méthodes abstraites Java, ces méthodes
     abstraites peuvent être implémentées. Cette implémentation peut
     être appelée via le mécanisme "super()" depuis la classe qui la
     redéfinit. C'est typiquement utile pour y appeler *super* et
     ainsi coopérer correctement dans un environnement utilisant de
     l'héritage multiple.

Le module "abc" gère également les décorateurs historiques suivants :

@abc.abstractclassmethod

   Nouveau dans la version 3.2.

   Obsolète depuis la version 3.3: Il est désormais possible
   d'utiliser "classmethod" avec "abstractmethod()", cela rend ce
   décorateur redondant.

   Sous-classe du décorateur natif "classmethod()" qui indique une
   méthode de classe ( "classmethod" ) abstraite. En dehors de cela,
   est similaire à "abstractmethod()".

   Ce cas spécial est obsolète car le décorateur "classmethod()" est
   désormais correctement identifié comme abstrait quand il est
   appliqué à une méthode abstraite :

      class C(ABC):
          @classmethod
          @abstractmethod
          def my_abstract_classmethod(cls, ...):
              ...

@abc.abstractstaticmethod

   Nouveau dans la version 3.2.

   Obsolète depuis la version 3.3: Il est désormais possible
   d'utiliser "staticmethod" avec "abstractmethod()", cela rend ce
   décorateur redondant.

   Sous-classe du décorateur natif "classmethod()" qui indique une
   méthode statique ( "staticmethod" ) abstraite. En dehors de cela,
   est similaire à "abstractmethod()".

   Ce cas spécial est obsolète car le décorateur "staticmethod()" est
   désormais correctement identifié comme abstrait quand appliqué à
   une méthode abstraite :

      class C(ABC):
          @staticmethod
          @abstractmethod
          def my_abstract_staticmethod(...):
              ...

@abc.abstractproperty

   Obsolète depuis la version 3.3: Il est désormais possible
   d'utiliser "property", "property.getter()", "property.setter()" et
   "property.deleter()" avec "abstractmethod()", ce qui rend ce
   décorateur redondant.

   Sous-classe de "property()", qui indique une propriété abstraite.

   Ce cas spécial est obsolète car le décorateur "property()" est
   désormais correctement identifié comme abstrait quand appliqué à
   une méthode abstraite :

      class C(ABC):
          @property
          @abstractmethod
          def my_abstract_property(self):
              ...

   L'exemple ci-dessus définit une propriété en lecture seule. Vous
   pouvez également définir une propriété en lecture-écriture
   abstraite en indiquant une ou plusieurs des méthodes sous-jacentes
   comme abstraite :

      class C(ABC):
          @property
          def x(self):
              ...

          @x.setter
          @abstractmethod
          def x(self, val):
              ...

   Si seuls certains composants sont abstraits, seuls ces composants
   abstraits nécessitent d'être mis à jour pour créer une propriété
   concrète dans une sous-classe :

      class D(C):
          @C.x.setter
          def x(self, val):
              ...

Le module "abc" fournit également la fonction suivante :

abc.get_cache_token()

   Renvoie le jeton de cache ( *cache token*) de l'ABC.

   Le jeton est un objet opaque (qui implémente le test d'égalité) qui
   identifie la version actuelle du cache de l'ABC pour les sous-
   classes virtuelles. Le jeton change avec chaque appel à
   "ABCMeta.register()" sur n'importe quelle ABC.

   Nouveau dans la version 3.4.

-[ Notes ]-

[1] Les développeurs C++ noteront que le concept Python de classe de
    base virtuelle ( *virtual base class* ) n'est pas le même que
    celui de C++.
