Zusammenfassung

Derzeit kann **kwargs als Typ-Hint gegeben werden, solange alle durch sie spezifizierten Schlüsselwortargumente vom selben Typ sind. Dieses Verhalten kann jedoch sehr einschränkend sein. Daher schlagen wir in diesem PEP einen neuen Weg vor, um eine präzisere **kwargs-Typisierung zu ermöglichen. Der neue Ansatz dreht sich um die Verwendung von TypedDict zur Typisierung von **kwargs, die Schlüsselwortargumente unterschiedlicher Typen umfassen.

Motivation

Derzeit bedeutet die Annotation von **kwargs mit einem Typ T, dass der Typ von kwargs tatsächlich dict[str, T] ist. Zum Beispiel

def foo(**kwargs: str) -> None: ...

bedeutet, dass alle Schlüsselwortargumente in foo Strings sind (d.h. kwargs hat den Typ dict[str, str]). Dieses Verhalten beschränkt die Möglichkeit, **kwargs nur in den Fällen zu typisieren, in denen alle vom selben Typ sind. Es ist jedoch oft der Fall, dass Schlüsselwortargumente, die durch **kwargs übermittelt werden, unterschiedliche Typen haben, die vom Namen des Schlüssels abhängen. In diesen Fällen ist die Typisierung von **kwargs nicht möglich. Dies ist insbesondere ein Problem für bereits bestehende Codebasen, bei denen die Notwendigkeit, den Code zu refaktorisieren, um ordnungsgemäße Typannotationen einzuführen, als nicht lohnenswert erachtet werden kann. Dies wiederum hindert das Projekt daran, alle Vorteile zu nutzen, die Typ-Hints bieten können.

Darüber hinaus kann **kwargs verwendet werden, um den benötigten Codeaufwand zu reduzieren, wenn eine Top-Level-Funktion Teil einer öffentlichen API ist und eine Reihe von Hilfsfunktionen aufruft, die alle dieselben Schlüsselwortargumente erwarten. Wenn diese Hilfsfunktionen jedoch **kwargs verwenden würden, gibt es keine Möglichkeit, sie ordnungsgemäß zu typisieren, wenn die von ihnen erwarteten Schlüsselwortargumente unterschiedliche Typen haben. Selbst wenn die Schlüsselwortargumente vom selben Typ sind, gibt es keine Möglichkeit zu überprüfen, ob die Funktion mit Schlüsselwortnamen aufgerufen wird, die sie tatsächlich erwartet.

Wie im Abschnitt Beabsichtigte Verwendung beschrieben, ist die Verwendung von **kwargs nicht immer das beste Werkzeug für die Aufgabe. Trotzdem ist es immer noch ein weit verbreitetes Muster. Infolgedessen gab es viele Diskussionen über die Unterstützung einer präziseren **kwargs-Typisierung, und es wurde zu einer Funktion, die für einen großen Teil der Python-Community wertvoll wäre. Dies wird am besten durch das mypy GitHub Issue 4441 veranschaulicht, das viele reale Anwendungsfälle enthält, die von diesem Vorschlag profitieren könnten.

Ein weiterer erwähnenswerter Anwendungsfall, für den **kwargs ebenfalls praktisch sind, ist, wenn eine Funktion optionale Schlüsselwort-Only-Argumente ermöglichen soll, die keine Standardwerte haben. Ein Bedarf für ein solches Muster kann entstehen, wenn Werte, die normalerweise als Standardwerte zur Anzeige keiner Benutzereingabe verwendet werden, wie z. B. None, von einem Benutzer übergeben werden können und zu einem gültigen, nicht standardmäßigen Verhalten führen sollen. Beispielsweise kam dieses Problem in der beliebten Bibliothek httpx auf.

Begründung

PEP 589 führte den TypedDict-Typkonstruktor ein, der Dictionary-Typen mit String-Schlüsseln und Werten potenziell unterschiedlicher Typen unterstützt. Die Schlüsselwortargumente einer Funktion, die durch einen formalen Parameter repräsentiert werden, der mit einem Doppelstern beginnt, wie z. B. **kwargs, werden als Dictionary empfangen. Zusätzlich werden solche Funktionen oft mit entpackten Dictionaries aufgerufen, um Schlüsselwortargumente bereitzustellen. Dies macht TypedDict zu einem perfekten Kandidaten für eine präzisere **kwargs-Typisierung. Darüber hinaus können mit TypedDict Schlüsselwortnamen bei der statischen Typanalyse berücksichtigt werden. Das Festlegen des **kwargs-Typs mit einem TypedDict bedeutet jedoch, wie bereits erwähnt, dass jedes durch **kwargs spezifizierte Schlüsselwortargument ein TypedDict selbst ist. Zum Beispiel

class Movie(TypedDict):
    name: str
    year: int

def foo(**kwargs: Movie) -> None: ...

bedeutet, dass jedes Schlüsselwortargument in foo selbst ein Movie-Dictionary ist, das einen name-Schlüssel mit einem String-Wert und einen year-Schlüssel mit einem Integer-Wert hat. Um daher die Typisierung von kwargs als TypedDict zu unterstützen, ohne das aktuelle Verhalten zu brechen, muss ein neues Konstrukt eingeführt werden.

Um diesen Anwendungsfall zu unterstützen, schlagen wir vor, Unpack wiederzuverwenden, das ursprünglich in PEP 646 eingeführt wurde. Dafür gibt es mehrere Gründe

• Sein Name ist für den **kwargs-Typisierungsfall sehr passend und intuitiv, da unsere Absicht ist, die Schlüsselwortargumente aus dem bereitgestellten TypedDict zu „entpacken“.
• Die aktuelle Art der Typisierung von *args würde auf **kwargs erweitert werden, und diese sollen sich ähnlich verhalten.
• Es wäre nicht notwendig, neue Sonderformen einzuführen.
• Die Verwendung von Unpack für die in diesem PEP beschriebenen Zwecke stört nicht die in PEP 646 beschriebenen Anwendungsfälle.

Spezifikation

Mit Unpack führen wir eine neue Methode zur Annotation von **kwargs ein. Fortsetzung des vorherigen Beispiels

def foo(**kwargs: Unpack[Movie]) -> None: ...

würde bedeuten, dass **kwargs zwei von Movie spezifizierte Schlüsselwortargumente umfasst (d.h. einen name-Schlüssel vom Typ str und einen year-Schlüssel vom Typ int). Dies deutet darauf hin, dass die Funktion wie folgt aufgerufen werden sollte

kwargs: Movie = {"name": "Life of Brian", "year": 1979}

foo(**kwargs)                               # OK!
foo(name="The Meaning of Life", year=1983)  # OK!

Wenn Unpack verwendet wird, behandeln Typ-Checker kwargs innerhalb des Funktionskörpers als ein TypedDict

def foo(**kwargs: Unpack[Movie]) -> None:
    assert_type(kwargs, Movie)  # OK!

Die Verwendung der neuen Annotation hat keine Laufzeitauswirkung – sie wird nur von Typ-Checkern berücksichtigt. Alle Fehlerhinweise in den folgenden Abschnitten beziehen sich auf Typ-Checker-Fehler.

def foo(**kwargs: Unpack[Movie]) -> None: ...

movie: dict[str, object] = {"name": "Life of Brian", "year": 1979}
foo(**movie)  # WRONG! Movie is of type dict[str, object]

typed_movie: Movie = {"name": "The Meaning of Life", "year": 1983}
foo(**typed_movie)  # OK!

another_movie = {"name": "Life of Brian", "year": 1979}
foo(**another_movie)  # Depends on the type checker.

def foo(name, **kwargs: Unpack[Movie]) -> None: ...     # WRONG! "name" will
                                                        # always bind to the
                                                        # first parameter.

def foo(name, /, **kwargs: Unpack[Movie]) -> None: ...  # OK! "name" is a
                                                        # positional-only parameter,
                                                        # so **kwargs can contain
                                                        # a "name" keyword.

class Movie(TypedDict):
    title: str
    year: NotRequired[int]

class Animal(TypedDict):
    name: str

class Dog(Animal):
    breed: str

def accept_animal(**kwargs: Unpack[Animal]): ...
def accept_dog(**kwargs: Unpack[Dog]): ...

accept_dog = accept_animal  # OK! Expression of type Dog can be
                            # assigned to a variable of type Animal.

accept_animal = accept_dog  # WRONG! Expression of type Animal
                            # cannot be assigned to a variable of type Dog.

class Example(TypedDict):
    animal: Animal
    string: str
    number: NotRequired[int]

def src(**kwargs: Unpack[Example]): ...
def dest(*, animal: Dog, string: str, number: int = ...): ...

dest = src  # OK!

def dest(dog: Dog, string: str, number: int = ...): ...

dog: Dog = {"name": "Daisy", "breed": "labrador"}

dest(dog, "some string")  # OK!

dest = src                # Type checker error!
dest(dog, "some string")  # The same call fails at
                          # runtime now because 'src' expects
                          # keyword arguments.

def dest(**kwargs: Unpack[Animal]): ...
def src(name: str): ...

dog: Dog = {"name": "Daisy", "breed": "Labrador"}
animal: Animal = dog

dest = src      # WRONG!
dest(**animal)  # Fails at runtime.

def src(**kwargs): ...
def dest(**kwargs: Unpack[Movie]): ...

dest = src  # OK!

class Vehicle:
    ...

class Car(Vehicle):
    ...

class Motorcycle(Vehicle):
    ...

class Vehicles(TypedDict):
    car: Car
    moto: Motorcycle

def dest(**kwargs: Unpack[Vehicles]): ...
def src(**kwargs: Vehicle): ...

dest = src  # OK!

class Animal(TypedDict):
    name: str

class Dog(Animal):
    breed: str

def takes_name(name: str): ...

dog: Dog = {"name": "Daisy", "breed": "Labrador"}
animal: Animal = dog

def foo(**kwargs: Unpack[Animal]):
    print(kwargs["name"].capitalize())

def bar(**kwargs: Unpack[Animal]):
    takes_name(**kwargs)

def baz(animal: Animal):
    takes_name(**animal)

def spam(**kwargs: Unpack[Animal]):
    baz(kwargs)

foo(**animal)   # OK! foo only expects and uses keywords of 'Animal'.

bar(**animal)   # WRONG! This will fail at runtime because 'breed' keyword
                # will be passed to 'takes_name' as well.

spam(**animal)  # WRONG! Again, 'breed' keyword will be eventually passed
                # to 'takes_name'.

def bar(**kwargs: Unpack[Animal]):
    name = kwargs["name"]
    takes_name(name)

>>> Unpack[Movie]
*<class '__main__.Movie'>

Beabsichtigte Verwendung

Die beabsichtigten Anwendungsfälle für diesen Vorschlag sind im Abschnitt Motivation beschrieben. Zusammenfassend lässt sich sagen, dass eine präzisere **kwargs-Typisierung Vorteile für bereits bestehende Codebasen bringen kann, die sich ursprünglich für die Verwendung von **kwargs entschieden haben, aber nun reif genug sind, um einen strengeren Vertrag über Typ-Hints zu nutzen. Die Verwendung von **kwargs kann auch dazu beitragen, Code-Duplizierung und die Menge an Copy-Paste-Aufwand zu reduzieren, wenn viele Funktionen dieselbe Menge an Schlüsselwortargumenten benötigen. Schließlich sind **kwargs nützlich für Fälle, in denen eine Funktion optionale Schlüsselwortargumente ermöglichen muss, für die es keine offensichtlichen Standardwerte gibt.

Es ist jedoch anzumerken, dass in einigen Fällen bessere Werkzeuge für die Aufgabe vorhanden sind als die Verwendung von TypedDict zur Typisierung von **kwargs, wie in diesem PEP vorgeschlagen. Zum Beispiel ist es beim Schreiben von neuem Code, wenn alle Schlüsselwortargumente erforderlich sind oder Standardwerte haben, besser, alles explizit zu schreiben, anstatt **kwargs und ein TypedDict zu verwenden.

def foo(name: str, year: int): ...     # Preferred way.
def foo(**kwargs: Unpack[Movie]): ...

Ähnlich verhält es sich beim Typ-Hinting von Drittanbieterbibliotheken über Stubs: Es ist wieder besser, die Funktionssignatur explizit anzugeben – dies ist die einzige Möglichkeit, eine solche Funktion zu typisieren, wenn sie Standardargumente hat. Ein weiteres Problem, das in diesem Fall auftreten kann, wenn versucht wird, die Funktion mit einem TypedDict zu typisieren, ist, dass einige Standard-Funktionsparameter als schlüsselwort-only behandelt werden könnten.

def foo(name, year): ...              # Function in a third party library.

def foo(Unpack[Movie]): ...           # Function signature in a stub file.

foo("Life of Brian", 1979)            # This would be now failing type
                                      # checking but is fine.

foo(name="Life of Brian", year=1979)  # This would be the only way to call
                                      # the function now that passes type
                                      # checking.

Daher wird in diesem Fall wieder bevorzugt, eine solche Funktion explizit zu typisieren als

def foo(name: str, year: int): ...

Außerdem sollten Funktionen, die Teil der öffentlichen API sind, zugunsten von IDEs und Dokumentationsseiten, wo immer möglich, explizite Schlüsselwortparameter bevorzugen.

Wie man das lehrt

Dieses PEP könnte in der Dokumentation des Moduls typing verlinkt werden. Darüber hinaus könnte ein neuer Abschnitt über die Verwendung von Unpack zu den oben genannten Dokumenten hinzugefügt werden. Ähnliche Abschnitte könnten auch in der mypy-Dokumentation und der Typing-Dokumentation hinzugefügt werden.

Referenzimplementierung

Der mypy-Typ-Checker unterstützt bereits präzisere **kwargs-Typisierung unter Verwendung von Unpack.

Der Pyright-Typ-Checker bietet ebenfalls eine vorläufige Unterstützung für diese Funktion.

Abgelehnte Ideen

class Book(TypedDict):
    genre: str
    pages: int

TypedDictUnion = Movie | Book

def foo(**kwargs: Unpack[TypedDictUnion]) -> None: ...  # WRONG! Unsupported use
                                                        # of a union of
                                                        # TypedDicts to type
                                                        # **kwargs

@overload
def foo(**kwargs: Unpack[Movie]): ...

@overload
def foo(**kwargs: Unpack[Book]): ...

def foo(**kwargs: **Movie): ...

def foo(**kwargs: Unpack[Movie]): ...

Urheberrecht

Dieses Dokument wird in die Public Domain oder unter die CC0-1.0-Universal-Lizenz gestellt, je nachdem, welche Lizenz permissiver ist.