Fonctions génériques et décorateurs avec TypeVar, ParamSpec et la syntaxe de la PEP 695

Ce que c'est

Une variable de type signifie « un certain type, le même partout où il apparaît dans cette signature ». def first[T](xs: Sequence[T]) -> T indique au vérificateur que le résultat a le type d'élément de l'argument. Python 3.12 (PEP 695) a ajouté la syntaxe à crochets pour les fonctions, les classes et les alias type ; le code antérieur écrit T = TypeVar("T") et hérite de Generic[T]. La documentation de typing distingue les variables de type bornées ([S: str] : tout sous-type, résolu vers le type le plus spécifique) des variables contraintes ([A: (str, bytes)] : exactement l'un des types listés, comme pour AnyStr). ParamSpec (PEP 612, noté **P) capture toute une liste de paramètres, si bien qu'un décorateur peut être typé Callable[P, R] -> Callable[P, R] sans réduire la signature enveloppée à Callable[..., Any]. Concatenate[Arg, P] décrit un enveloppeur qui ajoute ou retire un paramètre initial.

Pourquoi c'est important

Le code générique non typé dégénère en Any, et tout ce qui y transite perd la vérification. Les décorateurs constituent la fuite la plus courante : un décorateur de nouvelle tentative ou de mise en cache annoté Callable[..., Any] efface la signature de chaque fonction qu'il décore, si bien que des arguments erronés aux points d'appel ne sont plus signalés.

Comment l'appliquer

• Utiliser la syntaxe à crochets sur 3.12 et versions ultérieures ; avec la PEP 695, la variance des paramètres de type d'une classe est inférée, si bien que les indicateurs covariant=/contravariant= ne s'écrivent plus à la main.
• Typer les décorateurs comme def deco[**P, R](f: Callable[P, R]) -> Callable[P, R] et transmettre *args: P.args, **kwargs: P.kwargs dans l'enveloppeur.
• Préférer une borne lorsque la fonction a besoin d'une capacité ; utiliser des contraintes lorsque le comportement diffère véritablement selon le type concret et que les deux ne doivent pas se mélanger.
• Utiliser typing.Self pour les méthodes qui renvoient l'instance, plutôt qu'une variable de type bornée fabriquée à la main ; la documentation montre les deux comme équivalents.
• Ne donner une valeur par défaut à un paramètre de type ([T = str], Python 3.13) que pour les paramètres optionnels de classes génériques.

Pièges

Une variable de type qui n'apparaît qu'une seule fois dans une signature ne relie rien à rien et ne contraint donc rien ; les vérificateurs mettent généralement en garde à ce sujet. Les variables de type de fonctions différentes ne sont pas liées entre elles même en cas de nom identique. P.args et P.kwargs sont de simples objets à l'exécution ; ils existent pour les vérificateurs. Les classes génériques ne sont pas spécialisées à l'exécution : Box[int]() crée une Box, et isinstance(x, Box[int]) lève une TypeError. Le code qui doit tourner sur 3.11 ou une version antérieure a besoin de la forme manuelle de TypeVar ; la PEP 695 indique que les variables de type traditionnelles ne devraient pas être combinées avec des paramètres de type à la nouvelle syntaxe, et que les vérificateurs devraient signaler cette combinaison comme une erreur.