typing

Les annotations de types : une description des valeurs qu’une fonction attend et de ce qu’elle renvoie. Elles sont vérifiées par les éditeurs et des outils comme mypy.

Sur cette page

Exemple

#
Python
def average(scores: list[int]) -> float:
    return sum(scores) / len(scores)

def find_points(ranking: dict[str, int], name: str) -> int | None:
    return ranking.get(name)

ranking: dict[str, int] = {"Léa": 250, "Jean": 80}

print(average([80, 90, 100]))
print(find_points(ranking, "Léa"))
print(find_points(ranking, "Mia"))
print(average([1.5, 2.5]))
Résultatrésultat enregistré, vous pouvez le vérifier
90.0
250
None
2.0

Le dernier appel passe des nombres à virgule flottante, alors que l’annotation dit list[int]. Python l’exécutera sans erreur, et mypy signalerait une incompatibilité de types.

Définition et utilisation

#

Les annotations de types sont une description ajoutée au code : def award(name: str, exp: int = 10) -> str: dit que la fonction prend une chaîne et un nombre, et renvoie une chaîne. Python ne les vérifie pas pendant l’exécution du programme. Elles sont utilisées par les éditeurs, qui suggèrent du code et soulignent les erreurs, et par des outils comme mypy ou pyright, qui détectent les erreurs avant que vous ne lanciez le programme.

Les types de collections s’écrivent avec des noms intégrés suivis de crochets : list[int], dict[str, int], tuple[int, int]. Une valeur de l’un de plusieurs types se décrit avec l’opérateur |, par exemple int | str, et str | None signifie une chaîne ou None. Ce sont les formes plus récentes des notations Union[int, str] et Optional[str] du module typing, que vous rencontrerez encore dans du code plus ancien.

Le module typing fournit aussi des outils pour les cas plus complexes. TypedDict décrit un dictionnaire à clés fixes, par exemple un enregistrement lu depuis du JSON. Protocol indique quelles méthodes un objet doit avoir, sans exiger d’héritage, ce qui permet aux outils de vérifier le duck typing avant l’exécution. Literal restreint les valeurs à celles indiquées, et Any désactive la vérification.

Les annotations sont aussi disponibles pendant l’exécution du programme, ce dont profitent @dataclass, pydantic ou FastAPI. Vous n’avez pas à tout typer d’un coup : commencez par les paramètres et les résultats des fonctions, car les outils déduisent généralement seuls les types des variables locales.

Syntaxe

#
Syntaxe
from typing import Literal, Protocol, TypedDict

def fonction(parametre: type, facultatif: type | None = None) -> type_resultat:
    ...

variable: dict[str, int] = {}

Les notations les plus courantes

#
  • list[int]

    Python 3.9

    Une liste d’entiers. On écrit de la même façon set[str], tuple[int, str] et dict[str, int] (type des clés et des valeurs).
  • int | str

    Python 3.10

    L’un de plusieurs types. Ancienne notation : Union[int, str].
  • str | None

    Python 3.10

    Une chaîne ou None. Ancienne notation : Optional[str].
  • Literal[...]

    Python 3.8

    Uniquement les valeurs énumérées, par exemple Literal["easy", "hard"].
  • TypedDict

    Python 3.8

    Un dictionnaire à clés fixes et à types de valeurs fixés.
  • Protocol

    Python 3.8

    Un ensemble de méthodes qu’un objet doit avoir, sans exiger d’héritage.
  • Callable[[int], str]

    Python 3.5

    Une fonction qui prend un int et renvoie un str. Importée depuis collections.abc ou typing.
  • Any

    Python 3.5

    N’importe quel type. Désactive la vérification pour une valeur donnée.
  • type Alias = ...

    Python 3.12

    Un alias de type nommé, par exemple type Scores = list[int].

Plus d’exemples

#
TypedDict : un dictionnaire aux clés connues
Python
from typing import NotRequired, TypedDict

class StudentData(TypedDict):
    name: str
    world: int
    badges: list[str]
    mentor: NotRequired[str]

def describe(student: StudentData) -> str:
    mentor = student.get("mentor", "aucun")
    return f"{student['name']} (monde {student['world']}), mentor : {mentor}"

lea: StudentData = {"name": "Léa", "world": 7, "badges": ["Start"]}
print(describe(lea))
print(type(lea).__name__)
Résultatrésultat enregistré, vous pouvez le vérifier
Léa (monde 7), mentor : aucun
dict

Pendant l’exécution du programme, c’est un dictionnaire ordinaire. NotRequired désigne une clé qui peut manquer.

Protocol : méthodes requises sans héritage
Python
from typing import Protocol

class Scorable(Protocol):
    def score(self) -> int: ...

class Quiz:
    def __init__(self, correct: int) -> None:
        self.correct = correct

    def score(self) -> int:
        return self.correct * 10

class Project:
    def score(self) -> int:
        return 50

def total(items: list[Scorable]) -> int:
    return sum(item.score() for item in items)

print(total([Quiz(3), Project(), Quiz(1)]))
Résultatrésultat enregistré, vous pouvez le vérifier
90

Quiz et Project n’héritent pas de Scorable, mais ont une méthode score(), donc les outils de vérification de types les accepteront.

Union, Optional et Literal
Python
from typing import Literal, Optional, Union

Difficulty = Literal["easy", "medium", "hard"]

def exp_for(difficulty: Difficulty) -> int:
    return {"easy": 5, "medium": 10, "hard": 20}[difficulty]

def parse_points(value: Union[int, str]) -> Optional[int]:
    if isinstance(value, int):
        return value
    return int(value) if value.isdigit() else None

print(exp_for("hard"))
print(parse_points(40), parse_points("75"), parse_points("beaucoup"))
Résultatrésultat enregistré, vous pouvez le vérifier
20
40 75 None

Dans du nouveau code, Union[int, str] s’écrit int | str, et Optional[int] s’écrit int | None.

Bonnes pratiques

#
  • Les annotations n’arrêteront pas des données erronées pendant l’exécution. Lancez mypy ou pyright, par exemple dans votre éditeur, et validez séparément les données externes.
  • Dans du nouveau code, écrivez list[int] et int | None au lieu de List[int] et Optional[int] du module typing. Les anciennes notations fonctionnent toujours.
  • Nommez par un alias un type complexe qui se répète à plusieurs endroits : type Ranking = dict[str, int] depuis Python 3.12, et dans les versions plus anciennes par une simple assignation Ranking = dict[str, int].

Entrées associées

#

Pratiquer dans les leçons

#

Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.