29.7. `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) ?

Le module fournit les classes suivantes :

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 ABCMeta

class MyABC(metaclass=ABCMeta):
    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(metaclass=ABCMeta):

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

class abc.ABC¶

A helper class that has ABCMeta as its metaclass. With this class, an abstract base class can be created by simply deriving from ABC, avoiding sometimes confusing metaclass usage.

Note that the type of ABC is still ABCMeta, therefore inheriting from ABC requires the usual precautions regarding metaclass usage, as multiple inheritance may lead to metaclass conflicts.

Nouveau dans la version 3.4.

The abc module also provides the following decorators:

@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(metaclass=ABCMeta):
    @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 propriété native 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.

@abc.abstractclassmethod¶

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(metaclass=ABCMeta):
    @classmethod
    @abstractmethod
    def my_abstract_classmethod(cls, ...):
        ...

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.

@abc.abstractstaticmethod¶

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(metaclass=ABCMeta):
    @staticmethod
    @abstractmethod
    def my_abstract_staticmethod(...):
        ...

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.

@abc.abstractproperty(fget=None, fset=None, fdel=None, doc=None)¶

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

Using this function requires that the class’s metaclass is ABCMeta or is derived from it. A class that has a metaclass derived from ABCMeta cannot be instantiated unless all of its abstract methods and properties are overridden. The abstract properties can be called using any of the normal “super” call mechanisms.

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(metaclass=ABCMeta):
    @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(metaclass=ABCMeta):
    @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):
        ...

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.

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

29.7. `abc` — Classes de Base Abstraites¶

Sujet précédent

Sujet suivant

Cette page

29.7. abc — Classes de Base Abstraites¶

29.7. `abc` — Classes de Base Abstraites¶