Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / Python

Références anticipées dans les annotations de type

En Python 3.12, placez un nom de type entre guillemets s’il n’est pas encore disponible à la définition d’une méthode. Résolvez ensuite la référence si vous avez besoin de l’objet classe.

Version : Python 3.12

Syntaxe

# Quote a name that is not bound yet:
def f(value: "Later") -> "Later": ...

# For a union, quote the entire expression:
def g(value: "int | Later") -> None: ...

# Alternatively, as a separate module using postponed evaluation:
from __future__ import annotations

def f(value: Later) -> Later: ...

Une référence anticipée dans une annotation de type désigne un type dont le nom n’est pas encore disponible là où la fonction est définie. En Python 3.12, sans évaluation différée, les annotations de fonction sont évaluées à l’exécution de def, et non lors de l’appel. Si le nom du type n’est pas disponible à ce moment-là, l’utiliser sans guillemets provoque NameError. Les annotations aident les outils de vérification statique ; Python lui-même ne s’en sert pas pour vérifier les arguments ni les valeurs de retour.

Dans WorkItem.from_dict, -> "WorkItem" désigne la classe dont le corps est encore en cours d’exécution. Dans Project.add_module, module: "Module" désigne une classe définie plus bas. Dans les deux cas, le littéral de chaîne conserve la référence sans rechercher immédiatement le nom. Pour une union, mettez l’expression entière entre guillemets : "int | Module". Sans évaluation différée, int | "Module" provoque TypeError, car | reçoit un type et une chaîne.

Vous pouvez aussi placer from __future__ import annotations au début du module, après son éventuelle docstring. En Python 3.12, cet import conserve les annotations de fonction sous forme de chaînes. Vous pouvez donc écrire -> WorkItem et module: Module sans guillemets. Il ne diffère pas l’évaluation des expressions ordinaires hors des annotations, comme les valeurs par défaut des paramètres.

Dans l’exemple, __annotations__ contient des chaînes. Une fois les deux classes définies, typing.get_type_hints() recherche les noms dans les espaces de noms appropriés et résout les références en objets classes. Un nom absent peut encore provoquer NameError, par exemple s’il n’a été importé que dans if TYPE_CHECKING:. Ne résolvez pas d’annotations non fiables : l’évaluation de leurs expressions peut exécuter du code.

Exemples

from typing import get_type_hints


class WorkItem:
    def __init__(self, title: str) -> None:
        self.title = title

    @classmethod
    def from_dict(cls, data: dict[str, str]) -> "WorkItem":
        return cls(data["title"])


class Project:
    def __init__(self) -> None:
        self.modules = []

    def add_module(self, module: "Module") -> None:
        self.modules.append(module)


class Module:
    pass


print(repr(WorkItem.from_dict.__annotations__["return"]))
print(repr(Project.add_module.__annotations__["module"]))
print(get_type_hints(WorkItem.from_dict)["return"] is WorkItem)
print(get_type_hints(Project.add_module)["module"] is Module)

Résultat

'WorkItem'
'Module'
True
True

Les deux premières lignes montrent la représentation des chaînes de `__annotations__`. Les deux résultats `True` confirment que les annotations résolues sont exactement les objets classes `WorkItem` et `Module`.

Leçons associées

  • Python · Leçon 3 · Avancé · Version : 5
  • Python · Leçon 7 · Avancé · Version : 5

Sources