Typ-Einschränkungsverhalten

Um das Verhalten von TypeIs zu spezifizieren, verwenden wir die folgende Terminologie:

• I = TypeIs Eingabetyp
• R = TypeIs Rückgabetyp
• A = Typ des an die Typ-Einschränkungsfunktion übergebenen Arguments (vor Einschränkung)
• NP = Eingeschränkter Typ (positiv; verwendet, wenn TypeIs True zurückgegeben hat)
• NN = Eingeschränkter Typ (negativ; verwendet, wenn TypeIs False zurückgegeben hat)

def narrower(x: I) -> TypeIs[R]: ...

def func1(val: A):
    if narrower(val):
        assert_type(val, NP)
    else:
        assert_type(val, NN)

Der Rückgabetyp R muss konsistent mit I sein. Der Typ-Checker sollte einen Fehler ausgeben, wenn diese Bedingung nicht erfüllt ist.

Formell sollte Typ *NP* zu A∧R eingeschränkt werden, der Schnittmenge von *A* und *R*, und Typ *NN* sollte zu A∧¬R eingeschränkt werden, der Schnittmenge von *A* und dem Komplement von *R*. In der Praxis können die theoretischen Typen für strenge Type Guards im Python-Typsystem nicht präzise ausgedrückt werden. Typ-Checker sollten auf praktische Annäherungen dieser Typen zurückgreifen. Als Faustregel sollte ein Typ-Checker die gleiche Typ-Einschränkungslogik verwenden – und konsistente Ergebnisse erzielen – wie bei der Behandlung von isinstance(). Diese Anleitung ermöglicht Änderungen und Verbesserungen, falls das Typsystem in Zukunft erweitert wird.

Beispiele

Typ-Einschränkung wird sowohl im positiven als auch im negativen Fall angewendet.

from typing import TypeIs, assert_type

def is_str(x: object) -> TypeIs[str]:
    return isinstance(x, str)

def f(x: str | int) -> None:
    if is_str(x):
        assert_type(x, str)
    else:
        assert_type(x, int)

Der endgültige eingeschränkte Typ kann aufgrund der Einschränkungen des zuvor bekannten Typs des Arguments schmaler als **R** sein.

from collections.abc import Awaitable
from typing import Any, TypeIs, assert_type
import inspect

def isawaitable(x: object) -> TypeIs[Awaitable[Any]]:
    return inspect.isawaitable(x)

def f(x: Awaitable[int] | int) -> None:
    if isawaitable(x):
        # Type checkers may also infer the more precise type
        # "Awaitable[int] | (int & Awaitable[Any])"
        assert_type(x, Awaitable[int])
    else:
        assert_type(x, int)

Es ist ein Fehler, auf einen Typ einzuschränken, der nicht mit dem Eingabetyp konsistent ist.

from typing import TypeIs

def is_str(x: int) -> TypeIs[str]:  # Type checker error
    ...

Subtyping

TypeIs ist auch als Rückgabetyp eines Callables gültig, zum Beispiel in Callback-Protokollen und in der speziellen Form Callable. In diesen Kontexten wird es als Subtyp von bool behandelt. Zum Beispiel ist Callable[..., TypeIs[int]] zu Callable[..., bool] zuweisbar.

Im Gegensatz zu TypeGuard ist TypeIs in seinem Argumenttyp invariant: TypeIs[B] ist kein Subtyp von TypeIs[A], auch wenn B ein Subtyp von A ist. Um den Grund zu verstehen, betrachten wir folgendes Beispiel:

def takes_narrower(x: int | str, narrower: Callable[[object], TypeIs[int]]):
    if narrower(x):
        print(x + 1)  # x is an int
    else:
        print("Hello " + x)  # x is a str

def is_bool(x: object) -> TypeIs[bool]:
    return isinstance(x, bool)

takes_narrower(1, is_bool)  # Error: is_bool is not a TypeIs[int]

(Beachten Sie, dass bool ein Subtyp von int ist.) Dieser Code schlägt zur Laufzeit fehl, da der Einschränker False zurückgibt (1 ist keine bool) und der else-Zweig in takes_narrower() genommen wird. Wenn der Aufruf takes_narrower(1, is_bool) erlaubt wäre, würden Typ-Checker diesen Fehler nicht erkennen.

Wann sollte man TypeIs verwenden

Python-Code verwendet oft Funktionen wie isinstance(), um zwischen verschiedenen möglichen Typen eines Wertes zu unterscheiden. Typ-Checker verstehen isinstance() und verschiedene andere Prüfungen und verwenden sie, um den Typ einer Variablen einzuschränken. Manchmal möchte man jedoch eine kompliziertere Prüfung an mehreren Stellen wiederverwenden oder verwendet eine Prüfung, die der Typ-Checker nicht versteht. In diesen Fällen können Sie eine TypeIs-Funktion definieren, um die Prüfung durchzuführen und Typ-Checkern zu ermöglichen, sie zur Einschränkung des Variablentyps zu verwenden.

Eine TypeIs-Funktion nimmt ein einzelnes Argument und ist so annotiert, dass sie TypeIs[T] zurückgibt, wobei T der Typ ist, zu dem Sie einschränken möchten. Die Funktion muss True zurückgeben, wenn das Argument vom Typ T ist, und andernfalls False. Die Funktion kann dann in if-Prüfungen verwendet werden, genau wie Sie isinstance() verwenden würden. Zum Beispiel:

from typing import TypeIs, Literal

type Direction = Literal["N", "E", "S", "W"]

def is_direction(x: str) -> TypeIs[Direction]:
    return x in {"N", "E", "S", "W"}

def maybe_direction(x: str) -> None:
    if is_direction(x):
        print(f"{x} is a cardinal direction")
    else:
        print(f"{x} is not a cardinal direction")

Eine sichere TypeIs-Funktion schreiben

Eine TypeIs-Funktion ermöglicht es Ihnen, das Typ-Einschränkungsverhalten Ihres Typ-Checkers zu überschreiben. Dies ist ein mächtiges Werkzeug, kann aber gefährlich sein, da eine falsch geschriebene TypeIs-Funktion zu inkonsistenten Typ-Prüfungen führen kann und Typ-Checker solche Fehler nicht erkennen können.

Damit eine Funktion, die TypeIs[T] zurückgibt, sicher ist, muss sie genau dann True zurückgeben, wenn das Argument mit Typ T kompatibel ist, und andernfalls False. Wenn diese Bedingung nicht erfüllt ist, kann der Typ-Checker falsche Typen ableiten.

Nachfolgend einige Beispiele für korrekte und falsche TypeIs-Funktionen:

from typing import TypeIs

# Correct
def good_typeis(x: object) -> TypeIs[int]:
    return isinstance(x, int)

# Incorrect: does not return True for all ints
def bad_typeis1(x: object) -> TypeIs[int]:
    return isinstance(x, int) and x > 0

# Incorrect: returns True for some non-ints
def bad_typeis2(x: object) -> TypeIs[int]:
    return isinstance(x, (int, float))

Diese Funktion demonstriert einige Fehler, die bei der Verwendung einer schlecht geschriebenen TypeIs-Funktion auftreten können. Diese Fehler werden von Typ-Checkern nicht erkannt.

def caller(x: int | str, y: int | float) -> None:
    if bad_typeis1(x):  # narrowed to int
        print(x + 1)
    else:  # narrowed to str (incorrectly)
        print("Hello " + x)  # runtime error if x is a negative int

    if bad_typeis2(y):  # narrowed to int
        # Because of the incorrect TypeIs, this branch is taken at runtime if
        # y is a float.
        print(y.bit_count())  # runtime error: this method exists only on int, not float
    else:  # narrowed to float (though never executed at runtime)
        pass

Hier ist ein Beispiel für eine korrekte TypeIs-Funktion für einen komplizierteren Typ:

from typing import TypedDict, TypeIs

class Point(TypedDict):
    x: int
    y: int

def is_point(x: object) -> TypeIs[Point]:
    return (
        isinstance(x, dict)
        and all(isinstance(key, str) for key in x)
        and "x" in x
        and "y" in x
        and isinstance(x["x"], int)
        and isinstance(x["y"], int)
    )

TypeIs und TypeGuard

TypeIs und typing.TypeGuard sind beides Werkzeuge zur Einschränkung des Variablentyps basierend auf einer benutzerdefinierten Funktion. Beide können verwendet werden, um Funktionen zu annotieren, die ein Argument nehmen und einen booleschen Wert zurückgeben, je nachdem, ob das Eingabeargument mit dem eingeschränkten Typ kompatibel ist. Diese Funktionen können dann in if-Prüfungen verwendet werden, um den Variablentyp einzuschränken.

TypeIs hat normalerweise das intuitivste Verhalten, führt aber mehr Einschränkungen ein. TypeGuard ist das richtige Werkzeug, wenn:

• Sie auf einen Typ einschränken möchten, der nicht mit dem Eingabetyp kompatibel ist, z. B. von list[object] zu list[int]. TypeIs erlaubt nur Einschränkungen zwischen kompatiblen Typen.
• Ihre Funktion gibt nicht für alle Eingabewerte, die mit dem eingeschränkten Typ kompatibel sind, True zurück. Zum Beispiel könnten Sie einen TypeGuard[int] haben, der nur für positive ganze Zahlen True zurückgibt.

TypeIs und TypeGuard unterscheiden sich in folgenden Punkten:

• TypeIs erfordert, dass der eingeschränkte Typ ein Subtyp des Eingabetyps ist, während TypeGuard dies nicht tut.
• Wenn eine TypeGuard-Funktion True zurückgibt, schränken Typ-Checker den Typ der Variablen genau auf den TypeGuard-Typ ein. Wenn eine TypeIs-Funktion True zurückgibt, können Typ-Checker einen präziseren Typ ableiten, der den zuvor bekannten Typ der Variablen mit dem TypeIs-Typ kombiniert. (Technisch gesehen ist dies als Schnittmengentyp bekannt.)
• Wenn eine TypeGuard-Funktion False zurückgibt, können Typ-Checker den Variablentyp überhaupt nicht einschränken. Wenn eine TypeIs-Funktion False zurückgibt, können Typ-Checker den Variablentyp einschränken, um den TypeIs-Typ auszuschließen.

Dieses Verhalten kann im folgenden Beispiel beobachtet werden:

from typing import TypeGuard, TypeIs, reveal_type, final

class Base: ...
class Child(Base): ...
@final
class Unrelated: ...

def is_base_typeguard(x: object) -> TypeGuard[Base]:
    return isinstance(x, Base)

def is_base_typeis(x: object) -> TypeIs[Base]:
    return isinstance(x, Base)

def use_typeguard(x: Child | Unrelated) -> None:
    if is_base_typeguard(x):
        reveal_type(x)  # Base
    else:
        reveal_type(x)  # Child | Unrelated

def use_typeis(x: Child | Unrelated) -> None:
    if is_base_typeis(x):
        reveal_type(x)  # Child
    else:
        reveal_type(x)  # Unrelated

Verhalten von TypeGuard ändern

PEP 724 schlug zuvor vor, das spezifizierte Verhalten von typing.TypeGuard zu ändern, sodass, wenn der Rückgabetyp des Guards mit dem Eingabetyp konsistent ist, das hier für TypeIs vorgeschlagene Verhalten angewendet würde. Dieser Vorschlag hat einige wichtige Vorteile: da er keine Laufzeitänderungen erfordert, sind nur Änderungen an Typ-Checkern notwendig, was es für Benutzer einfacher macht, die Vorteile des neuen, meist intuitiveren Verhaltens zu nutzen.

Dieser Ansatz hat jedoch einige gravierende Nachteile. Benutzer, die TypeGuard-Funktionen im Erwartungshorizont der bestehenden Semantiken gemäß PEP 647 geschrieben haben, würden subtile und potenziell brechende Änderungen in der Art und Weise erfahren, wie Typ-Checker ihren Code interpretieren. Das gespaltene Verhalten von TypeGuard, wo es auf eine Weise funktioniert, wenn der Rückgabetyp mit dem Eingabetyp konsistent ist, und auf eine andere Weise, wenn nicht, könnte für Benutzer verwirrend sein. Der Typing Council konnte keine Einigung zugunsten von PEP 724 erzielen; infolgedessen schlagen wir dieses alternative PEP vor.

Nichts tun

Sowohl dieses PEP als auch der in PEP 724 vorgeschlagene alternative Vorschlag haben Schwächen. Letztere werden oben diskutiert. Was dieses PEP betrifft, so führt es zwei spezielle Formen mit sehr ähnlichen Semantiken ein und schafft potenziell einen langen Migrationspfad für Benutzer, die derzeit TypeGuard verwenden und mit anderen Einschränkungssemantiken besser bedient wären.

Ein möglicher Weg nach vorn wäre es also, nichts zu tun und mit den aktuellen Einschränkungen des Typsystems zu leben. Wir glauben jedoch, dass die Einschränkungen des aktuellen TypeGuard, wie im Abschnitt „Motivation“ dargelegt, signifikant genug sind, dass es sich lohnt, das Typsystem zu ändern, um sie zu beheben. Wenn wir keine Änderung vornehmen, werden Benutzer weiterhin mit den gleichen unintuitiven Verhaltensweisen von TypeGuard konfrontiert, und das Typsystem wird nicht in der Lage sein, gängige Typ-Einschränkungsfunktionen wie inspect.isawaitable korrekt darzustellen.

Alternative Namen

Dieses PEP schlägt derzeit den Namen TypeIs vor, der betont, dass die spezielle Form TypeIs[T] zurückgibt, ob das Argument vom Typ T ist, und die TypeScript-Syntax widerspiegelt. Andere Namen wurden erwogen, einschließlich in einer früheren Version dieses PEP.

Optionen umfassen:

• IsInstance (Post von Paul Moore): betont, dass das neue Konstrukt ähnlich der eingebauten Funktion isinstance() verhält.
• Narrowed oder NarrowedTo: kürzer als TypeNarrower, behält aber die Verbindung zu „Type Narrowing“ (von Eric Traut vorgeschlagen).
• Predicate oder TypePredicate: spiegelt den Namen von TypeScript für die Funktion wider, „type predicates“.
• StrictTypeGuard (frühere Entwürfe von PEP 724): betont, dass das neue Konstrukt eine strengere Form der Typ-Einschränkung als typing.TypeGuard durchführt.
• TypeCheck (Post von Nicolas Tessore): betont die binäre Natur der Prüfung.
• TypeNarrower: betont, dass die Funktion den Typ ihres Arguments einschränkt. In einer früheren Version dieses PEP verwendet.