Generische Funktionen und Decorators mit TypeVar, ParamSpec und der PEP-695-Syntax

Worum es geht

Eine Typvariable bedeutet „irgendein Typ, derselbe überall, wo er in dieser Signatur vorkommt“. def first[T](xs: Sequence[T]) -> T teilt dem Checker mit, dass das Ergebnis den Elementtyp des Arguments hat. Python 3.12 (PEP 695) hat die Klammersyntax für Funktionen, Klassen und type-Aliase eingeführt; älterer Code schreibt T = TypeVar("T") und erbt von Generic[T]. Die typing-Dokumentation unterscheidet beschränkte Typvariablen ([S: str]: jeder Subtyp, aufgelöst zum spezifischsten Typ) von eingeschränkten ([A: (str, bytes)]: genau einer der aufgeführten Typen, wie bei AnyStr). ParamSpec (PEP 612, geschrieben **P) erfasst eine ganze Parameterliste, sodass ein Decorator als Callable[P, R] -> Callable[P, R] typisiert werden kann, ohne die umschlossene Signatur zu Callable[..., Any] zu reduzieren. Concatenate[Arg, P] beschreibt einen Wrapper, der einen führenden Parameter hinzufügt oder entfernt.

Warum es wichtig ist

Ungetypter generischer Code verkommt zu Any, und alles, was hindurchfliesst, verliert die Prüfung. Decorators sind das häufigste Leck: Ein mit Callable[..., Any] annotierter Retry- oder Caching-Decorator löscht die Signatur jeder von ihm dekorierten Funktion, sodass falsche Argumente an den Aufrufstellen nicht mehr gemeldet werden.

So wird es angewendet

• Die Klammersyntax ab 3.12 verwenden; mit PEP 695 wird die Varianz von Klassen-Typparametern automatisch abgeleitet, sodass die Flags covariant=/contravariant= nicht mehr von Hand geschrieben werden.
• Decorators als def deco[**P, R](f: Callable[P, R]) -> Callable[P, R] typisieren und im Wrapper *args: P.args, **kwargs: P.kwargs weiterreichen.
• Einen Bound bevorzugen, wenn die Funktion eine Fähigkeit benötigt; Constraints verwenden, wenn sich das Verhalten pro konkretem Typ tatsächlich unterscheidet und die beiden nicht vermischt werden dürfen.
• typing.Self für Methoden verwenden, die die Instanz zurückgeben, statt eine selbst gebaute beschränkte Typvariable; die Dokumentation zeigt beide als gleichwertig.
• Einem Typparameter nur bei optionalen Parametern generischer Klassen einen Standardwert geben ([T = str], Python 3.13).

Stolpersteine

Eine Typvariable, die nur einmal in einer Signatur vorkommt, verbindet nichts mit irgendetwas und schränkt daher nichts ein; Checker warnen davor typischerweise. Typvariablen verschiedener Funktionen stehen in keiner Beziehung, selbst wenn sie gleich benannt sind. P.args und P.kwargs sind zur Laufzeit einfache Objekte; sie existieren für Checker. Generische Klassen werden zur Laufzeit nicht spezialisiert: Box[int]() erzeugt eine Box, und isinstance(x, Box[int]) löst TypeError aus. Code, der auf 3.11 oder älter laufen muss, braucht die manuelle TypeVar-Form; PEP 695 besagt, dass traditionelle Typvariablen nicht mit Typparametern der neuen Syntax kombiniert werden sollten und dass Checker die Kombination als Fehler kennzeichnen sollten.