spec: do not mandate inference details around TypeVarTuple (#2203)

JelleZijlstra · web-flow · commit 56ffa795fe78 · 2026-04-02T11:19:37.000-07:00
I don't think this case should error; a type checker can solve Ts
to something like (object,) or (int | str,). This is not all that
different from the first call to func4(), where the two calls with (0,)
and (1,) lead to Ts being solved to a common supertype.
diff --git a/conformance/results/mypy/generics_typevartuple_args.toml b/conformance/results/mypy/generics_typevartuple_args.toml
@@ -1,6 +1,6 @@
 conformant = "Partial"
 notes = """
-Does not enforce that tuples captured by TypeVarTuple are same type.
+Does not enforce that tuples captured by TypeVarTuple are of the same length.
 """
 output = """
 generics_typevartuple_args.py:33: error: Argument 3 to "exec_le" has incompatible type "str"; expected "Env"  [arg-type]
@@ -15,5 +15,4 @@ generics_typevartuple_args.py:67: error: Too few arguments for "func3"  [call-ar
 conformance_automated = "Fail"
 errors_diff = """
 Line 75: Expected 1 errors
-Line 76: Expected 1 errors
 """
diff --git a/conformance/results/mypy/generics_typevartuple_basic.toml b/conformance/results/mypy/generics_typevartuple_basic.toml
@@ -1,7 +1,6 @@
 conformant = "Partial"
 notes = """
 Does not enforce that tuples captured by TypeVarTuple are same length.
-Does not enforce that tuples captured by TypeVarTuple are same type.
 """
 output = """
 generics_typevartuple_basic.py:42: error: Argument 1 to "Array" has incompatible type "Height"; expected "tuple[Height, Width]"  [arg-type]
@@ -10,7 +9,6 @@ generics_typevartuple_basic.py:45: error: Argument 1 to "Array" has incompatible
 generics_typevartuple_basic.py:52: error: Free type variable expected in Generic[...]  [misc]
 generics_typevartuple_basic.py:53: error: TypeVarTuple "Shape" is only valid with an unpack  [valid-type]
 generics_typevartuple_basic.py:56: error: TypeVarTuple "Shape" is only valid with an unpack  [valid-type]
-generics_typevartuple_basic.py:57: error: Incompatible return value type (got "tuple[*Shape]", expected "tuple[Any]")  [return-value]
 generics_typevartuple_basic.py:59: error: TypeVarTuple "Shape" is only valid with an unpack  [valid-type]
 generics_typevartuple_basic.py:65: error: Unexpected keyword argument "covariant" for "TypeVarTuple"  [misc]
 generics_typevartuple_basic.py:66: error: Too many positional arguments for "TypeVarTuple"  [misc]
@@ -21,7 +19,5 @@ generics_typevartuple_basic.py:106: error: Can only use one type var tuple in a
 """
 conformance_automated = "Fail"
 errors_diff = """
-Line 89: Expected 1 errors
 Line 90: Expected 1 errors
-Line 57: Unexpected errors ['generics_typevartuple_basic.py:57: error: Incompatible return value type (got "tuple[*Shape]", expected "tuple[Any]")  [return-value]']
 """
diff --git a/conformance/results/pyrefly/generics_typevartuple_args.toml b/conformance/results/pyrefly/generics_typevartuple_args.toml
@@ -1,6 +1,10 @@
-conformant = "Pass"
-conformance_automated = "Pass"
+conformant = "Partial"
+conformance_automated = "Fail"
+notes = """
+Does not correctly solve TypeVarTuple with heterogeneous bounds.
+"""
 errors_diff = """
+Line 76: Unexpected errors ["Argument `tuple[Literal['1']]` is not assignable to parameter `*args` with type `tuple[int]` in function `func4` [bad-argument-type]"]
 """
 output = """
 ERROR generics_typevartuple_args.py:33:12-23: Unpacked argument `tuple[Literal[0], Literal['']]` is not assignable to parameter `*args` with type `tuple[*@_, Env]` in function `exec_le` [bad-argument-type]
diff --git a/conformance/results/pyrefly/generics_typevartuple_basic.toml b/conformance/results/pyrefly/generics_typevartuple_basic.toml
@@ -1,10 +1,11 @@
 conformant = "Partial"
 notes = """
-TypeVarTuple is pinned too early when calling generic function
+TypeVarTuple is pinned too early when calling generic function.
 """
 conformance_automated = "Fail"
 errors_diff = """
 Line 85: Unexpected errors ['Argument `tuple[float]` is not assignable to parameter `arg2` with type `tuple[int]` in function `func2` [bad-argument-type]']
+Line 89: Unexpected errors ["Argument `tuple[Literal['0']]` is not assignable to parameter `arg2` with type `tuple[int]` in function `func2` [bad-argument-type]"]
 """
 output = """
 ERROR generics_typevartuple_basic.py:42:34-43: Argument `Height` is not assignable to parameter `shape` with type `tuple[Height, Width]` in function `Array.__init__` [bad-argument-type]
diff --git a/conformance/results/pyright/generics_typevartuple_args.toml b/conformance/results/pyright/generics_typevartuple_args.toml
@@ -1,4 +1,11 @@
-conformant = "Pass"
+conformant = "Partial"
+notes = """
+Does not correctly solve TypeVarTuple with heterogeneous bounds.
+"""
+conformance_automated = "Fail"
+errors_diff = """
+Line 76: Unexpected errors ['generics_typevartuple_args.py:76:14 - error: Argument of type "tuple[Literal[\\'1\\']]" cannot be assigned to parameter "args" of type "tuple[*Ts@func4]" in function "func4"']
+"""
 output = """
 generics_typevartuple_args.py:33:20 - error: Argument of type "Literal['']" cannot be assigned to parameter of type "Env" in function "exec_le"
   "Literal['']" is not assignable to "Env" (reportArgumentType)
@@ -17,6 +24,3 @@ generics_typevartuple_args.py:75:13 - error: Argument of type "tuple[Literal[1],
 generics_typevartuple_args.py:76:14 - error: Argument of type "tuple[Literal['1']]" cannot be assigned to parameter "args" of type "tuple[*Ts@func4]" in function "func4"
   "Literal['1']" is not assignable to "int" (reportArgumentType)
 """
-conformance_automated = "Pass"
-errors_diff = """
-"""
diff --git a/conformance/results/pyright/generics_typevartuple_basic.toml b/conformance/results/pyright/generics_typevartuple_basic.toml
@@ -1,4 +1,11 @@
-conformant = "Pass"
+conformant = "Partial"
+notes = """
+Does not correctly solve TypeVarTuple with heterogeneous bounds.
+"""
+conformance_automated = "Fail"
+errors_diff = """
+Line 89: Unexpected errors ['generics_typevartuple_basic.py:89:14 - error: Argument of type "tuple[Literal[\\'0\\']]" cannot be assigned to parameter "arg2" of type "tuple[*Ts@func2]" in function "func2"']
+"""
 output = """
 generics_typevartuple_basic.py:42:34 - error: Argument of type "Height" cannot be assigned to parameter "shape" of type "tuple[*Shape@Array]" in function "__init__"
   "Height" is not assignable to "tuple[*Shape@Array]" (reportArgumentType)
@@ -30,6 +37,3 @@ generics_typevartuple_basic.py:100:17 - error: Argument of type "Array[Height, W
 generics_typevartuple_basic.py:106:14 - error: Generic class can have at most one TypeVarTuple type parameter but received multiple ("Ts1", "Ts2") (reportGeneralTypeIssues)
 generics_typevartuple_basic.py:106:29 - error: Type argument list can have at most one unpacked TypeVarTuple or tuple (reportInvalidTypeForm)
 """
-conformance_automated = "Pass"
-errors_diff = """
-"""
diff --git a/conformance/results/results.html b/conformance/results/results.html
@@ -413,17 +413,17 @@ <h3>Python Type System Conformance Test Results</h3>
 <th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not reject access of generic instance variable from the class object.</p></span></div></th>
 </tr>
 <tr><th class="column col1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;generics_typevartuple_args</th>
-<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not enforce that tuples captured by TypeVarTuple are same type.</p></span></div></th>
-<th class="column col2 conformant">Pass</th>
-<th class="column col2 conformant">Pass</th>
-<th class="column col2 conformant">Pass</th>
+<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not enforce that tuples captured by TypeVarTuple are of the same length.</p></span></div></th>
+<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not correctly solve TypeVarTuple with heterogeneous bounds.</p></span></div></th>
+<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not correctly solve TypeVarTuple with heterogeneous bounds.</p></span></div></th>
+<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not correctly solve TypeVarTuple with heterogeneous bounds.</p></span></div></th>
 <th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Supports PEP-646 unpacked tuples but not TypeVarTuple.</p></span></div></th>
 </tr>
 <tr><th class="column col1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;generics_typevartuple_basic</th>
-<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not enforce that tuples captured by TypeVarTuple are same length.</p><p>Does not enforce that tuples captured by TypeVarTuple are same type.</p></span></div></th>
-<th class="column col2 conformant">Pass</th>
-<th class="column col2 conformant">Pass</th>
-<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>TypeVarTuple is pinned too early when calling generic function</p></span></div></th>
+<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not enforce that tuples captured by TypeVarTuple are same length.</p></span></div></th>
+<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not correctly solve TypeVarTuple with heterogeneous bounds.</p></span></div></th>
+<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>Does not correctly solve TypeVarTuple with heterogeneous bounds.</p></span></div></th>
+<th class="column col2 partially-conformant"><div class="hover-text">Partial<span class="tooltip-text" id="bottom"><p>TypeVarTuple is pinned too early when calling generic function.</p></span></div></th>
 <th class="column col2 not-conformant">Unsupported</th>
 </tr>
 <tr><th class="column col1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;generics_typevartuple_callable</th>
diff --git a/conformance/results/ty/generics_typevartuple_args.toml b/conformance/results/ty/generics_typevartuple_args.toml
@@ -12,7 +12,6 @@ Line 58: Expected 1 errors
 Line 59: Expected 1 errors
 Line 67: Expected 1 errors
 Line 75: Expected 1 errors
-Line 76: Expected 1 errors
 Line 29: Unexpected errors ['generics_typevartuple_args.py:29:5: error[type-assertion-failure] Type `tuple[@Todo(TypeVarTuple), ...]` does not match asserted type `tuple[int, str]`']
 Line 31: Unexpected errors ['generics_typevartuple_args.py:31:5: error[type-assertion-failure] Type `tuple[@Todo(TypeVarTuple), ...]` does not match asserted type `tuple[()]`']
 Line 32: Unexpected errors ['generics_typevartuple_args.py:32:5: error[type-assertion-failure] Type `tuple[@Todo(TypeVarTuple), ...]` does not match asserted type `tuple[int, str]`']
diff --git a/conformance/results/ty/generics_typevartuple_basic.toml b/conformance/results/ty/generics_typevartuple_basic.toml
@@ -5,7 +5,6 @@ Line 43: Expected 1 errors
 Line 53: Expected 1 errors
 Line 56: Expected 1 errors
 Line 59: Expected 1 errors
-Line 89: Expected 1 errors
 Line 90: Expected 1 errors
 Line 99: Expected 1 errors
 Line 100: Expected 1 errors
diff --git a/conformance/results/zuban/generics_typevartuple_args.toml b/conformance/results/zuban/generics_typevartuple_args.toml
@@ -1,5 +1,10 @@
-conformance_automated = "Pass"
+conformant = "Partial"
+notes = """
+Does not correctly solve TypeVarTuple with heterogeneous bounds.
+"""
+conformance_automated = "Fail"
 errors_diff = """
+Line 76: Unexpected errors ['generics_typevartuple_args.py:76: error: Argument 2 to "func4" has incompatible type "tuple[Literal[\\'1\\']]"; expected "tuple[int]"  [arg-type]']
 """
 output = """
 generics_typevartuple_args.py:33: error: Argument 3 to "exec_le" has incompatible type "str"; expected "Env"  [arg-type]
diff --git a/conformance/results/zuban/generics_typevartuple_basic.toml b/conformance/results/zuban/generics_typevartuple_basic.toml
@@ -1,5 +1,10 @@
-conformance_automated = "Pass"
+conformant = "Partial"
+notes = """
+Does not correctly solve TypeVarTuple with heterogeneous bounds.
+"""
+conformance_automated = "Fail"
 errors_diff = """
+Line 89: Unexpected errors ['generics_typevartuple_basic.py:89: error: Argument 2 to "func2" has incompatible type "tuple[Literal[\\'0\\']]"; expected "tuple[int]"  [arg-type]']
 """
 output = """
 generics_typevartuple_basic.py:42: error: Argument 1 to "Array" has incompatible type "Height"; expected "tuple[Height, Width]"  [arg-type]
diff --git a/conformance/tests/generics_typevartuple_args.py b/conformance/tests/generics_typevartuple_args.py
@@ -21,7 +21,7 @@ class Env:
     ...
 
 
-def exec_le(path: str, *args: * tuple[*Ts, Env], env: Env | None = None) -> tuple[*Ts]:
+def exec_le(path: str, *args: *tuple[*Ts, Env], env: Env | None = None) -> tuple[*Ts]:
     raise NotImplementedError
 
 
@@ -39,7 +39,7 @@ def has_int_and_str(x: int, y: str):
 # > *args: int, which accepts zero or more values of type int.
 
 
-def func1(*args: * tuple[int, ...]) -> None:
+def func1(*args: *tuple[int, ...]) -> None:
     ...
 
 
@@ -48,7 +48,7 @@ def func1(*args: * tuple[int, ...]) -> None:
 func1(1, "2", 3)  # E
 
 
-def func2(*args: * tuple[int, *tuple[str, ...], str]) -> None:
+def func2(*args: *tuple[int, *tuple[str, ...], str]) -> None:
     ...
 
 
@@ -59,7 +59,7 @@ def func2(*args: * tuple[int, *tuple[str, ...], str]) -> None:
 func2("")  # E
 
 
-def func3(*args: * tuple[int, str]) -> None:
+def func3(*args: *tuple[int, str]) -> None:
     ...
 
 
@@ -72,8 +72,8 @@ def func4(*args: tuple[*Ts]):
 
 
 func4((0,), (1,))  # OK
-func4((0,), (1, 2))  # E
-func4((0,), ("1",))  # E
+func4((0,), (1, 2))  # E (length mismatch)
+func4((0,), ("1",))  # OK
 
 
 # This is a syntax error, so leave it commented out.
diff --git a/conformance/tests/generics_typevartuple_basic.py b/conformance/tests/generics_typevartuple_basic.py
@@ -54,7 +54,7 @@ def __init__(self, shape: tuple[Shape]):  # E: not unpacked
         self._shape: tuple[*Shape] = shape
 
     def get_shape(self) -> tuple[Shape]:  # E: not unpacked
-        return self._shape
+        raise NotImplementedError
 
     def method1(*args: Shape) -> None:  # E: not unpacked
         ...
@@ -86,7 +86,7 @@ def func2(arg1: tuple[*Ts], arg2: tuple[*Ts]) -> tuple[*Ts]:
 func2((0.0,), (0,))  # OK
 func2((0,), (1,))  # OK
 
-func2((0,), ("0",))  # E
+func2((0,), ("0",))  # OK
 func2((0, 0), (0,))  # E
 
 
diff --git a/docs/spec/generics.rst b/docs/spec/generics.rst
@@ -1189,51 +1189,34 @@ for two reasons:
 * To improve readability: the star also functions as an explicit visual
   indicator that the type variable tuple is not a normal type variable.
 
-Variance, Type Constraints and Type Bounds: Not (Yet) Supported
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Variance, Type Constraints and Type Bounds: Not Supported
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-``TypeVarTuple`` does not yet support specification of:
+``TypeVarTuple`` does not currently support specification of:
 
 * Variance (e.g. ``TypeVar('T', covariant=True)``)
 * Type constraints (``TypeVar('T', int, float)``)
 * Type bounds (``TypeVar('T', bound=ParentClass)``)
 
-We leave the decision of how these arguments should behave to a future PEP, when variadic generics have been tested in the field. As of PEP 646, type variable tuples are
-invariant.
-
 Type Variable Tuple Equality
 """"""""""""""""""""""""""""
 
 If the same ``TypeVarTuple`` instance is used in multiple places in a signature
-or class, a valid type inference might be to bind the ``TypeVarTuple`` to
-a ``tuple`` of a union of types:
+or class, type checkers may use the same rules for solving the variables as they
+would for normal ``TypeVar``\ s. The exact inference behavior is not specified.
 
 ::
 
-  def foo(arg1: tuple[*Ts], arg2: tuple[*Ts]): ...
+  def foo(arg1: tuple[*Ts], arg2: tuple[*Ts]) -> tuple[*Ts]: ...
 
   a = (0,)
   b = ('0',)
-  foo(a, b)  # Can Ts be bound to tuple[int | str]?
-
-We do *not* allow this; type unions may *not* appear within the ``tuple``.
-If a type variable tuple appears in multiple places in a signature,
-the types must match exactly (the list of type parameters must be the same
-length, and the type parameters themselves must be identical):
+  reveal_type(foo(a, b))  # May be e.g. tuple[object], tuple[int | str], tuple[Literal[0, "0"]]
 
-::
+All usages of the ``TypeVarTuple`` must match in length, however::
 
-  def pointwise_multiply(
-      x: Array[*Shape],
-      y: Array[*Shape]
-  ) -> Array[*Shape]: ...
+  foo((1,), (2, 3))  # Error: Expected a tuple of length 1 for arg2, but got a tuple of length 2.
 
-  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
 
 Multiple Type Variable Tuples: Not Allowed
 """"""""""""""""""""""""""""""""""""""""""
