Kombination von Laufzeit- und statischen Verwendungen von Annotationen

Es gibt einen aufkommenden Trend, dass Bibliotheken Typ-Annotationen zur Laufzeit nutzen (z. B. `dataclasses`); die Möglichkeit, Typ-Annotationen um externe Daten zu erweitern, wäre ein großer Vorteil für diese Bibliotheken.

Hier ist ein Beispiel, wie ein hypothetisches Modul Annotationen nutzen könnte, um C-Strukturen zu lesen

UnsignedShort = Annotated[int, struct2.ctype('H')]
SignedChar = Annotated[int, struct2.ctype('b')]

class Student(struct2.Packed):
    # mypy typechecks 'name' field as 'str'
    name: Annotated[str, struct2.ctype("<10s")]
    serialnum: UnsignedShort
    school: SignedChar

# 'unpack' only uses the metadata within the type annotations
Student.unpack(record)
# Student(name=b'raymond   ', serialnum=4658, school=264)

Senkung der Hürden für die Entwicklung neuer Typkonstrukte

Typischerweise muss ein Entwickler bei der Hinzufügung eines neuen Typs diesen Typ in das `typing`-Modul hochladen und `mypy`, PyCharm, Pyre, pytype usw. ändern. Dies ist besonders wichtig, wenn man an Open-Source-Code arbeitet, der diese Typen verwendet, da der Code ohne zusätzliche Logik nicht sofort auf die Werkzeuge anderer Entwickler übertragbar wäre. Infolgedessen ist die Entwicklung und das Ausprobieren neuer Typen in einer Codebasis mit hohen Kosten verbunden. Idealerweise sollten Autoren neue Typen so einführen können, dass eine stufenweise Herabstufung möglich ist (z. B. wenn Clients keinen benutzerdefinierten mypy-Plugin haben), was die Entwicklungshürde senkt und ein gewisses Maß an Abwärtskompatibilität gewährleistet.

Angenommen, ein Autor möchte Unterstützung für Tagged Unions in Python hinzufügen. Eine Möglichkeit, dies zu erreichen, wäre, TypedDict in Python zu annotieren, sodass nur ein Feld gesetzt werden darf

Currency = Annotated[
    TypedDict('Currency', {'dollars': float, 'pounds': float}, total=False),
    TaggedUnion,
]

Dies ist eine etwas umständliche Syntax, aber sie ermöglicht es uns, an diesem Proof-of-Concept zu iterieren und Personen mit Typ-Prüfern (oder anderen Werkzeugen) arbeiten zu lassen, die diese Funktion noch nicht unterstützen, in einer Codebasis mit Tagged Unions. Der Autor könnte diesen Vorschlag leicht testen und die Fehler ausbügeln, bevor er versucht, Tagged Unions in typing, mypy usw. hochzuladen. Darüber hinaus könnten Werkzeuge, die keine Unterstützung für das Parsen der TaggedUnion-Annotation haben, Currency weiterhin als TypedDict behandeln, was immer noch eine gute Annäherung darstellt (etwas weniger streng).

Syntax

Annotated wird mit einem Typ und einer beliebigen Liste von Python-Werten parametrisiert, die die Annotationen darstellen. Hier sind die spezifischen Details der Syntax

• Das erste Argument für Annotated muss ein gültiger Typ sein
• Mehrere Typ-Annotationen werden unterstützt ( Annotated unterstützt variable Argumente)

  Annotated[int, ValueRange(3, 10), ctype("char")]
  

• Annotated muss mit mindestens zwei Argumenten aufgerufen werden ( Annotated[int] ist nicht gültig)
• Die Reihenfolge der Annotationen wird beibehalten und ist für Gleichheitsprüfungen relevant

  Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
      int, ctype("char"), ValueRange(3, 10)
  ]
  

• Verschachtelte Annotated-Typen werden abgeflacht, wobei die Metadaten mit der innersten Annotation beginnen

  Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
      int, ValueRange(3, 10), ctype("char")
  ]
  

• Duplizierte Annotationen werden nicht entfernt

  Annotated[int, ValueRange(3, 10)] != Annotated[
      int, ValueRange(3, 10), ValueRange(3, 10)
  ]
  

• Annotated kann mit verschachtelten und generischen Aliassen verwendet werden

  Typevar T = ...
  Vec = Annotated[List[Tuple[T, T]], MaxLen(10)]
  V = Vec[int]
  
  V == Annotated[List[Tuple[int, int]], MaxLen(10)]
  

Verbrauch von Annotationen

Letztendlich liegt die Verantwortung dafür, wie die Annotationen interpretiert werden (falls überhaupt), beim Werkzeug oder der Bibliothek, die auf den Annotated-Typ stößt. Ein Werkzeug oder eine Bibliothek, die auf einen Annotated-Typ stößt, kann die Annotationen durchsuchen, um festzustellen, ob sie von Interesse sind (z. B. mittels isinstance()).

Unbekannte Annotationen: Wenn ein Werkzeug oder eine Bibliothek Annotationen nicht unterstützt oder auf eine unbekannte Annotation stößt, sollte es diese einfach ignorieren und den annotierten Typ als zugrundeliegenden Typ behandeln. Wenn beispielsweise eine Annotation auf den Namen stößt, die keine Instanz von struct2.ctype ist (z. B. Annotated[str, 'foo', struct2.ctype("<10s")]), sollte die Entpackmethode diese ignorieren.

Namespaces für Annotationen: Namensräume sind für Annotationen nicht erforderlich, da die von den Annotationen verwendete Klasse als Namespace fungiert.

Mehrere Annotationen: Es liegt an dem Werkzeug, das die Annotationen konsumiert, zu entscheiden, ob der Client mehrere Annotationen für einen Typ haben darf und wie diese Annotationen zusammengeführt werden.

Da der Typ Annotated es ermöglicht, mehrere Annotationen desselben (oder verschiedener) Typs auf jedem Knoten anzubringen, sind die Werkzeuge oder Bibliotheken, die diese Annotationen konsumieren, dafür verantwortlich, mit möglichen Duplikaten umzugehen. Zum Beispiel könnten Sie bei der Wertebereichsanalyse Folgendes zulassen

T1 = Annotated[int, ValueRange(-10, 5)]
T2 = Annotated[T1, ValueRange(-20, 3)]

Abflachung von verschachtelten Annotationen, dies führt zu

T2 = Annotated[int, ValueRange(-10, 5), ValueRange(-20, 3)]

Interaktion mit get_type_hints()

typing.get_type_hints() erhält ein neues Argument include_extras, das standardmäßig auf False gesetzt ist, um die Abwärtskompatibilität zu wahren. Wenn include_extras False ist, werden die zusätzlichen Annotationen aus dem Rückgabewert entfernt. Andernfalls werden die Annotationen unverändert zurückgegeben.

@struct2.packed
class Student(NamedTuple):
    name: Annotated[str, struct.ctype("<10s")]

get_type_hints(Student) == {'name': str}
get_type_hints(Student, include_extras=False) == {'name': str}
get_type_hints(Student, include_extras=True) == {
    'name': Annotated[str, struct.ctype("<10s")]
}

Aliase & Bedenken wegen Ausführlichkeit

Das Schreiben von typing.Annotated überall kann ziemlich umständlich sein; glücklicherweise bedeutet die Möglichkeit, Annotationen zu aliasieren, dass wir in der Praxis nicht erwarten, dass Kunden viel Boilerplate-Code schreiben müssen.

T = TypeVar('T')
Const = Annotated[T, my_annotations.CONST]

class C:
    def const_method(self: Const[List[int]]) -> int:
        ...