Zusammenfassung

PEP 589 definiert eine Notation zur Deklaration eines TypedDict mit allen erforderlichen Schlüsseln und eine Notation zur Definition eines TypedDicts mit allen potenziell fehlenden Schlüsseln. Es gibt jedoch keinen Mechanismus, um einige Schlüssel als erforderlich und andere als potenziell fehlend zu deklarieren. Dieses PEP führt zwei neue Notationen ein: Required[], die auf einzelnen Elementen eines TypedDict verwendet werden kann, um sie als erforderlich zu kennzeichnen, und NotRequired[], die auf einzelnen Elementen verwendet werden kann, um sie als potenziell fehlend zu kennzeichnen.

Dieses PEP macht keine Änderungen an der Python-Grammatik. Die korrekte Verwendung von erforderlichen und potenziell fehlenden Schlüsseln von TypedDicts soll nur von statischen Typ-Checkern erzwungen werden und muss nicht von Python selbst zur Laufzeit erzwungen werden.

Motivation

Es ist nicht ungewöhnlich, ein TypedDict mit einigen erforderlichen und anderen potenziell fehlenden Schlüsseln definieren zu wollen. Derzeit ist die einzige Möglichkeit, ein solches TypedDict zu definieren, ein TypedDict mit einem Wert für total zu deklarieren und es dann von einem anderen TypedDict mit einem anderen Wert für total zu erben.

class _MovieBase(TypedDict):  # implicitly total=True
    title: str

class Movie(_MovieBase, total=False):
    year: int

Zwei verschiedene TypedDict-Typen für diesen Zweck deklarieren zu müssen, ist umständlich.

Dieses PEP führt zwei neue Typqualifizierer ein, typing.Required und typing.NotRequired, die die Definition eines einzigen TypedDicts mit einer Mischung aus erforderlichen und potenziell fehlenden Schlüsseln ermöglichen.

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

Dieses PEP ermöglicht auch die Definition von TypedDicts in der alternativen funktionalen Syntax mit einer Mischung aus erforderlichen und potenziell fehlenden Schlüsseln, was derzeit überhaupt nicht möglich ist, da die alternative Syntax keine Vererbung unterstützt.

Actor = TypedDict('Actor', {
    'name': str,
    # "in" is a keyword, so the functional syntax is necessary
    'in': NotRequired[List[str]],
})

Begründung

Man mag es ungewöhnlich finden, eine Notation vorzuschlagen, die die Kennzeichnung von erforderlichen Schlüsseln anstelle von potenziell fehlenden Schlüsseln priorisiert, wie es in anderen Sprachen wie TypeScript üblich ist.

interface Movie {
    title: string;
    year?: number;  // ? marks potentially-missing keys
}

Die Schwierigkeit besteht darin, dass das beste Wort zur Kennzeichnung eines potenziell fehlenden Schlüssels, Optional[], bereits in Python für einen völlig anderen Zweck verwendet wird: zur Kennzeichnung von Werten, die entweder vom angegebenen Typ oder None sein können. Insbesondere funktioniert Folgendes nicht:

class Movie(TypedDict):
    ...
    year: Optional[int]  # means int|None, not potentially-missing!

Der Versuch, ein beliebiges Synonym von "optional" zur Kennzeichnung potenziell fehlender Schlüssel zu verwenden (wie Missing[]), wäre Optional[] zu ähnlich und leicht mit ihm zu verwechseln.

Daher wurde beschlossen, sich stattdessen auf die positive Formulierung für erforderliche Schlüssel zu konzentrieren, die einfach als Required[] geschrieben werden kann.

Dennoch ist es üblich, dass Personen, die ein reguläres (total=True) TypedDict erweitern möchten, nur eine kleine Anzahl von potenziell fehlenden Schlüsseln hinzufügen wollen, was eine Möglichkeit erfordert, Schlüssel zu kennzeichnen, die nicht erforderlich und potenziell fehlend sind. Daher erlauben wir für diesen Fall auch die Form NotRequired[].

Spezifikation

Der Typqualifizierer typing.Required wird verwendet, um anzugeben, dass eine in einer TypedDict-Definition deklarierte Variable ein erforderlicher Schlüssel ist.

class Movie(TypedDict, total=False):
    title: Required[str]
    year: int

Zusätzlich wird der Typqualifizierer typing.NotRequired verwendet, um anzugeben, dass eine in einer TypedDict-Definition deklarierte Variable ein potenziell fehlender Schlüssel ist.

class Movie(TypedDict):  # implicitly total=True
    title: str
    year: NotRequired[int]

Es ist ein Fehler, Required[] oder NotRequired[] an einer anderen Stelle als bei einem Element eines TypedDict zu verwenden. Typ-Checker müssen diese Einschränkung erzwingen.

Es ist gültig, Required[] und NotRequired[] auch für Elemente zu verwenden, bei denen dies redundant ist, um bei Bedarf zusätzliche Klarheit zu schaffen.

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

Es ist ein Fehler, sowohl Required[] als auch NotRequired[] gleichzeitig zu verwenden.

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

Typ-Checker müssen diese Einschränkung erzwingen. Die Laufzeitimplementierungen von Required[] und NotRequired[] können diese Einschränkung ebenfalls erzwingen.

Die alternative funktionale Syntax für TypedDict unterstützt ebenfalls Required[] und NotRequired[].

Movie = TypedDict('Movie', {'name': str, 'year': NotRequired[int]})

class _MovieBase(TypedDict):  # implicitly total=True
    title: str

class Movie(_MovieBase, total=False):
    year: int

class _MovieBase(TypedDict):
    title: str

class Movie(_MovieBase):
    year: NotRequired[int]

class Movie(TypedDict):
    title: str
    year: NotRequired[Annotated[int, ValueRange(-9999, 9999)]]  # ok

class Movie(TypedDict):
    title: str
    year: Annotated[NotRequired[int], ValueRange(-9999, 9999)]  # ok

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

assert get_type_hints(Movie) == \
    {'title': str, 'year': int}
assert get_type_hints(Movie, include_extras=True) == \
    {'title': str, 'year': NotRequired[int]}

assert get_origin(Required[int]) is Required
assert get_args(Required[int]) == (int,)

assert get_origin(NotRequired[int]) is NotRequired
assert get_args(NotRequired[int]) == (int,)

assert Movie.__required_keys__ == frozenset({'title'})
assert Movie.__optional_keys__ == frozenset({'year'})

Abwärtskompatibilität

Dieses PEP führt keine abwärtsinkompatiblen Änderungen ein.

Wie man das lehrt

Um ein TypedDict zu definieren, bei dem die meisten Schlüssel erforderlich und einige potenziell fehlend sind, definieren Sie ein einzelnes TypedDict wie gewohnt (ohne das Schlüsselwort total) und markieren Sie die wenigen potenziell fehlenden Schlüssel mit NotRequired[].

Um ein TypedDict zu definieren, bei dem die meisten Schlüssel potenziell fehlend und einige erforderlich sind, definieren Sie ein total=False TypedDict und markieren Sie die wenigen erforderlichen Schlüssel mit Required[].

Wenn einige Elemente zusätzlich zu einem regulären Wert auch None akzeptieren, wird empfohlen, die TYP|None-Notation gegenüber Optional[TYP] zur Kennzeichnung solcher Elementwerte zu bevorzugen, um die Verwendung von Required[] oder NotRequired[] zusammen mit Optional[] innerhalb derselben TypedDict-Definition zu vermeiden.

Ja

from __future__ import annotations  # for Python 3.7-3.9

class Dog(TypedDict):
    name: str
    owner: NotRequired[str|None]

Okay (erforderlich für Python 3.5.3-3.6)

class Dog(TypedDict):
    name: str
    owner: 'NotRequired[str|None]'

Nein

class Dog(TypedDict):
    name: str
    # ick; avoid using both Optional and NotRequired
    owner: NotRequired[Optional[str]]

from typing import NotRequired, TypedDict

class Dog(TypedDict):
    name: str
    owner: NotRequired[str|None]

from __future__ import annotations  # for Python 3.7-3.9

from typing_extensions import NotRequired, TypedDict  # for Python <3.11 with (Not)Required

class Dog(TypedDict):
    name: str
    owner: NotRequired[str|None]

from typing import TypedDict  # oops: should import from typing_extensions instead
from typing_extensions import NotRequired

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

assert Movie.__required_keys__ == frozenset({'title', 'year'})  # yikes
assert Movie.__optional_keys__ == frozenset()  # yikes

Referenzimplementierung

Die Typ-Checker mypy 0.930, pyright 1.1.117 und pyanalyze 0.4.0 unterstützen Required und NotRequired.

Eine Referenzimplementierung der Laufzeitkomponente ist im Modul typing_extensions verfügbar.

Abgelehnte Ideen

class MyThing(TypedDict):
    opt1?: str  # may not exist, but if exists, value is string
    opt2: Optional[str]  # always exists, but may have None value

class MyThing(TypedDict):
    Optional[opt1]: str  # may not exist, but if exists, value is string
    opt2: Optional[str]  # always exists, but may have None value

class MyThing(TypedDict, total=False):
    req1: +int    # + means a required key, or Required[]
    opt1: str
    req2: +float

class MyThing(TypedDict):
    req1: int
    opt1: -str    # - means a potentially-missing key, or NotRequired[]
    req2: float

class MyThing(TypedDict):
    req1: int
    opt1: ~str    # ~ means a opposite-of-normal-totality key
    req2: float

>>> from typing import TypeVar
>>> (TypeVar('T', covariant=True), TypeVar('U', contravariant=True), TypeVar('V'))
(+T, -U, ~V)

class MyThing(TypedDict):
    req1: int
    opt1: str|Missing
    req2: float

class MyClass:
    attr: int|Missing

    def __init__(self, set_attr: bool) -> None:
        if set_attr:
            self.attr = 10

def foo(set_attr: bool) -> None:
    if set_attr:
        attr = 10
    reveal_type(attr)  # int|Missing

class Packet:
    data: Union[str, bytes]

def send_data(packet: Packet) -> None:
    if isinstance(packet.data, str):
        reveal_type(packet.data)  # str
        packet_bytes = packet.data.encode('utf-8')
    else:
        reveal_type(packet.data)  # bytes
        packet_bytes = packet.data
    socket.send(packet_bytes)

class Packet:
    data: Union[str, Missing]

def send_data(packet: Packet) -> None:
    if hasattr(packet, 'data'):
        reveal_type(packet.data)  # str
        packet_bytes = packet.data.encode('utf-8')
    else:
        reveal_type(packet.data)  # Missing? error?
        packet_bytes = b''
    socket.send(packet_bytes)

def send_data(packet_data: Optional[str]) -> None:
    packet_bytes: Union[str, Missing]
    if packet_data is not None:
        packet_bytes = packet.data.encode('utf-8')

    if 'packet_bytes' in locals():
        reveal_type(packet_bytes)  # bytes
        socket.send(packet_bytes)
    else:
        reveal_type(packet_bytes)  # Missing? error?

warning: Union[str, Missing]
import sys
if sys.version_info < (3, 6):
    warning = 'Your version of Python is unsupported!'

if 'warning' in globals():
    reveal_type(warning)  # str
    print(warning)
else:
    reveal_type(warning)  # Missing? error?

class MyThing(TypedDict, optional_as_missing=True):
    req1: int
    opt1: Optional[str]

class MyThing(TypedDict, optional_as_nullable=False):
    req1: int
    opt1: Optional[str]

Referenzen

Urheberrecht

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