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.
The collections
module has some concrete classes that derive from
ABCs; these can, of course, be further derived. In addition, the
collections.abc
submodule has some ABCs that can be used to test whether
a class or instance provides a particular interface, for example, if it is
hashable or if it is a mapping.
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 deABC
, 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
resteABCMeta
. En conséquence, hériter deABC
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 utilisantABCMeta
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 viasuper()
). 1Les 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 fonctionget_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'appelerregister()
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
ouNotImplemented
. Si elle renvoieTrue
, subclass est considérée comme sous-classe de cette ABC. Si elle renvoieFalse
, 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 renvoieNotImplemented
, 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éthodeget_iterator()
fait également partie de la classe de base abstraiteMyIterable
, 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 unMyIterable
.Enfin, la dernière ligne fait de
Foo
une sous-classe virtuelle deMyIterable
, 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 leget_iterator
deMyIterable
disponible comme une méthode deFoo
,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 deABCMeta
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.L'ajout dynamique de méthodes abstraites à une classe comme la modification de l'état d'abstraction d'une méthode ou d'une classe une fois celle-ci créée sont des opérations à réaliser avec
update_abstractmethods()
. En effet,abstractmethod()
n'affecte que les sous-classes dérivées utilisant l'héritage classique. Les "sous-classes virtuelles" enregistrées avec la méthoderegister()
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, arg1): ... @classmethod @abstractmethod def my_abstract_classmethod(cls, arg2): ... @staticmethod @abstractmethod def my_abstract_staticmethod(arg3): ... @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 êtreTrue
si au moins une des méthodes faisant partie du descripteur est abstraite. Par exemple, la classe nativeproperty
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
avecabstractmethod()
, 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, arg): ...
-
@
abc.
abstractstaticmethod
¶ Nouveau dans la version 3.2.
Obsolète depuis la version 3.3: Il est désormais possible d'utiliser
staticmethod
avecabstractmethod()
, 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(arg): ...
-
@
abc.
abstractproperty
¶ Obsolète depuis la version 3.3: Il est désormais possible d'utiliser
property
,property.getter()
,property.setter()
etproperty.deleter()
avecabstractmethod()
, 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.
-
abc.
update_abstractmethods
(cls)¶ Recalcule l'état d'abstraction de la classe. Il est nécessaire d'appeler cette fonction si les méthodes abstraites d'une classe sont ajoutées ou modifiées après la création de la classe. C'est notamment le cas dans les décorateurs de classe.
Pour permettre une utilisation en tant que décorateur, cette fonction renvoie cls.
Ne fait rien si cls n'est pas une instance de
ABCMeta
.Note
Cette fonction suppose que les classes mères de cls ont vu leur état recalculé, et ne fait rien pour recalculer celui des classes filles.
Nouveau dans la version 3.10.
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++.