Typ-Variable-Tupel

Auf die gleiche Weise, wie eine normale Typvariable ein Platzhalter für einen einzelnen Typ wie int ist, ist eine Typvariable *Tupel* ein Platzhalter für einen *Tupel*-Typ wie Tuple[int, str].

Typ-Variable-Tupel werden erstellt mit

from typing import TypeVarTuple

Ts = TypeVarTuple('Ts')

Shape = TypeVarTuple('Shape')

class Array(Generic[*Shape]): ...

Height = NewType('Height', int)
Width = NewType('Width', int)
x: Array[Height, Width] = Array()

Time = NewType('Time', int)
Batch = NewType('Batch', int)
y: Array[Batch, Height, Width] = Array()
z: Array[Time, Batch, Height, Width] = Array()

class Array(Generic[*Shape]):

    def __init__(self, shape: Tuple[*Shape]):
        self._shape: Tuple[*Shape] = shape

    def get_shape(self) -> Tuple[*Shape]:
        return self._shape

shape = (Height(480), Width(640))
x: Array[Height, Width] = Array(shape)
y = abs(x)  # Inferred type is Array[Height, Width]
z = x + x   #        ...    is Array[Height, Width]

# Unpacking using the star operator in new versions of Python
class Array(Generic[*Shape]): ...

# Unpacking using ``Unpack`` in older versions of Python
class Array(Generic[Unpack[Shape]]): ...

def foo(arg1: Tuple[*Ts], arg2: Tuple[*Ts]): ...

a = (0,)
b = ('0',)
foo(a, b)  # Can Ts be bound to Tuple[int | str]?

def pointwise_multiply(
    x: Array[*Shape],
    y: Array[*Shape]
) -> Array[*Shape]: ...

x: Array[Height]
y: Array[Width]
z: Array[Height, Width]
pointwise_multiply(x, x)  # Valid
pointwise_multiply(x, y)  # Error
pointwise_multiply(x, z)  # Error

class Array(Generic[*Ts1, *Ts2]): ...  # Error

x: Array[int, str, bool]  # Ts1 = ???, Ts2 = ???

Typ-Konkatenation

Typ-Variable-Tupel müssen nicht alleine stehen; normale Typen können vorangestellt und/oder nachgestellt werden.

Shape = TypeVarTuple('Shape')
Batch = NewType('Batch', int)
Channels = NewType('Channels', int)

def add_batch_axis(x: Array[*Shape]) -> Array[Batch, *Shape]: ...
def del_batch_axis(x: Array[Batch, *Shape]) -> Array[*Shape]: ...
def add_batch_channels(
  x: Array[*Shape]
) -> Array[Batch, *Shape, Channels]: ...

a: Array[Height, Width]
b = add_batch_axis(a)      # Inferred type is Array[Batch, Height, Width]
c = del_batch_axis(b)      # Array[Height, Width]
d = add_batch_channels(a)  # Array[Batch, Height, Width, Channels]

Normale TypeVar-Instanzen können ebenfalls vorangestellt und/oder nachgestellt werden.

T = TypeVar('T')
Ts = TypeVarTuple('Ts')

def prefix_tuple(
    x: T,
    y: Tuple[*Ts]
) -> Tuple[T, *Ts]: ...

z = prefix_tuple(x=0, y=(True, 'a'))
# Inferred type of z is Tuple[int, bool, str]

Entpacken von Tupel-Typen

Wir erwähnten, dass ein TypeVarTuple für ein Tupel von Typen steht. Da wir ein TypeVarTuple entpacken können, erlauben wir aus Konsistenzgründen auch das Entpacken eines Tupel-Typs. Wie wir sehen werden, ermöglicht dies auch eine Reihe interessanter Funktionen.

def process_batch_channels(
    x: Array[Batch, *Tuple[Any, ...], Channels]
) -> None:
    ...


x: Array[Batch, Height, Width, Channels]
process_batch_channels(x)  # OK
y: Array[Batch, Channels]
process_batch_channels(y)  # OK
z: Array[Batch]
process_batch_channels(z)  # Error: Expected Channels.

y: Array[*Tuple[Any, ...]] = read_from_file()

def expect_variadic_array(
    x: Array[Batch, *Shape]
) -> None: ...

expect_variadic_array(y)  # OK

def expect_precise_array(
    x: Array[Batch, Height, Width, Channels]
) -> None: ...

expect_precise_array(y)  # OK

x: Tuple[int, *Ts, str, *Ts2]  # Error
y: Tuple[int, *Tuple[int, ...], str, *Tuple[str, ...]]  # Error

*args als Typ-Variable-Tupel

PEP 484 besagt, dass, wenn eine Typannotation für *args bereitgestellt wird, jedes Argument vom annotierten Typ sein muss. Das heißt, wenn wir *args als Typ int spezifizieren, dann müssen *alle* Argumente vom Typ int sein. Dies schränkt unsere Fähigkeit ein, die Typ-Signaturen von Funktionen zu spezifizieren, die heterogene Argumenttypen annehmen.

Wenn jedoch *args als Typ-Variable-Tupel annotiert wird, werden die Typen der einzelnen Argumente zu den Typen im Typ-Variable-Tupel:

Ts = TypeVarTuple('Ts')

def args_to_tuple(*args: *Ts) -> Tuple[*Ts]: ...

args_to_tuple(1, 'a')  # Inferred type is Tuple[int, str]

Im obigen Beispiel wird Ts an Tuple[int, str] gebunden. Wenn keine Argumente übergeben werden, verhält sich das Typ-Variable-Tupel wie ein leeres Tupel, Tuple[()].

Wie üblich können wir beliebige Tupel-Typen entpacken. Zum Beispiel können wir durch die Verwendung eines Typ-Variable-Tupels innerhalb eines Tupels anderer Typen auf Präfixe oder Suffixe der variadischen Argumentliste verweisen. Zum Beispiel:

# os.execle takes arguments 'path, arg0, arg1, ..., env'
def execle(path: str, *args: *Tuple[*Ts, Env]) -> None: ...

Beachten Sie, dass dies sich von

def execle(path: str, *args: *Ts, env: Env) -> None: ...

unterscheidet, da env hier ein nur-keyword-Argument wäre.

Die Verwendung eines entpackten, unbegrenzten Tupels ist äquivalent zum Verhalten von *args: int gemäß PEP 484, das null oder mehr Werte vom Typ int akzeptiert.

def foo(*args: *Tuple[int, ...]) -> None: ...

# equivalent to:
def foo(*args: int) -> None: ...

Das Entpacken von Tupel-Typen ermöglicht auch präzisere Typen für heterogene *args. Die folgende Funktion erwartet am Anfang eine int, null oder mehr str-Werte und am Ende eine str:

def foo(*args: *Tuple[int, *Tuple[str, ...], str]) -> None: ...

Der Vollständigkeit halber erwähnen wir, dass das Entpacken eines konkreten Tupels die Spezifikation von *args mit einer festen Anzahl von heterogenen Typen ermöglicht:

def foo(*args: *Tuple[int, str]) -> None: ...

foo(1, "hello")  # OK

Beachten Sie, dass in Übereinstimmung mit der Regel, dass Typ-Variable-Tupel immer entpackt verwendet werden müssen, die Annotation von *args als ein einfaches Typ-Variable-Tupel-Instanz *nicht* erlaubt ist.

def foo(*args: Ts): ...  # NOT valid

*args ist der einzige Fall, in dem ein Argument direkt als *Ts annotiert werden kann; andere Argumente sollten *Ts verwenden, um etwas anderes zu parametrisieren, z. B. Tuple[*Ts]. Wenn *args selbst als Tuple[*Ts] annotiert wird, gilt weiterhin das alte Verhalten: Alle Argumente müssen ein Tuple sein, das mit denselben Typen parametrisiert ist.

def foo(*args: Tuple[*Ts]): ...

foo((0,), (1,))    # Valid
foo((0,), (1, 2))  # Error
foo((0,), ('1',))  # Error

Schließlich ist zu beachten, dass ein Typ-Variable-Tupel *nicht* als Typ für **kwargs verwendet werden kann. (Wir kennen noch keinen Anwendungsfall dafür, daher ziehen wir es vor, den Boden für ein mögliches zukünftiges PEP frei zu halten.)

# NOT valid
def foo(**kwargs: *Ts): ...

Typ-Variable-Tupel mit Callable

Typ-Variable-Tupel können auch in den Argument-Abschnitten eines Callable verwendet werden.

class Process:
  def __init__(
    self,
    target: Callable[[*Ts], None],
    args: Tuple[*Ts],
  ) -> None: ...

def func(arg1: int, arg2: str) -> None: ...

Process(target=func, args=(0, 'foo'))  # Valid
Process(target=func, args=('foo', 0))  # Error

Andere Typen und normale Typvariablen können ebenfalls vor oder nach dem Typ-Variable-Tupel stehen.

T = TypeVar('T')

def foo(f: Callable[[int, *Ts, T], Tuple[T, *Ts]]): ...

Das Verhalten eines Callable, das ein entpacktes Element enthält, sei es ein TypeVarTuple oder ein Tupel-Typ, ist so, dass die Elemente so behandelt werden, als wären sie der Typ für *args. Also wird Callable[[*Ts], None] als Typ der Funktion behandelt:

def foo(*args: *Ts) -> None: ...

Callable[[int, *Ts, T], Tuple[T, *Ts]] wird als Typ der Funktion behandelt:

def foo(*args: *Tuple[int, *Ts, T]) -> Tuple[T, *Ts]: ...

Verhalten, wenn Typparameter nicht angegeben sind

Wenn eine generische Klasse, die durch ein Typ-Variable-Tupel parametrisiert ist, ohne Typ-Parameter verwendet wird, verhält sie sich so, als ob das Typ-Variable-Tupel durch Tuple[Any, ...] ersetzt würde.

def takes_any_array(arr: Array): ...

# equivalent to:
def takes_any_array(arr: Array[*Tuple[Any, ...]]): ...

x: Array[Height, Width]
takes_any_array(x)  # Valid
y: Array[Time, Height, Width]
takes_any_array(y)  # Also valid

Dies ermöglicht graduelles Typisieren: bestehende Funktionen, die zum Beispiel einen einfachen TensorFlow Tensor akzeptieren, bleiben gültig, auch wenn Tensor generisch gemacht wird und der aufrufende Code einen Tensor[Height, Width] übergibt.

Dies funktioniert auch in umgekehrter Richtung:

def takes_specific_array(arr: Array[Height, Width]): ...

z: Array
# equivalent to Array[*Tuple[Any, ...]]

takes_specific_array(z)

(Einzelheiten finden Sie im Abschnitt Entpacken von unbegrenzten Tupel-Typen.)

Auf diese Weise müssen Benutzer von Bibliotheken, selbst wenn diese aktualisiert werden, um Typen wie Array[Height, Width] zu verwenden, nicht auch Typannotationen auf ihren gesamten Code anwenden; Benutzer haben weiterhin die Wahl, welche Teile ihres Codes sie typisieren und welche nicht.

Aliase

Generische Aliase können mithilfe eines Typ-Variable-Tupels ähnlich wie reguläre Typvariablen erstellt werden.

IntTuple = Tuple[int, *Ts]
NamedArray = Tuple[str, Array[*Ts]]

IntTuple[float, bool]  # Equivalent to Tuple[int, float, bool]
NamedArray[Height]     # Equivalent to Tuple[str, Array[Height]]

Wie dieses Beispiel zeigt, werden alle an den Alias übergebenen Typparameter an das Typ-Variable-Tupel gebunden.

Für unser ursprüngliches Array-Beispiel (siehe Zusammenfassung Beispiele) ist dies wichtig, da es uns ermöglicht, praktische Aliase für Arrays mit fester Form oder festem Datentyp zu definieren:

Shape = TypeVarTuple('Shape')
DType = TypeVar('DType')
class Array(Generic[DType, *Shape]):

# E.g. Float32Array[Height, Width, Channels]
Float32Array = Array[np.float32, *Shape]

# E.g. Array1D[np.uint8]
Array1D = Array[DType, Any]

Wenn eine explizit leere Typparameterliste angegeben wird, wird das Typ-Variable-Tupel im Alias als leer gesetzt.

IntTuple[()]    # Equivalent to Tuple[int]
NamedArray[()]  # Equivalent to Tuple[str, Array[()]]

Wenn die Typparameterliste vollständig weggelassen wird, werden die nicht spezifizierten Typ-Variable-Tupel als Tuple[Any, ...] behandelt (ähnlich wie in Verhalten, wenn Typparameter nicht angegeben sind).

def takes_float_array_of_any_shape(x: Float32Array): ...
x: Float32Array[Height, Width] = Array()
takes_float_array_of_any_shape(x)  # Valid

def takes_float_array_with_specific_shape(
    y: Float32Array[Height, Width]
): ...
y: Float32Array = Array()
takes_float_array_with_specific_shape(y)  # Valid

Normale TypeVar-Instanzen können ebenfalls in solchen Aliasen verwendet werden.

T = TypeVar('T')
Foo = Tuple[T, *Ts]

# T bound to str, Ts to Tuple[int]
Foo[str, int]
# T bound to float, Ts to Tuple[()]
Foo[float]
# T bound to Any, Ts to an Tuple[Any, ...]
Foo

Substitution in Aliassen

Im vorherigen Abschnitt haben wir nur die einfache Verwendung von generischen Aliasen besprochen, bei denen die Typargumente nur einfache Typen waren. Es sind jedoch auch eine Reihe exotischerer Konstruktionen möglich.

Ts1 = TypeVar('Ts1')
Ts2 = TypeVar('Ts2')

IntTuple = Tuple[int, *Ts1]
IntFloatTuple = IntTuple[float, *Ts2]  # Valid

IntFloatsTuple = IntTuple[*Tuple[float, ...]]  # Valid

T = TypeVar('T')

IntTuple = Tuple[int, T]

IntTuple[str]                 # Valid
IntTuple[*Ts]                 # NOT valid
IntTuple[*Tuple[float, ...]]  # NOT valid

T = TypeVar('T')
Foo = Tuple[T, *Ts]

Foo[str, int]         # T bound to str, Ts to Tuple[int]
Foo[str, int, float]  # T bound to str, Ts to Tuple[int, float]

T1 = TypeVar('T1')
T2 = TypeVar('T2')
T3 = TypeVar('T3')

Tuple[*Ts, T1, T2]      # Valid
Tuple[T1, T2, *Ts]      # Valid
Tuple[T1, *Ts, T2, T3]  # Valid

Shrubbery = Tuple[*Ts, T1, T2]

Shrubbery[str, bool]              # T2=bool,  T1=str,   Ts=Tuple[()]
Shrubbery[str, bool, float]       # T2=float, T1=bool,  Ts=Tuple[str]
Shrubbery[str, bool, float, int]  # T2=int,   T1=float, Ts=Tuple[str, bool]

Ptang = Tuple[T1, *Ts, T2, T3]

Ptang[str, bool, float]       # T1=str, T3=float, T2=bool,  Ts=Tuple[()]
Ptang[str, bool, float, int]  # T1=str, T3=int,   T2=float, Ts=Tuple[bool]

Shrubbery[int]  # Not valid; Shrubbery needs at least two type arguments

Elderberries = Tuple[*Ts, T1]
Hamster = Elderberries[*Tuple[int, ...]]  # valid

Elderberries[*Tuple[int, ...], str]

Elderberries[str, *Tuple[int, ...]]

Ts1 = TypeVarTuple('Ts1')
Ts2 = TypeVarTuple('Ts2')

Camelot = Tuple[T, *Ts1]
Camelot[*Ts2]  # NOT valid

Überladungen für den Zugriff auf einzelne Typen

Für Situationen, in denen wir Zugriff auf jeden einzelnen Typ im Tupel der Typvariablen benötigen, können Überladungen mit einzelnen TypeVar-Instanzen anstelle des Tupels der Typvariablen verwendet werden.

Shape = TypeVarTuple('Shape')
Axis1 = TypeVar('Axis1')
Axis2 = TypeVar('Axis2')
Axis3 = TypeVar('Axis3')

class Array(Generic[*Shape]):

  @overload
  def transpose(
    self: Array[Axis1, Axis2]
  ) -> Array[Axis2, Axis1]: ...

  @overload
  def transpose(
    self: Array[Axis1, Axis2, Axis3]
  ) -> Array[Axis3, Axis2, Axis1]: ...

(Insbesondere für Array-Form-Operationen ist die Angabe von Überladungen für jeden möglichen Rang eine ziemlich umständliche Lösung. Sie ist jedoch das Beste, was wir ohne zusätzliche Typmanipulationsmechanismen tun können. Wir planen, diese in einem zukünftigen PEP einzuführen.)

Form-Arithmetik

Betrachtet man insbesondere den Anwendungsfall von Array-Formen, so ist anzumerken, dass es nach diesem PEP noch nicht möglich ist, arithmetische Transformationen von Array-Dimensionen zu beschreiben - zum Beispiel def repeat_each_element(x: Array[N]) -> Array[2*N]. Wir betrachten dies als außer Reichweite für den aktuellen PEP, planen jedoch, zusätzliche Mechanismen vorzuschlagen, die dies in einem zukünftigen PEP ermöglichen werden.

Unterstützung von Variadizität durch Aliase

Wie in der Einleitung erwähnt, ist es möglich, auf variadische Generics zu verzichten, indem einfach Aliase für jede mögliche Anzahl von Typparametern definiert werden.

class Array1(Generic[Axis1]): ...
class Array2(Generic[Axis1, Axis2]): ...

Dies scheint jedoch etwas umständlich zu sein – es erfordert, dass Benutzer ihren Code unnötigerweise mit 1, 2 usw. für jeden benötigten Rang durchsetzen.

Konstruktion von TypeVarTuple

TypeVarTuple begann als ListVariadic, basierend auf seiner Benennung in einer frühen Implementierung in Pyre.

Wir haben dies dann zu TypeVar(list=True) geändert, mit der Begründung, dass a) dies die Ähnlichkeit zu TypeVar besser hervorhebt und b) die Bedeutung von 'list' leichter zu verstehen ist als der Jargon von 'variadic'.

Sobald wir beschlossen hatten, dass eine variadische Typvariable sich wie ein Tuple verhalten sollte, erwogen wir auch TypeVar(bound=Tuple), was ähnlich intuitiv ist und die meisten unserer Wünsche erfüllt, ohne neue Argumente für TypeVar zu benötigen. Wir erkannten jedoch, dass dies uns zukünftig einschränken könnte, wenn wir zum Beispiel wünschen, dass Typgrenzen oder Varianz für variadische Typvariablen leicht anders funktionieren als die Semantik von TypeVar sonst implizieren würde. Außerdem möchten wir später möglicherweise Argumente unterstützen, die von regulären Typvariablen nicht unterstützt werden sollten (wie z. B. arbitrary_len [10]).

Wir haben uns daher für TypeVarTuple entschieden.

Nicht spezifizierte Typparameter: Tupel vs. TypeVarTuple

Um graduelles Tippen zu unterstützen, besagt dieser PEP, dass *beide* der folgenden Beispiele korrekt typgeprüft werden sollten.

def takes_any_array(x: Array): ...
x: Array[Height, Width]
takes_any_array(x)

def takes_specific_array(y: Array[Height, Width]): ...
y: Array
takes_specific_array(y)

Beachten Sie, dass dies im Gegensatz zum Verhalten des derzeit einzigen variadischen Typs in Python, Tuple, steht.

def takes_any_tuple(x: Tuple): ...
x: Tuple[int, str]
takes_any_tuple(x)  # Valid

def takes_specific_tuple(y: Tuple[int, str]): ...
y: Tuple
takes_specific_tuple(y)  # Error

Die Regeln für Tuple wurden bewusst so gewählt, dass der letztere Fall ein Fehler ist: Es wurde angenommen, dass der Programmierer eher einen Fehler gemacht hat, als dass die Funktion einen bestimmten Tuple erwartet, aber die spezifische Art des übergebenen Tuple dem Typüberprüfer unbekannt ist. Darüber hinaus ist Tuple eine Art Sonderfall, insofern als es zur Darstellung unveränderlicher Sequenzen verwendet wird. Das heißt, wenn der Typ eines Objekts als nicht-parametrisierter Tuple inferiert wird, ist dies nicht unbedingt auf unvollständiges Tippen zurückzuführen.

Im Gegensatz dazu ist es viel wahrscheinlicher, dass der Benutzer seinen Code einfach noch nicht vollständig annotiert hat oder dass die Signatur einer Shape-manipulierenden Bibliotheksfunktion noch nicht mit dem Typsystem ausgedrückt werden kann und daher die Rückgabe eines einfachen Array die einzige Option ist. Wir beschäftigen uns selten mit Arrays wahrhaft beliebiger Form; in bestimmten Fällen sind *einige* Teile der Form beliebig - zum Beispiel bei Sequenzen sind die ersten beiden Teile der Form oft 'batch' und 'time' - aber wir planen, diese Fälle in einem zukünftigen PEP explizit mit einer Syntax wie Array[Batch, Time, ...] zu unterstützen.

Wir trafen daher die Entscheidung, variadische Generics *außer* Tuple anders zu handhaben, um dem Benutzer mehr Flexibilität bei der Entscheidung zu geben, wie viel seines Codes er annotieren möchte, und um die Kompatibilität zwischen altem, nicht annotiertem Code und neuen Versionen von Bibliotheken, die diese Typannotationen verwenden, zu ermöglichen.

Änderung 1: Stern-Ausdrücke in Indizes

Die erste Grammatikänderung ermöglicht die Verwendung von Sternausdrücken in Indexoperationen (d. h. innerhalb von eckigen Klammern), was für die Unterstützung des Stern-Entpackens von TypeVarTuples erforderlich ist.

DType = TypeVar('DType')
Shape = TypeVarTuple('Shape')
class Array(Generic[DType, *Shape]):
    ...

Vorher

slices:
    | slice !','
    | ','.slice+ [',']

Nachher

slices:
    | slice !','
    | ','.(slice | starred_expression)+ [',']

Wie beim Stern-Entpacken in anderen Kontexten ruft der Stern-Operator __iter__ auf dem Aufrufer auf und fügt den Inhalt des resultierenden Iterators zu den an __getitem__ übergebenen Argumenten hinzu. Wenn wir beispielsweise foo[a, *b, c] machen und b.__iter__ einen Iterator erzeugt, der d und e liefert, erhält foo.__getitem__ (a, d, e, c).

Anders ausgedrückt, beachten Sie, dass x[..., *a, ...] dasselbe Ergebnis liefert wie x[(..., *a, ...)] (wobei beliebige Slices i:j in ... durch slice(i, j) ersetzt werden, mit der einzigen Ausnahme, dass x[*a] zu x[(*a,)] wird).

class TypeVarTuple:
    def __init__(self, name):
        self._name = name
        self._unpacked = UnpackedTypeVarTuple(name)
    def __iter__(self):
        yield self._unpacked
    def __repr__(self):
        return self._name

class UnpackedTypeVarTuple:
    def __init__(self, name):
        self._name = name
    def __repr__(self):
        return '*' + self._name

idxs = (1, 2)
array_slice = array[0, *idxs, -1]  # Equivalent to [0, 1, 2, -1]
array[0, *idxs, -1] = array_slice  # Also allowed

array[*idxs_to_select, *idxs_to_select]  # Equivalent to array[1, 2, 1, 2]

array[3:5, *idxs_to_select]  # Equivalent to array[3:5, 1, 2]

# Syntax error
array[*idxs_start:*idxs_end]

Änderung 2: *args als TypeVarTuple

Die zweite Änderung ermöglicht die Verwendung von *args: *Ts in Funktionsdefinitionen.

Vorher

star_etc:
| '*' param_no_default param_maybe_default* [kwds]
| '*' ',' param_maybe_default+ [kwds]
| kwds

Nachher

star_etc:
| '*' param_no_default param_maybe_default* [kwds]
| '*' param_no_default_star_annotation param_maybe_default* [kwds]  # New
| '*' ',' param_maybe_default+ [kwds]
| kwds

Wo

param_no_default_star_annotation:
| param_star_annotation ',' TYPE_COMMENT?
| param_star_annotation TYPE_COMMENT? &')'

param_star_annotation: NAME star_annotation

star_annotation: ':' star_expression

Wir müssen uns auch mit dem star_expression befassen, der sich aus dieser Konstruktion ergibt. Normalerweise tritt ein star_expression im Kontext von z. B. einer Liste auf, so dass ein star_expression behandelt wird, indem im Wesentlichen iter() auf dem gestarteten Objekt aufgerufen wird und die Ergebnisse des resultierenden Iterators an der entsprechenden Stelle in die Liste eingefügt werden. Für *args: *Ts müssen wir jedoch das star_expression auf eine andere Weise verarbeiten.

Wir tun dies, indem wir stattdessen einen Sonderfall für das star_expression, das aus *args: *Ts resultiert, erstellen und Code ausgeben, der äquivalent zu [annotation_value] = [*Ts] ist. Das heißt, wir erstellen einen Iterator aus Ts, indem wir Ts.__iter__ aufrufen, einen einzelnen Wert aus dem Iterator abrufen, verifizieren, dass der Iterator erschöpft ist, und diesen Wert als Annotationswert festlegen. Dies führt dazu, dass das entpackte TypeVarTuple direkt als Laufzeitanotation für *args gesetzt wird.

>>> Ts = TypeVarTuple('Ts')
>>> def foo(*args: *Ts): pass
>>> foo.__annotations__
{'args': *Ts}
# *Ts is the repr() of Ts._unpacked, an instance of UnpackedTypeVarTuple

Dies ermöglicht es der Laufzeitannotation, mit einer AST-Darstellung übereinzustimmen, die einen Starred-Knoten für die Annotationen von args verwendet - was wiederum für Werkzeuge wichtig ist, die auf dem AST basieren, wie z. B. mypy, um die Konstruktion korrekt zu erkennen.

>>> print(ast.dump(ast.parse('def foo(*args: *Ts): pass'), indent=2))
Module(
  body=[
    FunctionDef(
      name='foo',
      args=arguments(
        posonlyargs=[],
        args=[],
        vararg=arg(
          arg='args',
          annotation=Starred(
            value=Name(id='Ts', ctx=Load()),
            ctx=Load())),
        kwonlyargs=[],
        kw_defaults=[],
        defaults=[]),
      body=[
        Pass()],
      decorator_list=[])],
  type_ignores=[])

Beachten Sie, dass das einzige Szenario, in dem diese Grammatikänderung die Verwendung von *Ts als direkte Annotation (anstatt z. B. in Tuple[*Ts] verpackt) zulässt, *args ist. Andere Verwendungen sind immer noch ungültig.

x: *Ts                 # Syntax error
def foo(x: *Ts): pass  # Syntax error

>>> foo = [1]
>>> def bar(*args: *foo): pass
>>> bar.__annotations__
{'args': 1}

>>> foo = [1, 2]
>>> def bar(*args: *foo): pass
ValueError: too many values to unpack (expected 1)

Alternativen (Warum nicht einfach Unpack verwenden?)

Wenn diese Grammatikänderungen als zu belastend erachtet werden, gibt es zwei Alternativen.

Die erste wäre, **Änderung 1 zu unterstützen, aber nicht Änderung 2**. Variadische Generics sind uns wichtiger als die Fähigkeit, *args zu annotieren.

Die zweite Alternative wäre, **stattdessen ``Unpack`` zu verwenden**, was keine Grammatikänderungen erfordert. Wir betrachten dies jedoch aus zwei Gründen als suboptimal.

• Lesbarkeit. class Array(Generic[DType, Unpack[Shape]]) ist etwas sperrig; der Lesefluss wird durch die Länge von Unpack und die zusätzlichen eckigen Klammern unterbrochen. class Array(Generic[DType, *Shape]) ist viel einfacher zu überfliegen und kennzeichnet Shape dennoch als besonders.
• Intuitivität. Wir glauben, dass ein Benutzer die Bedeutung von *Ts intuitiver verstehen wird – insbesondere wenn er sieht, dass Ts ein TypeVar**Tuple** ist – als die Bedeutung von Unpack[Ts]. (Dies setzt voraus, dass der Benutzer mit Stern-Entpacken in anderen Kontexten vertraut ist; wenn der Benutzer Code liest oder schreibt, der variadische Generics verwendet, erscheint dies vernünftig.)

Wenn selbst Änderung 1 als zu bedeutend angesehen wird, wäre es daher besser, wenn wir unsere Optionen überdenken, bevor wir mit dieser zweiten Alternative fortfahren.

Anwendungsfall 1: Angabe von Form-Werten

Die einfachste Methode zur Parametrisierung von Array-Typen ist die Verwendung von Literal-Typparametern – z. B. Array[Literal[64], Literal[64]].

Wir können jedem Parameter Namen mit normalen Typvariablen zuweisen.

K = TypeVar('K')
N = TypeVar('N')

def matrix_vector_multiply(x: Array[K, N], y: Array[N]) -> Array[K]: ...

a: Array[Literal[64], Literal[32]]
b: Array[Literal[32]]
matrix_vector_multiply(a, b)
# Result is Array[Literal[64]]

Beachten Sie, dass solche Namen einen rein lokalen Geltungsbereich haben. Das heißt, der Name K ist nur innerhalb von matrix_vector_multiply an Literal[64] gebunden. Anders ausgedrückt, es besteht kein Zusammenhang zwischen dem Wert von K in verschiedenen Signaturen. Dies ist wichtig: Es wäre umständlich, wenn jede mit K benannte Achse im gesamten Programm den gleichen Wert haben müsste.

Der Nachteil dieses Ansatzes ist, dass wir keine Möglichkeit haben, Shape-Semantiken über verschiedene Aufrufe hinweg zu erzwingen. Zum Beispiel können wir das in der Motivation erwähnte Problem nicht lösen: Wenn eine Funktion ein Array mit den führenden Dimensionen 'Zeit × Stapel' zurückgibt und eine andere Funktion dasselbe Array unter der Annahme führender Dimensionen 'Stapel × Zeit' annimmt, haben wir keine Möglichkeit, dies zu erkennen.

Der Hauptvorteil ist, dass in einigen Fällen die Achsengrößen tatsächlich das sind, was uns interessiert. Dies gilt sowohl für einfache lineare Algebra-Operationen wie die obigen Matrixmanipulationen, als auch für kompliziertere Transformationen wie Faltungsschichten in neuronalen Netzen, bei denen es für den Programmierer von großem Nutzen wäre, die Array-Größe nach jeder Schicht mithilfe statischer Analyse inspizieren zu können. Um dies zu unterstützen, möchten wir in Zukunft Möglichkeiten für zusätzliche Typoperatoren erforschen, die Arithmetik auf Array-Shapes ermöglichen – zum Beispiel.

def repeat_each_element(x: Array[N]) -> Array[Mul[2, N]]: ...

Solche arithmetischen Typoperatoren wären nur sinnvoll, wenn Namen wie N sich auf die Achsengröße beziehen.

Anwendungsfall 2: Angabe von Form-Semantik

Ein zweiter Ansatz (der, auf dem die meisten Beispiele in diesem PEP basieren) besteht darin, auf die Annotation mit tatsächlicher Achsengröße zu verzichten und stattdessen den Achsen-*Typ* zu annotieren.

Dies würde es uns ermöglichen, das Problem der Durchsetzung von Shape-Eigenschaften über Aufrufe hinweg zu lösen. Zum Beispiel.

# lib.py

class Batch: pass
class Time: pass

def make_array() -> Array[Batch, Time]: ...

# user.py

from lib import Batch, Time

# `Batch` and `Time` have the same identity as in `lib`,
# so must take array as produced by `lib.make_array`
def use_array(x: Array[Batch, Time]): ...

Beachten Sie, dass in diesem Fall Namen *global* sind (in dem Umfang, in dem wir denselben Batch-Typ an verschiedenen Stellen verwenden). Da Namen sich jedoch nur auf Achsen-*Typen* beziehen, schränkt dies nicht den *Wert* bestimmter Achsen ein (d. h. dies schränkt nicht alle Achsen namens Height so ein, dass sie den gleichen Wert haben, sagen wir, durchgehend 480).

Das Argument *für* diesen Ansatz ist, dass in vielen Fällen der Achsen-*Typ* das Wichtigere ist, das es zu überprüfen gilt; uns ist wichtiger, welche Achse welche ist, als die genaue Größe jeder Achse.

Es schließt auch Fälle nicht aus, in denen wir Shape-Transformationen beschreiben möchten, ohne den Typ im Voraus zu kennen. Zum Beispiel können wir immer noch schreiben.

K = TypeVar('K')
N = TypeVar('N')

def matrix_vector_multiply(x: Array[K, N], y: Array[N]) -> Array[K]: ...

Wir können dies dann mit verwenden.

class Batch: pass
class Values: pass

batch_of_values: Array[Batch, Values]
value_weights: Array[Values]
matrix_vector_multiply(batch_of_values, value_weights)
# Result is Array[Batch]

Die Nachteile sind die Umkehrung der Vorteile aus Anwendungsfall 1. Insbesondere eignet sich dieser Ansatz nicht gut für Arithmetik auf Achsentypen: Mul[2, Batch] wäre genauso bedeutungslos wie 2 * int.

Diskussion

Beachten Sie, dass Anwendungsfälle 1 und 2 im Benutzercode sich gegenseitig ausschließen. Benutzer können Größe oder semantischen Typ überprüfen, aber nicht beides.

Nach diesem PEP sind wir uns nicht sicher, welcher Ansatz den größten Nutzen bringen wird. Da die in diesem PEP eingeführten Funktionen mit beiden Ansätzen kompatibel sind, lassen wir die Tür jedoch offen.

Warum nicht beides?

Betrachten Sie den folgenden 'normalen' Code.

def f(x: int): ...

Beachten Sie, dass wir Symbole sowohl für den Wert der Sache (x) als auch für den Typ der Sache (int) haben. Warum können wir nicht dasselbe mit Achsen tun? Zum Beispiel könnten wir mit einer imaginären Syntax schreiben.

def f(array: Array[TimeValue: TimeType]): ...

Dies würde es uns ermöglichen, auf die Achsengröße (sagen wir, 32) über das Symbol TimeValue *und* den Typ über das Symbol TypeType zuzugreifen.

Dies könnte sogar mit vorhandener Syntax über eine zweite Ebene der Parametrisierung möglich sein.

def f(array: array[TimeValue[TimeType]]): ..

Wir überlassen die Erkundung dieses Ansatzes jedoch der Zukunft.