Deklaration

Eine Parameterspezifikationsvariable wird ähnlich wie eine normale Typvariable mit typing.TypeVar definiert.

from typing import ParamSpec
P = ParamSpec("P")         # Accepted
P = ParamSpec("WrongName") # Rejected because P =/= WrongName

Die Laufzeit sollte bounds und covariant und contravariant Argumente in der Deklaration akzeptieren, genau wie typing.TypeVar, aber vorerst werden wir die Standardisierung der Semantik dieser Optionen auf eine spätere PEP verschieben.

Gültige Verwendungspositionen

Zuvor waren nur eine Liste von Parameterargumenten ([A, B, C]) oder eine Ellipse (die „undefinierte Parameter“ bedeutet) als erstes „Argument“ für typing.Callable akzeptabel. Nun erweitern wir dies um zwei neue Optionen: eine Parameterspezifikationsvariable (Callable[P, int]) oder eine Verkettung einer Parameterspezifikationsvariable (Callable[Concatenate[int, P], int]).

callable ::= Callable "[" parameters_expression, type_expression "]"

parameters_expression ::=
  | "..."
  | "[" [ type_expression ("," type_expression)* ] "]"
  | parameter_specification_variable
  | concatenate "["
                   type_expression ("," type_expression)* ","
                   parameter_specification_variable
                "]"

wobei parameter_specification_variable eine typing.ParamSpec Variable ist, die wie oben definiert deklariert wurde, und concatenate typing.Concatenate ist.

Wie zuvor sind parameters_expressions allein an Stellen, wo ein Typ erwartet wird, nicht akzeptabel

def foo(x: P) -> P: ...                           # Rejected
def foo(x: Concatenate[int, P]) -> int: ...       # Rejected
def foo(x: typing.List[P]) -> None: ...           # Rejected
def foo(x: Callable[[int, str], P]) -> None: ...  # Rejected

Benutzerdefinierte generische Klassen

So wie das Erben einer Klasse von Generic[T] eine Klasse generisch für einen einzelnen Parameter macht (wenn T eine TypeVar ist), macht das Erben einer Klasse von Generic[P] eine Klasse generisch für parameters_expressions (wenn P ein ParamSpec ist).

T = TypeVar("T")
P_2 = ParamSpec("P_2")

class X(Generic[T, P]):
  f: Callable[P, int]
  x: T

def f(x: X[int, P_2]) -> str: ...                    # Accepted
def f(x: X[int, Concatenate[int, P_2]]) -> str: ...  # Accepted
def f(x: X[int, [int, bool]]) -> str: ...            # Accepted
def f(x: X[int, ...]) -> str: ...                    # Accepted
def f(x: X[int, int]) -> str: ...                    # Rejected

Nach den oben definierten Regeln würde das Ausschreiben einer konkreten Instanz einer Klasse, die nur in Bezug auf einen einzigen ParamSpec generisch ist, hässliche doppelte Klammern erfordern. Aus ästhetischen Gründen erlauben wir, diese wegzulassen.

class Z(Generic[P]):
  f: Callable[P, int]

def f(x: Z[[int, str, bool]]) -> str: ...   # Accepted
def f(x: Z[int, str, bool]) -> str: ...     # Equivalent

# Both Z[[int, str, bool]] and Z[int, str, bool] express this:
class Z_instantiated:
  f: Callable[[int, str, bool], int]

Semantik

Die Inferenzregeln für den Rückgabetyp einer Funktionsaufrufs, dessen Signatur eine ParamSpec-Variable enthält, sind analog zu denen bei der Auswertung von TypeVars.

def changes_return_type_to_str(x: Callable[P, int]) -> Callable[P, str]: ...

def returns_int(a: str, b: bool) -> int: ...

f = changes_return_type_to_str(returns_int) # f should have the type:
                                            # (a: str, b: bool) -> str

f("A", True)               # Accepted
f(a="A", b=True)           # Accepted
f("A", "A")                # Rejected

expects_str(f("A", True))  # Accepted
expects_int(f("A", True))  # Rejected

Genau wie bei herkömmlichen TypeVars kann ein Benutzer denselben ParamSpec mehrmals in den Argumenten derselben Funktion einfügen, um eine Abhängigkeit zwischen mehreren Argumenten anzuzeigen. In diesen Fällen kann der Typ-Checker zu einem gemeinsamen Verhalten-Obertyp auflösen (d. h. eine Menge von Parametern, für die alle gültigen Aufrufe in beiden Untertypen gültig sind), ist aber nicht dazu verpflichtet.

P = ParamSpec("P")

def foo(x: Callable[P, int], y: Callable[P, int]) -> Callable[P, bool]: ...

def x_y(x: int, y: str) -> int: ...
def y_x(y: int, x: str) -> int: ...

foo(x_y, x_y)  # Should return (x: int, y: str) -> bool

foo(x_y, y_x)  # Could return (__a: int, __b: str) -> bool
               # This works because both callables have types that are
               # behavioral subtypes of Callable[[int, str], int]


def keyword_only_x(*, x: int) -> int: ...
def keyword_only_y(*, y: int) -> int: ...
foo(keyword_only_x, keyword_only_y) # Rejected

Die Konstruktoren benutzerdefinierter Klassen, die auf ParamSpecs generisch sind, sollten auf die gleiche Weise ausgewertet werden.

U = TypeVar("U")

class Y(Generic[U, P]):
  f: Callable[P, str]
  prop: U

  def __init__(self, f: Callable[P, str], prop: U) -> None:
    self.f = f
    self.prop = prop

def a(q: int) -> str: ...

Y(a, 1)   # Should resolve to Y[(q: int), int]
Y(a, 1).f # Should resolve to (q: int) -> str

Die Semantik von Concatenate[X, Y, P] bedeutet, dass es die von P repräsentierten Parameter mit zwei vorangestellten positionsabhängigen Parametern darstellt. Das bedeutet, wir können es verwenden, um höherrangige Funktionen darzustellen, die eine endliche Anzahl von Parametern eines Aufrufs hinzufügen, entfernen oder transformieren.

def bar(x: int, *args: bool) -> int: ...

def add(x: Callable[P, int]) -> Callable[Concatenate[str, P], bool]: ...

add(bar)       # Should return (__a: str, x: int, *args: bool) -> bool

def remove(x: Callable[Concatenate[int, P], int]) -> Callable[P, bool]: ...

remove(bar)    # Should return (*args: bool) -> bool

def transform(
  x: Callable[Concatenate[int, P], int]
) -> Callable[Concatenate[str, P], bool]: ...

transform(bar) # Should return (__a: str, *args: bool) -> bool

Das bedeutet auch, dass, während jede Funktion, die ein R zurückgibt, typing.Callable[P, R] erfüllen kann, nur Funktionen, die positionsabhängig in ihrer ersten Position mit einem X aufgerufen werden können, typing.Callable[Concatenate[X, P], R] erfüllen können.

def expects_int_first(x: Callable[Concatenate[int, P], int]) -> None: ...

@expects_int_first # Rejected
def one(x: str) -> int: ...

@expects_int_first # Rejected
def two(*, x: int) -> int: ...

@expects_int_first # Rejected
def three(**kwargs: int) -> int: ...

@expects_int_first # Accepted
def four(*args: int) -> int: ...

Es gibt immer noch einige Klassen von Dekoratoren, die mit diesen Features noch nicht unterstützt werden

• die, die eine **variable** Anzahl von Parametern hinzufügen/entfernen/ändern (zum Beispiel wird functools.partial auch nach dieser PEP nicht typisierbar bleiben)
• die, die nur-Schlüsselwortparameter hinzufügen/entfernen/ändern (siehe Verketten von Schlüsselwortparametern für weitere Details).

Gültige Verwendungspositionen

Diese „Eigenschaften“ können nur als annotierte Typen für *args und **kwargs verwendet werden, zugegriffen von einem bereits im Gültigkeitsbereich befindlichen ParamSpec.

def puts_p_into_scope(f: Callable[P, int]) -> None:

  def inner(*args: P.args, **kwargs: P.kwargs) -> None:      # Accepted
    pass

  def mixed_up(*args: P.kwargs, **kwargs: P.args) -> None:   # Rejected
    pass

  def misplaced(x: P.args) -> None:                          # Rejected
    pass

def out_of_scope(*args: P.args, **kwargs: P.kwargs) -> None: # Rejected
  pass

Darüber hinaus, da die Standardart von Parametern in Python ((x: int)) sowohl positionsabhängig als auch über seinen Namen angesprochen werden kann, können zwei gültige Aufrufe einer (*args: P.args, **kwargs: P.kwargs)-Funktion unterschiedliche Partitionen derselben Menge von Parametern ergeben. Daher müssen wir sicherstellen, dass diese speziellen Typen nur gemeinsam in die Welt gebracht und gemeinsam verwendet werden, damit unsere Verwendung für alle möglichen Partitionen gültig ist.

def puts_p_into_scope(f: Callable[P, int]) -> None:

  stored_args: P.args                           # Rejected

  stored_kwargs: P.kwargs                       # Rejected

  def just_args(*args: P.args) -> None:         # Rejected
    pass

  def just_kwargs(**kwargs: P.kwargs) -> None:  # Rejected
    pass

Semantik

Mit diesen Anforderungen können wir nun die einzigartigen Eigenschaften nutzen, die uns diese Konfiguration bietet

• Innerhalb der Funktion hat args den Typ P.args, nicht Tuple[P.args, ...], wie es bei einer normalen Annotation der Fall wäre (und ebenso mit den **kwargs)
  • Dieser Sonderfall ist notwendig, um die heterogenen Inhalte der args/kwargs eines bestimmten Aufrufs zu kapseln, was nicht durch einen unbestimmten Tupel-/Dictionary-Typ ausgedrückt werden kann.
• Eine Funktion vom Typ Callable[P, R] kann mit (*args, **kwargs) aufgerufen werden, wenn und nur wenn args den Typ P.args und kwargs den Typ P.kwargs hat und diese Typen beide von derselben Funktionsdeklaration stammen.
• Eine Funktion, die als def inner(*args: P.args, **kwargs: P.kwargs) -> X deklariert ist, hat den Typ Callable[P, X].

Mit diesen drei Eigenschaften haben wir nun die Möglichkeit, parametererhaltende Dekoratoren vollständig zu typisieren.

def decorator(f: Callable[P, int]) -> Callable[P, None]:

  def foo(*args: P.args, **kwargs: P.kwargs) -> None:

    f(*args, **kwargs)    # Accepted, should resolve to int

    f(*kwargs, **args)    # Rejected

    f(1, *args, **kwargs) # Rejected

  return foo              # Accepted

Um dies auf Concatenate auszudehnen, deklarieren wir die folgenden Eigenschaften

• Eine Funktion vom Typ Callable[Concatenate[A, B, P], R] kann nur mit (a, b, *args, **kwargs) aufgerufen werden, wenn args und kwargs die jeweiligen Komponenten von P sind, a vom Typ A und b vom Typ B ist.
• Eine Funktion, die als def inner(a: A, b: B, *args: P.args, **kwargs: P.kwargs) -> R deklariert ist, hat den Typ Callable[Concatenate[A, B, P], R]. Das Platzieren von nur-Schlüsselwortparametern zwischen *args und **kwargs ist verboten.

def add(f: Callable[P, int]) -> Callable[Concatenate[str, P], None]:

  def foo(s: str, *args: P.args, **kwargs: P.kwargs) -> None:  # Accepted
    pass

  def bar(*args: P.args, s: str, **kwargs: P.kwargs) -> None:  # Rejected
    pass

  return foo                                                   # Accepted


def remove(f: Callable[Concatenate[int, P], int]) -> Callable[P, None]:

  def foo(*args: P.args, **kwargs: P.kwargs) -> None:
    f(1, *args, **kwargs) # Accepted

    f(*args, 1, **kwargs) # Rejected

    f(*args, **kwargs)    # Rejected

  return foo

Beachten Sie, dass die Namen der Parameter, die den ParamSpec-Komponenten vorausgehen, nicht in der resultierenden Concatenate erwähnt werden. Das bedeutet, dass diese Parameter nicht über ein benanntes Argument angesprochen werden können

def outer(f: Callable[P, None]) -> Callable[P, None]:
  def foo(x: int, *args: P.args, **kwargs: P.kwargs) -> None:
    f(*args, **kwargs)

  def bar(*args: P.args, **kwargs: P.kwargs) -> None:
    foo(1, *args, **kwargs)   # Accepted
    foo(x=1, *args, **kwargs) # Rejected

  return bar

Dies ist keine Implementierungsgconvenienz, sondern eine Anforderung an die Fehlerfreiheit. Wenn wir den zweiten Aufrufstil zulassen würden, wäre der folgende Ausschnitt problematisch.

@outer
def problem(*, x: object) -> None:
  pass

problem(x="uh-oh")

Innerhalb von bar würden wir TypeError: foo() got multiple values for argument 'x' erhalten. Das Erzwingen, dass diese verketteten Argumente positionsabhängig angesprochen werden, vermeidet diese Art von Problemen und vereinfacht die Syntax zur Darstellung dieser Typen. Beachten Sie, dass dies auch der Grund ist, warum wir Signaturen der Form (*args: P.args, s: str, **kwargs: P.kwargs) ablehnen müssen (siehe Verketten von Schlüsselwortparametern für weitere Details).

Wenn einer dieser vorangestellten Positionsargumente einen freien ParamSpec enthält, betrachten wir diese Variable für die Zwecke der Extraktion der Komponenten dieses ParamSpec als im Gültigkeitsbereich. Das erlaubt uns, Dinge wie diese zu schreiben

def twice(f: Callable[P, int], *args: P.args, **kwargs: P.kwargs) -> int:
  return f(*args, **kwargs) + f(*args, **kwargs)

Der Typ von twice im obigen Beispiel ist Callable[Concatenate[Callable[P, int], P], int], wobei P durch das äußere Callable gebunden ist. Dies hat die folgende Semantik

def a_int_b_str(a: int, b: str) -> int:
  pass

twice(a_int_b_str, 1, "A")       # Accepted

twice(a_int_b_str, b="A", a=1)   # Accepted

twice(a_int_b_str, "A", 1)       # Rejected