Files
Carl Meyer 017c77fcf1 [ty] Use # ok comments in mdtests (#29856)
Use `# ok` as the marker for mdtest statements whose expectation is that
no diagnostic is emitted. Update the guidance in `AGENTS.md` and replace
existing `# no diagnostic` comments in Ruff and ty mdtests.
2026-10-30 20:53:21 -07:00

70 KiB
Raw Permalink Blame History

Call expression

Simple

def get_int() -> int:
    return 42

reveal_type(get_int())  # revealed: int

Gradual variadic parameters

from typing import Any, TypeVar

T = TypeVar("T")

def accepts_anything(first: int, *args: Any, **kwargs: Any) -> None: ...
def accepts_only_gradual(*args: Any, **kwargs: Any) -> None: ...
def preserves_first(first: T, *args: Any, **kwargs: Any) -> T:
    return first

accepts_anything(1, "one", object(), keyword=object())
accepts_anything("not an int")  # error: [invalid-argument-type]
accepts_only_gradual(1, "one", keyword=object())
accepts_only_gradual(**{1: "one"})  # error: [invalid-argument-type]

reveal_type(preserves_first(1, "other", keyword=object()))  # revealed: Literal[1]

Object variadic parameters

*args: object and **kwargs: object can receive many unrelated argument types. Call binding should not build large unions to remember the exact values that were supplied to these broad sinks.

class C0: ...
class C1: ...
class C2: ...
class C3: ...
class C4: ...
class C5: ...
class C6: ...
class C7: ...
class C8: ...
class C9: ...

def accepts_objects(*args: object, **kwargs: object) -> None: ...

accepts_objects(
    C0(),
    C1(),
    C2(),
    C3(),
    C4(),
    C5(),
    C6(),
    C7(),
    C8(),
    C9(),
    k0=C0(),
    k1=C1(),
    k2=C2(),
    k3=C3(),
    k4=C4(),
    k5=C5(),
    k6=C6(),
    k7=C7(),
    k8=C8(),
    k9=C9(),
)

Async

async def get_int_async() -> int:
    return 42

reveal_type(get_int_async())  # revealed: CoroutineType[Any, Any, int]

Generic

[environment]
python-version = "3.12"
def get_int[T]() -> int:
    return 42

reveal_type(get_int())  # revealed: int

Generic call with independent and dependent arguments

Concrete arguments must not erase a type variable inferred from another argument.

[environment]
python-version = "3.12"
from __future__ import annotations

class Invariant[T]:
    item: T

class Bounded[T: int]:
    item: T

def combine[A, B, U](first: Invariant[A], second: Invariant[B], dependent: Invariant[U]) -> tuple[A, B, U]:
    raise NotImplementedError

class Constructed[T]:
    def __new__[A, B, U](cls, first: Invariant[A], second: Invariant[B], dependent: Invariant[U]) -> Constructed[tuple[A, B, U]]:
        raise NotImplementedError

def infer[T](dependent: Invariant[T]) -> None:
    concrete = Invariant[int]()
    reveal_type(combine(concrete, concrete, dependent))  # revealed: tuple[int, int, T@infer]
    reveal_type(Constructed(concrete, concrete, dependent))  # revealed: Constructed[tuple[int, int, T@infer]]

    bounded = Invariant[Bounded[int]]()
    reveal_type(combine(bounded, bounded, dependent))  # revealed: tuple[Bounded[int], Bounded[int], T@infer]
    reveal_type(Constructed(bounded, bounded, dependent))  # revealed: Constructed[tuple[Bounded[int], Bounded[int], T@infer]]

Generic callable chains

Inferring a chain of generic callable parameters should discard internal typevar artifacts from transitive constraints instead of expanding them recursively.

from typing import Callable, TypeVar

_A = TypeVar("_A")
_B = TypeVar("_B")
_C = TypeVar("_C")
_D = TypeVar("_D")
_E = TypeVar("_E")
_F = TypeVar("_F")
_G = TypeVar("_G")
_H = TypeVar("_H")

def compose(
    fn1: Callable[[_A], _B],
    fn2: Callable[[_B], _C],
    fn3: Callable[[_C], _D],
    fn4: Callable[[_D], _E],
    fn5: Callable[[_E], _F],
    fn6: Callable[[_F], _G],
    fn7: Callable[[_G], _H],
) -> Callable[[_A], _H]:
    raise NotImplementedError

Func = Callable[[int], int]
fn: Func = lambda x: x + 42

cn = compose(fn, fn, fn, fn, fn, fn, fn)
reveal_type(cn)  # revealed: (int, /) -> int

Recursive callable constraints in constructors

When inferring the generic constructor for map, an overloaded callable together with a gradual iterable can produce expanding recursive constraints. We should fall back rather than repeatedly substituting those constraints.

import operator
from typing import Any

ints: list[int] = []
dynamic: Any = []

reveal_type(map(operator.add, ints, dynamic))  # revealed: map[Unknown]

Generic overloaded callable constraints in constructors

An overloaded callback can have a type variable of its own. An overload rejected by the constructor must not leave a mapping for that variable that causes the accepted overload to be rejected.

from typing import Generic, TypeVar, overload

T = TypeVar("T", str, bytes)

class Result(Generic[T]): ...

@overload
def convert(value: T) -> Result[T]: ...
@overload
def convert(value: Result[T]) -> Result[T]: ...
def convert(value: T | Result[T]) -> Result[T]:
    raise NotImplementedError

# TODO: Preserve correlated overloaded-callback solutions (astral-sh/ty#2799) to infer
# `map[Result[str]]`.
reveal_type(map(convert, ["a"]))  # revealed: map[Unknown]

Decorated

from typing import Callable

def foo() -> int:
    return 42

def decorator(func) -> Callable[[], int]:
    return foo

@decorator
def bar() -> str:
    return "bar"

reveal_type(bar())  # revealed: int

Invalid callable

nonsense = 123
x = nonsense()  # error: "Object of type `Literal[123]` is not callable"

Potentially unbound function

def _(flag: bool):
    if flag:
        def foo() -> int:
            return 42
    # error: [possibly-unresolved-reference]
    reveal_type(foo())  # revealed: int

PEP-484 convention for positional-only parameters

PEP 570, introduced in Python 3.8, added dedicated Python syntax for denoting positional-only parameters (the / in a function signature). However, functions implemented in C were able to have positional-only parameters prior to Python 3.8 (there was just no syntax for expressing this at the Python level).

Stub files describing functions implemented in C nonetheless needed a way of expressing that certain parameters were positional-only. In the absence of dedicated Python syntax, PEP 484 described a convention that type checkers were expected to understand:

Some functions are designed to take their arguments only positionally, and expect their callers never to use the argument’s name to provide that argument by keyword. All arguments with names beginning with __ are assumed to be positional-only, except if their names also end with __.

While this convention is now redundant (following the implementation of PEP 570), many projects still continue to use the old convention, so it is supported by ty as well.

def f(__x: int): ...

f(1)
# error: [positional-only-parameter-as-kwarg]
f(__x=1)

But not if they follow a non-positional-only parameter. When enabled, invalid-legacy-positional-parameter flags this as an incorrect use of the legacy convention:

from typing import overload

# error: [invalid-legacy-positional-parameter]
def g(x: int, __y: str): ...

g(x=1, __y="foo")

# The earlier `g` definition is shadowed here,
# but we still emit a diagnostic on the earlier definition
def g(): ...

Because the lint is a syntactic check, we emit it for each overload if multiple overloads violate the lint:

import tkinter
from typing import Callable, TypeVar, Any

@overload
def g2(x: int, __y: str): ...  # error: [invalid-legacy-positional-parameter]
@overload
def g2(x: str, __y: int): ...  # error: [invalid-legacy-positional-parameter]
def g2(x: str | int, __y: int | str): ...  # error: [invalid-legacy-positional-parameter]

T = TypeVar("T")

def copy_type(f: T) -> Callable[[Any], T]:
    return lambda x: x

# Naively iterating over the overloads using `.iter_overloads_and_implementation()` and/or
# using `.signature()` would cause us to panic on this function, because the overloads
# of this function's public signature are defined in `stdlib/tkinter/__init__.pyi` due to
# the decorator.
@copy_type(tkinter.Text.__init__)
def g3(x, *args: Any, **kwargs: Any) -> None: ...
def new_signature(): ...

# The check is able to "see through" the decorators and examines the original function's
# signature:
@copy_type(new_signature)
def g4(a, __b): ...  # error: [invalid-legacy-positional-parameter]

Parameters are also not understood as positional-only if they both start and end with __:

def h(__x__: str): ...

h(__x__="foo")

And if any parameters use the new PEP-570 convention, the old convention does not apply:

def i(x: str, /, __y: int): ...

i("foo", __y=42)  # fine

And self/cls are implicitly positional-only:

class C:
    def method(self, __x: int): ...
    @classmethod
    def class_method(cls, __x: str): ...
    # (the name of the first parameter is irrelevant;
    # a staticmethod works the same as a free function in the global scope)
    @staticmethod
    def static_method(self, __x: int): ...  # error: [invalid-legacy-positional-parameter]
    # `__new__` is a staticmethod, but the `cls` parameter works in the same way as the `cls`
    # parameter in a classmethod, and is always passed positionally at runtime,
    # We therefore understand both `cls` and `__x` here as positional-only; we do not
    # emit `[invalid-legacy-positional-parameter]` on the method.
    def __new__(cls, __x: int):
        return super().__new__(cls)

# error: [positional-only-parameter-as-kwarg]
C(42).method(__x=1)
# error: [positional-only-parameter-as-kwarg]
C.class_method(__x="1")
C.static_method("x", __x=42)  # fine

Splatted arguments

Unknown argument length

def takes_zero() -> None: ...
def takes_one(x: int) -> None: ...
def takes_two(x: int, y: int) -> None: ...
def takes_two_positional_only(x: int, y: int, /) -> None: ...
def takes_two_different(x: int, y: str) -> None: ...
def takes_two_different_positional_only(x: int, y: str, /) -> None: ...
def takes_at_least_zero(*args) -> None: ...
def takes_at_least_one(x: int, *args) -> None: ...
def takes_at_least_two(x: int, y: int, *args) -> None: ...
def takes_at_least_two_positional_only(x: int, y: int, /, *args) -> None: ...

# Test all of the above with a number of different splatted argument types

def _(args: list[int]) -> None:
    takes_zero(*args)
    takes_one(*args)
    takes_two(*args)
    takes_two(*b"ab")
    takes_two(*b"abc")  # error: [too-many-positional-arguments]
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

def _(args: tuple[int, ...]) -> None:
    takes_zero(*args)
    takes_one(*args)
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

Fixed-length tuple argument

def takes_zero() -> None: ...
def takes_one(x: int) -> None: ...
def takes_two(x: int, y: int) -> None: ...
def takes_two_positional_only(x: int, y: int, /) -> None: ...
def takes_two_different(x: int, y: str) -> None: ...
def takes_two_different_positional_only(x: int, y: str, /) -> None: ...
def takes_at_least_zero(*args) -> None: ...
def takes_at_least_one(x: int, *args) -> None: ...
def takes_at_least_two(x: int, y: int, *args) -> None: ...
def takes_at_least_two_positional_only(x: int, y: int, /, *args) -> None: ...

# Test all of the above with a number of different splatted argument types

def _(args: tuple[int]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)
    takes_two(*args)  # error: [missing-argument]
    takes_two_positional_only(*args)  # error: [missing-argument]
    takes_two_different(*args)  # error: [missing-argument]
    takes_two_different_positional_only(*args)  # error: [missing-argument]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)  # error: [missing-argument]
    takes_at_least_two_positional_only(*args)  # error: [missing-argument]

def _(args: tuple[int, int]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)  # error: [too-many-positional-arguments]
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

def _(args: tuple[int, str]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)  # error: [too-many-positional-arguments]
    takes_two(*args)  # error: [invalid-argument-type]
    takes_two_positional_only(*args)  # error: [invalid-argument-type]
    takes_two_different(*args)
    takes_two_different_positional_only(*args)
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)  # error: [invalid-argument-type]
    takes_at_least_two_positional_only(*args)  # error: [invalid-argument-type]

Excess elements in unpacked tuples

The diagnostic counts every element, including those after the first excess argument.

def pair(x: int, y: str) -> None: ...

pair(*(1, "two", 3, 4))  # error: [too-many-positional-arguments] "expected 2, got 4"

Literal promotion in unpacked tuples

Call unpacking uses the tuple's inferred element types. Tuples with more than 64 elements promote integer literals to int, so only the shorter tuple can satisfy Literal[0].

from typing import Literal

def first_zero(first: Literal[0], *rest: int) -> None: ...

# fmt: off
first_zero(*(
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
))

# error: [invalid-argument-type]
first_zero(*(
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0, 0, 0, 0, 0, 0, 0, 0,
    0,
))
# fmt: on

Immediate list arguments

Unpacking a list constructed in the call preserves its exact length and each element's type. The list's homogeneous element type does not describe these argument positions precisely enough.

def pair(x: int, y: str) -> None: ...

pair(*[1, "two"])
pair(*[1], *["two"])

Missing arguments, extra arguments, and incompatible element types are rejected. These diagnostics currently highlight the call or unpacked list rather than individual list elements.

# snapshot: missing-argument
pair(*[])
error[missing-argument]: No arguments provided for required parameters `x`, `y` of function `pair`
 --> src/mdtest_snippet.py:6:1
  |
6 | pair(*[])
  | ^^^^^^^^^
info: Parameters declared here
 --> src/mdtest_snippet.py:1:9
  |
1 | def pair(x: int, y: str) -> None: ...
  |         ^^^^^^^^^^^^^^^^
# snapshot: missing-argument
pair(*[1])
error[missing-argument]: No argument provided for required parameter `y` of function `pair`
 --> src/mdtest_snippet.py:8:1
  |
8 | pair(*[1])
  | ^^^^^^^^^^
info: Parameter declared here
 --> src/mdtest_snippet.py:1:18
  |
1 | def pair(x: int, y: str) -> None: ...
  |                  ^^^^^^
# snapshot: too-many-positional-arguments
pair(*[1, "two", 3, 4])
error[too-many-positional-arguments]: Too many positional arguments to function `pair`: expected 2, got 4
  --> src/mdtest_snippet.py:10:6
   |
10 | pair(*[1, "two", 3, 4])
   |      ^^^^^^^^^^^^^^^^^
info: Function signature here
 --> src/mdtest_snippet.py:1:5
  |
1 | def pair(x: int, y: str) -> None: ...
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
# snapshot: invalid-argument-type
pair(*["one", "two"])
error[invalid-argument-type]: Argument to function `pair` is incorrect
  --> src/mdtest_snippet.py:12:6
   |
12 | pair(*["one", "two"])
   |      ^^^^^^^^^^^^^^^ Expected `int`, found `Literal["one"]`
info: Function defined here
 --> src/mdtest_snippet.py:1:5
  |
1 | def pair(x: int, y: str) -> None: ...
  |     ^^^^ ------ Parameter declared here

An exact positional unpack still supplies a parameter that also has an explicit keyword, whether that keyword precedes or follows the unpack in the source.

def f(x: int, *, y: int = 0) -> None: ...

f(x=1, *[2])  # error: [parameter-already-assigned]
f(*[2], x=1)  # error: [parameter-already-assigned]

Immediate dictionary arguments

A dictionary constructed directly in the call preserves each string key and its value type. A repeated key replaces the earlier value, as it does at runtime.

def pair(x: int, *, y: str) -> None: ...

pair(**{"y": "two", "x": 1})
pair(**{})  # error: [missing-argument]
pair(**{"y": "two"})  # error: [missing-argument]
pair(**{"x": "one", "x": 1, "y": "two"})
pair(**{"x": 1, "y": 2})  # error: [invalid-argument-type]
pair(x=1, **{"x": 2, "y": "two"})  # error: [parameter-already-assigned]
pair(**{"x": 1}, **{"x": 2, "y": "two"})  # error: [parameter-already-assigned]
pair(**{"z": 3, "x": 1, "y": "two"})  # error: [unknown-argument]

Aliased list arguments

Assigning a list literal to a variable loses the per-position types used for immediate unpacking. This call is valid at runtime, but ty currently reports errors because args has type list[int | str].

def pair(x: int, y: str) -> None: ...

args = [1, "two"]
# error: [invalid-argument-type]
# error: [invalid-argument-type]
pair(*args)

Mutated list arguments

After a list is mutated, its original literal contents may no longer describe the arguments. This call raises TypeError at runtime because clear() empties the list. ty does not report this error because it treats values as a variable-length list[int].

def pair(x: int, y: int) -> None: ...

values = [1]
values.clear()
pair(*values)

Subclass of fixed-length tuple argument

def takes_zero() -> None: ...
def takes_one(x: int) -> None: ...
def takes_two(x: int, y: int) -> None: ...
def takes_two_positional_only(x: int, y: int, /) -> None: ...
def takes_two_different(x: int, y: str) -> None: ...
def takes_two_different_positional_only(x: int, y: str, /) -> None: ...
def takes_at_least_zero(*args) -> None: ...
def takes_at_least_one(x: int, *args) -> None: ...
def takes_at_least_two(x: int, y: int, *args) -> None: ...
def takes_at_least_two_positional_only(x: int, y: int, /, *args) -> None: ...

# Test all of the above with a number of different splatted argument types

class SingleElementTuple(tuple[int]): ...

def _(args: SingleElementTuple) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]

    takes_one(*args)

    takes_two(*args)  # error: [missing-argument]
    takes_two_positional_only(*args)  # error: [missing-argument]

    takes_two_different(*args)  # error: [missing-argument]
    takes_two_different_positional_only(*args)  # error: [missing-argument]

    takes_at_least_zero(*args)
    takes_at_least_one(*args)

    takes_at_least_two(*args)  # error: [missing-argument]
    takes_at_least_two_positional_only(*args)  # error: [missing-argument]

class TwoElementIntTuple(tuple[int, int]): ...

def _(args: TwoElementIntTuple) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)  # error: [too-many-positional-arguments]
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

class IntStrTuple(tuple[int, str]): ...

def _(args: IntStrTuple) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]

    takes_one(*args)  # error: [too-many-positional-arguments]

    # error: [invalid-argument-type]
    takes_two(*args)
    # error: [invalid-argument-type]
    takes_two_positional_only(*args)

    takes_two_different(*args)
    takes_two_different_positional_only(*args)
    takes_at_least_zero(*args)
    takes_at_least_one(*args)

    # error: [invalid-argument-type]
    takes_at_least_two(*args)
    # error: [invalid-argument-type]
    takes_at_least_two_positional_only(*args)

Mixed tuple argument

[environment]
python-version = "3.11"
def takes_zero() -> None: ...
def takes_one(x: int) -> None: ...
def takes_two(x: int, y: int) -> None: ...
def takes_two_positional_only(x: int, y: int, /) -> None: ...
def takes_two_different(x: int, y: str) -> None: ...
def takes_two_different_positional_only(x: int, y: str, /) -> None: ...
def takes_at_least_zero(*args) -> None: ...
def takes_at_least_one(x: int, *args) -> None: ...
def takes_at_least_two(x: int, y: int, *args) -> None: ...
def takes_at_least_two_positional_only(x: int, y: int, /, *args) -> None: ...

# Test all of the above with a number of different splatted argument types

def _(args: tuple[int, *tuple[int, ...]]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

def _(args: tuple[int, *tuple[str, ...]]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)
    takes_two(*args)  # error: [invalid-argument-type]
    takes_two_positional_only(*args)  # error: [invalid-argument-type]
    takes_two_different(*args)
    takes_two_different_positional_only(*args)
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)  # error: [invalid-argument-type]
    takes_at_least_two_positional_only(*args)  # error: [invalid-argument-type]

def _(args: tuple[int, int, *tuple[int, ...]]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)  # error: [too-many-positional-arguments]
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

def _(args: tuple[int, int, *tuple[str, ...]]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)  # error: [too-many-positional-arguments]
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

def _(args: tuple[int, *tuple[int, ...], int]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)  # error: [too-many-positional-arguments]
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

def _(args: tuple[int, *tuple[str, ...], int]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)  # error: [too-many-positional-arguments]
    takes_two(*args)  # error: [invalid-argument-type]
    takes_two_positional_only(*args)  # error: [invalid-argument-type]
    takes_two_different(*args)
    takes_two_different_positional_only(*args)
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)  # error: [invalid-argument-type]
    takes_at_least_two_positional_only(*args)  # error: [invalid-argument-type]

Subclass of mixed tuple argument

[environment]
python-version = "3.11"
def takes_zero() -> None: ...
def takes_one(x: int) -> None: ...
def takes_two(x: int, y: int) -> None: ...
def takes_two_positional_only(x: int, y: int, /) -> None: ...
def takes_two_different(x: int, y: str) -> None: ...
def takes_two_different_positional_only(x: int, y: str, /) -> None: ...
def takes_at_least_zero(*args) -> None: ...
def takes_at_least_one(x: int, *args) -> None: ...
def takes_at_least_two(x: int, y: int, *args) -> None: ...
def takes_at_least_two_positional_only(x: int, y: int, /, *args) -> None: ...

# Test all of the above with a number of different splatted argument types

class IntStarInt(tuple[int, *tuple[int, ...]]): ...

def _(args: IntStarInt) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

class IntStarStr(tuple[int, *tuple[str, ...]]): ...

def _(args: IntStarStr) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]

    takes_one(*args)

    # error: [invalid-argument-type]
    takes_two(*args)
    # error: [invalid-argument-type]
    takes_two_positional_only(*args)

    takes_two_different(*args)
    takes_two_different_positional_only(*args)

    takes_at_least_zero(*args)

    takes_at_least_one(*args)

    # error: [invalid-argument-type]
    takes_at_least_two(*args)
    # error: [invalid-argument-type]
    takes_at_least_two_positional_only(*args)

class IntIntStarInt(tuple[int, int, *tuple[int, ...]]): ...

def _(args: IntIntStarInt) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)  # error: [too-many-positional-arguments]
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

class IntIntStarStr(tuple[int, int, *tuple[str, ...]]): ...

def _(args: IntIntStarStr) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]

    takes_one(*args)  # error: [too-many-positional-arguments]

    takes_two(*args)
    takes_two_positional_only(*args)

    # error: [invalid-argument-type]
    takes_two_different(*args)
    # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)

    takes_at_least_zero(*args)

    takes_at_least_one(*args)

    takes_at_least_two(*args)

    takes_at_least_two_positional_only(*args)

class IntStarIntInt(tuple[int, *tuple[int, ...], int]): ...

def _(args: IntStarIntInt) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)  # error: [too-many-positional-arguments]
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

class IntStarStrInt(tuple[int, *tuple[str, ...], int]): ...

def _(args: IntStarStrInt) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]

    takes_one(*args)  # error: [too-many-positional-arguments]

    # error: [invalid-argument-type]
    takes_two(*args)
    # error: [invalid-argument-type]
    takes_two_positional_only(*args)

    takes_two_different(*args)
    takes_two_different_positional_only(*args)

    takes_at_least_zero(*args)

    takes_at_least_one(*args)

    # error: [invalid-argument-type]
    takes_at_least_two(*args)

    # error: [invalid-argument-type]
    takes_at_least_two_positional_only(*args)

String argument

from typing import Literal

def takes_zero() -> None: ...
def takes_one(x: str) -> None: ...
def takes_two(x: str, y: str) -> None: ...
def takes_two_positional_only(x: str, y: str, /) -> None: ...
def takes_two_different(x: int, y: str) -> None: ...
def takes_two_different_positional_only(x: int, y: str, /) -> None: ...
def takes_at_least_zero(*args) -> None: ...
def takes_at_least_one(x: str, *args) -> None: ...
def takes_at_least_two(x: str, y: str, *args) -> None: ...
def takes_at_least_two_positional_only(x: str, y: str, /, *args) -> None: ...

# Test all of the above with a number of different splatted argument types

def _(args: Literal["a"]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)
    takes_two(*args)  # error: [missing-argument]
    takes_two_positional_only(*args)  # error: [missing-argument]
    # error: [invalid-argument-type]
    # error: [missing-argument]
    takes_two_different(*args)
    # error: [invalid-argument-type]
    # error: [missing-argument]
    takes_two_different_positional_only(*args)
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)  # error: [missing-argument]
    takes_at_least_two_positional_only(*args)  # error: [missing-argument]

def _(args: Literal["ab"]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)  # error: [too-many-positional-arguments]
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

def _(args: Literal["abc"]) -> None:
    takes_zero(*args)  # error: [too-many-positional-arguments]
    takes_one(*args)  # error: [too-many-positional-arguments]
    takes_two(*args)  # error: [too-many-positional-arguments]
    takes_two_positional_only(*args)  # error: [too-many-positional-arguments]
    # error: [invalid-argument-type]
    # error: [too-many-positional-arguments]
    takes_two_different(*args)
    # error: [invalid-argument-type]
    # error: [too-many-positional-arguments]
    takes_two_different_positional_only(*args)
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

def _(args: str) -> None:
    takes_zero(*args)
    takes_one(*args)
    takes_two(*args)
    takes_two_positional_only(*args)
    takes_two_different(*args)  # error: [invalid-argument-type]
    takes_two_different_positional_only(*args)  # error: [invalid-argument-type]
    takes_at_least_zero(*args)
    takes_at_least_one(*args)
    takes_at_least_two(*args)
    takes_at_least_two_positional_only(*args)

Wrong argument type

Positional argument, positional-or-keyword parameter

def f(x: int) -> int:
    return 1

# error: 15 [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `Literal["foo"]`"
reveal_type(f("foo"))  # revealed: int

Positional argument, positional-only parameter

def f(x: int, /) -> int:
    return 1

# error: 15 [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `Literal["foo"]`"
reveal_type(f("foo"))  # revealed: int

Positional argument, variadic parameter

def f(*args: int) -> int:
    return 1

# error: 15 [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `Literal["foo"]`"
reveal_type(f("foo"))  # revealed: int

Variadic argument, variadic parameter

[environment]
python-version = "3.11"
def f(*args: int) -> int:
    return 1

def _(args: list[str]) -> None:
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `str`"
    reveal_type(f(*args))  # revealed: int

Considering a few different shapes of tuple for the splatted argument:

def f1(*args: str): ...
def _(
    args1: tuple[str, ...],
    args2: tuple[str, *tuple[str, ...]],
    args3: tuple[str, *tuple[str, ...], str],
    args4: tuple[int, *tuple[str, ...]],
    args5: tuple[int, *tuple[str, ...], str],
    args6: tuple[*tuple[str, ...], str],
    args7: tuple[*tuple[str, ...], int],
    args8: tuple[int, *tuple[str, ...], int],
    args9: tuple[str, *tuple[str, ...], int],
    args10: tuple[str, *tuple[int, ...], str],
):
    f1(*args1)
    f1(*args2)
    f1(*args3)
    f1(*args4)  # error: [invalid-argument-type]
    f1(*args5)  # error: [invalid-argument-type]
    f1(*args6)
    f1(*args7)  # error: [invalid-argument-type]

    # Both fixed elements have the same incompatible type, so we report the error once.
    f1(*args8)  # error: [invalid-argument-type]

    f1(*args9)  # error: [invalid-argument-type]
    f1(*args10)  # error: [invalid-argument-type]

A union of heterogeneous tuples provided to a variadic parameter:

# Test inspired by ecosystem code at:
# - <https://github.com/home-assistant/core/blob/bde4eb50111a72f9717fe73ee5929e50eb06911b/homeassistant/components/lovelace/websocket.py#L50-L59>
# - <https://github.com/pydata/xarray/blob/3572f4e70f2b12ef9935c1f8c3c1b74045d2a092/xarray/tests/test_groupby.py#L3058-L3059>

def f2(a: str, b: bool): ...
def f3(coinflip: bool):
    if coinflip:
        args = "foo", True
    else:
        args = "bar", False

    # revealed: tuple[Literal["foo"], Literal[True]] | tuple[Literal["bar"], Literal[False]]
    reveal_type(args)
    f2(*args)  # fine

    if coinflip:
        other_args = "foo", True
    else:
        other_args = "bar", (True,)

    # revealed: tuple[Literal["foo"], Literal[True]] | tuple[Literal["bar"], tuple[Literal[True]]]
    reveal_type(other_args)
    # error: [invalid-argument-type] "Argument to function `f2` is incorrect: Expected `bool`, found `Literal[True] | tuple[Literal[True]]`"
    f2(*other_args)

def f4(a=None, b=None, c=None, d=None, e=None): ...

my_args = ((1, 2), (3, 4), (5, 6))

for tup in my_args:
    f4(*tup, e=None)  # fine

my_other_args = (
    (1, 2, 3, 4, 5),
    (6, 7, 8, 9, 10),
)

for tup in my_other_args:
    # error: [parameter-already-assigned] "Multiple values provided for parameter `e` of function `f4`"
    f4(*tup, e=None)

Regression test for https://github.com/astral-sh/ty/issues/2734.

def f5(x: int | None = None, y: str = "") -> None: ...
def f6(args: tuple[()] | tuple[int]) -> None:
    f5(*args)

def f7(x: int | None = None, y: str = "") -> None: ...
def f8(args: tuple[()] | tuple[str]) -> None:
    f7(*args)  # error: [invalid-argument-type]

def f11(*args: int) -> None: ...
def f12(args: tuple[int] | int) -> None:
    f11(*args)  # error: [not-iterable]

def f13(a: int, b: int, c: str) -> None: ...
def f14(a: int, b: int, c: str, d: list[float], e: list[float]) -> None: ...
def f15(profile: bool, line: str) -> None:
    matcher = f13
    timings = []
    if profile:
        matcher = f14
        timings = [[0.0], [1.0], [2.0], [3.0]]
    matcher(1, 2, line, *timings[:2])

def f9(x: int = 0, y: str = "") -> None: ...
def f10(args: tuple[int, ...] | tuple[int, str]) -> None:
    # The variable-length element `int` from `tuple[int, ...]` unions with `str`
    # from `tuple[int, str]` at position 1, giving `int | str` for `y: str`.
    f9(*args)  # error: [invalid-argument-type]

def f18(x: int = 0, y: int = 0) -> None: ...
def f19(args: tuple[int, ...] | tuple[int, int]) -> None:
    f18(*args)

# Union variadic unpacking also works when the non-defaulted parameters are covered by
# the shortest union element, even if not all remaining parameters are defaulted.
def f16(a: int, b: int = 0, c: str = "") -> None: ...
def f17(x: tuple[int] | tuple[int, int]) -> None:
    f16(*x)

# Longer union elements must still be rejected when they would contribute
# extra positional arguments.
def f20(a: int, b: int) -> None: ...
def f21(x: tuple[int, int] | tuple[int, int, int]) -> None:
    f20(*x)  # error: [too-many-positional-arguments]

# Shorter union elements must also be rejected when they cannot provide a required
# positional argument.
def f22(a: int, b: int, c: int) -> None: ...
def f23(x: tuple[int, int] | tuple[int, int, int]) -> None:
    f22(*x)  # error: [missing-argument]

Tuple unions followed by positional arguments

[environment]
python-version = "3.12"

A tuple union retains its minimum length when followed by another positional argument. Both members here supply at least one element, so the call always has too many arguments:

def one(a: int) -> None: ...
def _(args: tuple[int] | tuple[int, int]) -> None:
    one(*args, 1)  # error: [too-many-positional-arguments] "expected 1, got 2"

The minimum can include several required elements:

def two(a: int, b: int) -> None: ...
def _(args: tuple[int, int] | tuple[int, int, int]) -> None:
    two(*args, 1)  # error: [too-many-positional-arguments] "expected 2, got 3"

Type aliases preserve the same minimum:

type Nonempty = tuple[int] | tuple[int, int]

def _(args: Nonempty) -> None:
    one(*args, 1)  # error: [too-many-positional-arguments] "expected 1, got 2"

An empty tuple member or an iterable of unknown length can leave room for the later argument:

def optional(a: int, b: int = 0) -> None: ...
def _(args: tuple[()] | tuple[int]) -> None:
    optional(*args, 1)  # ok

def _(args: list[int] | tuple[int]) -> None:
    one(*args, 1)  # ok

When a tuple union is followed by another positional argument, we currently combine its element types before checking the call. Here, we treat the tuple as an iterable of int | str. This reports an error for both a and b, even though only b can receive a str:

def f(a: int, b: int, c: int = 0) -> None: ...
def _(args: tuple[int] | tuple[int, str]) -> None:
    # error: [invalid-argument-type]
    f(*args, 1)  # error: [invalid-argument-type]

Mixed argument and parameter containing variadic

[environment]
python-version = "3.11"
def f(x: int, *args: str) -> int:
    return 1

def _(
    args1: list[int],
    args2: tuple[int],
    args3: tuple[int, int],
    args4: tuple[int, ...],
    args5: tuple[int, *tuple[str, ...]],
    args6: tuple[int, int, *tuple[str, ...]],
) -> None:
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `str`, found `int`"
    reveal_type(f(*args1))  # revealed: int

    # This shouldn't raise an error because the unpacking doesn't match the variadic parameter.
    reveal_type(f(*args2))  # revealed: int

    # But, this should because the second tuple element is not assignable.
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `str`, found `int`"
    reveal_type(f(*args3))  # revealed: int

    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `str`, found `int`"
    reveal_type(f(*args4))  # revealed: int

    # The first element of the tuple matches the required argument;
    # all subsequent elements match the variadic argument
    reveal_type(f(*args5))  # revealed: int

    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `str`, found `int`"
    reveal_type(f(*args6))  # revealed: int

Variable-length unpacking with explicit keyword arguments

When a variable-length iterable (like a list) is unpacked and followed by explicit keyword arguments, the variadic unpacking should not greedily consume parameters that have explicit keyword bindings. This prevents false positive "parameter already assigned" errors.

Regression test for https://github.com/astral-sh/ty/issues/1584.

from typing import TypedDict

def f(a: str, b: str, c: float) -> None: ...

# Explicit keyword argument takes precedence over variable-length variadic expansion.
# The list unpacking should only fill `a` and `b`, leaving `c` for the keyword argument.
def _(args: list[str]) -> None:
    f(*args, c=1.0)

# Fixed-length tuple unpacking with keyword argument also works correctly.
def _(args: tuple[str, str]) -> None:
    f(*args, c=1.0)

# But, with a fixed-length tuple that is too long, we get the expected error.
def _(args: tuple[str, str, str]) -> None:
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `float`, found `str`"
    # error: [parameter-already-assigned] "Multiple values provided for parameter `c` of function `f`"
    f(*args, c=1.0)

If no later argument is known to supply a positional value, we still assume that the first iterable fills every remaining positional parameter:

# Multiple variable-length variadics are ambiguous
def _(args1: list[str], args2: list[float]) -> None:
    # error: [invalid-argument-type]
    f(*args1, *args2)

# Keyword variadic (**dict) with unknown keys is also ambiguous
def _(args: list[str], kwargs: dict[str, float]) -> None:
    # error: [invalid-argument-type]
    f(*args, **kwargs)

# Keyword variadic with TypedDict has known keys but is still handled conservatively
# but we could possibly improve this in the future.
class CKwargs(TypedDict):
    c: float

def _(args: list[str]) -> None:
    # error: [invalid-argument-type]
    # error: [parameter-already-assigned]
    f(*args, **CKwargs(c=1.0))

Variable-length unpacking with later positional arguments

For a callable without *args, we leave enough parameters for later positional arguments. The unpacked iterable may be short enough for the call to succeed.

Regression test for https://github.com/astral-sh/ty/issues/3649.

def f(a: str, b: str, c: float) -> None: ...
def _(args: list[str]) -> None:
    f(*args, 1.0)  # ok

Arguments on either side of the iterable reduce the number of parameters it can fill:

def _(args: list[str]) -> None:
    f(*args, "b", 1.0)  # ok
    f("a", *args, 1.0)  # ok

The later argument must match the type of its parameter:

def _(args: list[str]) -> None:
    # error: [invalid-argument-type] "Expected `float`, found `Literal["c"]`"
    f(*args, "c")

Even an empty iterable cannot make room for more arguments than the callable accepts:

def _(args: list[str]) -> None:
    # error: [too-many-positional-arguments] "expected 3, got 4"
    f(*args, "a", "b", 1.0, 2.0)

Variable-length unpacking with positional and keyword arguments

Both positional and keyword arguments leave fewer parameters for the unpacked iterable:

def f(a: str, b: float, c: int) -> None: ...
def _(args: list[str]) -> None:
    f(*args, 1.0, c=1)  # ok

Unpacking a dictionary afterwards does not prevent the positional argument from filling b:

def g(a: str, b: float) -> None: ...
def _(args: list[str], kwargs: dict[str, int]) -> None:
    g(*args, 1.0, **kwargs)  # ok

Variable-length unpacking followed by another unpacked argument

A later unpacked tuple also needs room for its elements:

def f(a: str, b: str, c: float) -> None: ...
def _(args: list[str]) -> None:
    f(*args, *(1.0,))  # ok

If the tuple fills every parameter, the earlier iterable must be empty:

def _(args: list[str], tail: tuple[str, str, float]) -> None:
    f(*args, *tail)  # ok

A variable-length tuple needs room for at least its required elements:

def _(args: list[str], more: tuple[float, *tuple[float, ...]]) -> None:
    f(*args, *more)  # ok

A later iterable with no required elements can be empty. Only the explicit 1.0 needs room here:

def _(args: list[str], more: list[float]) -> None:
    f(*args, *more, 1.0)  # ok

Required tuple elements before a later positional argument

The variable-length part of a tuple can be empty, leaving only its required final element:

def f(a: str, b: float) -> None: ...
def _(args: tuple[*tuple[bytes, ...], str]) -> None:
    f(*args, 1.0)  # ok

That final element cannot be omitted when its type is incompatible:

def _(args: tuple[*tuple[str, ...], bytes]) -> None:
    # error: [invalid-argument-type] "Expected `str`, found `bytes`"
    f(*args, 1.0)

Required elements at both ends of the tuple keep their order when the variable-length part is empty:

def g(a: str, b: bytes, c: float) -> None: ...
def _(args: tuple[str, *tuple[int, ...], bytes]) -> None:
    g(*args, 1.0)  # ok

When the variable-length part supplies one element, both required final elements still follow it:

def h(a: str, b: bytes, c: int, d: float) -> None: ...
def _(args: tuple[*tuple[str, ...], bytes, int]) -> None:
    h(*args, 1.0)  # ok

We still report excess arguments when the tuple's required elements cannot all fit:

def _(args: tuple[str, *tuple[str, ...], float, float]) -> None:
    # error: [too-many-positional-arguments] "expected 2, got 4"
    f(*args, 1.0)

Later positional arguments and variadic parameters

When the callable has a variadic parameter, we still assume the unpacked iterable fills the named positional parameters. Later arguments then go to the variadic parameter:

def log(fmt: str, *args: object) -> None: ...
def _(parts: list[str]) -> None:
    log(*parts, 1)  # ok

This remains a limitation: we reject calls that would succeed if the iterable were shorter. With two strings in args, 1.0 would fill c:

def v(a: str, b: str, c: float, *rest: str) -> None: ...
def _(args: list[str]) -> None:
    # TODO: Accept this call.
    # error: [invalid-argument-type] "Expected `float`, found `str`"
    # error: [invalid-argument-type] "Expected `str`"
    v(*args, 1.0)

Positional argument between unpacked iterables

We also reject the middle-argument example from https://github.com/astral-sh/ty/issues/3649. The first iterable fills four parameters, leaving text to fill e. The call would succeed if each iterable supplied two integers instead:

def f(a: int, b: int, c: str, d: int, e: int) -> None: ...
def _(before, text: str, after) -> None:
    # TODO: Accept this call.
    # error: [invalid-argument-type] "Expected `int`, found `str`"
    f(*before, text, *after)

Keyword argument, positional-or-keyword parameter

def f(x: int) -> int:
    return 1

# error: 15 [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `Literal["foo"]`"
reveal_type(f(x="foo"))  # revealed: int

Keyword argument, keyword-only parameter

def f(*, x: int) -> int:
    return 1

# error: 15 [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `Literal["foo"]`"
reveal_type(f(x="foo"))  # revealed: int

Keyword argument, keywords parameter

def f(**kwargs: int) -> int:
    return 1

# error: 15 [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `Literal["foo"]`"
reveal_type(f(x="foo"))  # revealed: int

Correctly match keyword out-of-order

def f(x: int = 1, y: str = "foo") -> int:
    return 1

# error: 15 [invalid-argument-type] "Argument to function `f` is incorrect: Expected `str`, found `Literal[2]`"
# error: 20 [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `Literal["bar"]`"
reveal_type(f(y=2, x="bar"))  # revealed: int

Diagnostics for union types where the union is not assignable

from typing import Sized

class Foo: ...
class Bar: ...
class Baz: ...

def f(x: Sized): ...
def g(
    a: str | Foo,
    b: list[str] | str | dict[str, str] | tuple[str, ...] | bytes | frozenset[str] | set[str] | Foo,
    c: list[str] | str | dict[str, str] | tuple[str, ...] | bytes | frozenset[str] | set[str] | Foo | Bar,
    d: list[str] | str | dict[str, str] | tuple[str, ...] | bytes | frozenset[str] | set[str] | Foo | Bar | Baz,
):
    f(a)  # error: [invalid-argument-type]
    f(b)  # error: [invalid-argument-type]
    f(c)  # error: [invalid-argument-type]
    f(d)  # error: [invalid-argument-type]

Too many positional arguments

One too many

def f() -> int:
    return 1

# error: 15 [too-many-positional-arguments] "Too many positional arguments to function `f`: expected 0, got 1"
reveal_type(f("foo"))  # revealed: int

Two too many

def f() -> int:
    return 1

# error: 15 [too-many-positional-arguments] "Too many positional arguments to function `f`: expected 0, got 2"
reveal_type(f("foo", "bar"))  # revealed: int

No too-many-positional if variadic is taken

def f(*args: int) -> int:
    return 1

reveal_type(f(1, 2, 3))  # revealed: int

Multiple keyword arguments map to keyword variadic parameter

def f(**kwargs: int) -> int:
    return 1

reveal_type(f(foo=1, bar=2))  # revealed: int

Missing arguments

No defaults or variadic

def f(x: int) -> int:
    return 1

# error: 13 [missing-argument] "No argument provided for required parameter `x` of function `f`"
reveal_type(f())  # revealed: int

With default

def f(x: int, y: str = "foo") -> int:
    return 1

# error: 13 [missing-argument] "No argument provided for required parameter `x` of function `f`"
reveal_type(f())  # revealed: int

Defaulted argument is not required

def f(x: int = 1) -> int:
    return 1

reveal_type(f())  # revealed: int

With variadic

def f(x: int, *y: str) -> int:
    return 1

# error: 13 [missing-argument] "No argument provided for required parameter `x` of function `f`"
reveal_type(f())  # revealed: int

Variadic argument is not required

def f(*args: int) -> int:
    return 1

reveal_type(f())  # revealed: int

Unpacked variadic arguments can require positional arguments

An unpacked tuple can require arguments even though an ordinary variadic parameter can be empty. Fixed tuples also reject positional arguments beyond their declared length.

[environment]
python-version = "3.13"
def at_least_one(*args: *tuple[*tuple[int, ...], int]) -> None: ...
def exactly_two(*args: *tuple[int, str]) -> None: ...
def exactly_zero(*args: *tuple[()]) -> None: ...

at_least_one()  # error: [missing-argument]
at_least_one(1)
at_least_one(1, 2)
at_least_one("wrong")  # error: [invalid-argument-type]
at_least_one(1, "wrong")  # error: [invalid-argument-type]

exactly_two()  # error: [missing-argument]
exactly_two(1)  # error: [missing-argument]
exactly_two(1, "two")
exactly_two("one", "two")  # error: [invalid-argument-type]
exactly_two(1, 2)  # error: [invalid-argument-type]
exactly_two(1, "two", 3)  # error: [too-many-positional-arguments]

exactly_zero()
exactly_zero(1)  # error: [too-many-positional-arguments]

Unpacked variadic arity errors preserve element diagnostics

Matched tuple elements should still be checked when a call has the wrong arity.

[environment]
python-version = "3.13"
def exactly_two(*args: *tuple[int, str]) -> None: ...

exactly_two(1, "valid")
exactly_two("wrong", "valid")  # error: [invalid-argument-type]

# TODO: error: [invalid-argument-type]
# error: [missing-argument]
exactly_two("wrong")

# TODO: error: [invalid-argument-type]
# error: [too-many-positional-arguments]
exactly_two("wrong", "valid", 3)

# TODO: error: [invalid-argument-type]
# TODO: error: [invalid-argument-type]
# error: [too-many-positional-arguments]
exactly_two("wrong", 2, 3)

The same recovery should validate fixed prefixes when a required suffix is missing.

def with_suffix(*args: *tuple[int, *tuple[str, ...], bytes]) -> None: ...

# TODO: error: [invalid-argument-type]
# error: [missing-argument]
with_suffix("wrong")

Forwarding a fixed-length tuple should preserve the same element and arity diagnostics.

def forward(values: tuple[str]) -> None:
    # TODO: error: [invalid-argument-type]
    # error: [missing-argument]
    exactly_two(*values)

Callable protocols should use the same recovery as ordinary functions.

from typing import Protocol

class ExactlyTwo(Protocol):
    def __call__(self, *args: *tuple[int, str]) -> None: ...

def call(callback: ExactlyTwo) -> None:
    # TODO: error: [invalid-argument-type]
    # error: [missing-argument]
    callback("wrong")

Unpacked variadic arguments preserve element positions

Fixed prefixes, a homogeneous variadic segment, and fixed suffixes each retain their own argument types. A required suffix also requires any preceding defaulted positional parameter to be filled.

[environment]
python-version = "3.13"
def mixed(*args: *tuple[int, *tuple[str, ...], bytes]) -> None: ...
def with_default(first: int = 0, *args: *tuple[*tuple[int, ...], int]) -> None: ...

mixed(1, b"last")
mixed(1, "middle", b"last")
mixed("first", b"last")  # error: [invalid-argument-type]
mixed(1, 2, b"last")  # error: [invalid-argument-type]
mixed(1, "middle", "last")  # error: [invalid-argument-type]

with_default()  # error: [missing-argument]
with_default(first=1)  # error: [missing-argument]
with_default(1)  # error: [missing-argument]
with_default(1, 2)

Unpacked variadic elements preserve generic bounds

Ordinary type variables are inferred from individual unpacked elements in homogeneous or heterogeneous tuples, even beside an unresolved type-variable tuple. Their upper bounds remain enforced.

[environment]
python-version = "3.13"
def fixed[T: str](*args: *tuple[T]) -> T:
    return args[0]

def suffix[T: str, *Ts](*args: *tuple[*Ts, T]) -> T:
    return args[-1]

reveal_type(fixed("valid"))  # revealed: Literal["valid"]
fixed(1)  # error: [invalid-argument-type]

reveal_type(suffix("prefix", "valid"))  # revealed: Literal["valid"]
suffix("prefix", 1)  # error: [invalid-argument-type]

def homogeneous[T: str](*args: *tuple[T, ...]) -> T:
    return args[0]

reveal_type(homogeneous("first", "second"))  # revealed: Literal["first", "second"]
homogeneous("valid", 1)  # error: [invalid-argument-type]

def heterogeneous[T: str](*args: *tuple[int, T]) -> T:
    return args[1]

def _(valid: tuple[int, str], invalid: tuple[int, int]) -> None:
    reveal_type(heterogeneous(*valid))  # revealed: str
    heterogeneous(*invalid)  # error: [invalid-argument-type]

Callable protocols enforce unpacked variadic requirements

Calling a callable protocol uses the same tuple element types and argument-count bounds as calling an ordinary function.

[environment]
python-version = "3.13"
from typing import Protocol

class AtLeastOne(Protocol):
    def __call__(self, *args: *tuple[*tuple[int, ...], int]) -> None: ...

class ExactlyOne(Protocol):
    def __call__(self, *args: *tuple[int]) -> None: ...

def call(at_least_one: AtLeastOne, exactly_one: ExactlyOne) -> None:
    at_least_one()  # error: [missing-argument]
    at_least_one(1)
    at_least_one("wrong")  # error: [invalid-argument-type]

    exactly_one(1)
    exactly_one()  # error: [missing-argument]
    exactly_one(1, 2)  # error: [too-many-positional-arguments]

Keywords argument is not required

def f(**kwargs: int) -> int:
    return 1

reveal_type(f())  # revealed: int

Multiple

def f(x: int, y: int) -> int:
    return 1

# error: 13 [missing-argument] "No arguments provided for required parameters `x`, `y` of function `f`"
reveal_type(f())  # revealed: int

Unknown argument

def f(x: int) -> int:
    return 1

# error: 20 [unknown-argument] "Argument `y` does not match any known parameter of function `f`"
reveal_type(f(x=1, y=2))  # revealed: int

Parameter already assigned

def f(x: int) -> int:
    return 1

# error: 18 [parameter-already-assigned] "Multiple values provided for parameter `x` of function `f`"
reveal_type(f(1, x=2))  # revealed: int

Special functions

Some functions require special handling in type inference. Here, we make sure that we still emit proper diagnostics in case of missing or superfluous arguments.

reveal_type

from typing_extensions import reveal_type

# error: [missing-argument] "No argument provided for required parameter `obj` of function `reveal_type`"
reveal_type()

# error: [too-many-positional-arguments] "Too many positional arguments to function `reveal_type`: expected 1, got 2"
reveal_type(1, 2)

static_assert

from ty_extensions import static_assert

# error: [missing-argument] "No argument provided for required parameter `condition` of function `static_assert`"
static_assert()

# error: [static-assert-error] "Static assertion error: argument evaluates to `False`"
static_assert(condition=False)

# error: [static-assert-error] "Static assertion error: argument of type `Unknown` has an ambiguous static truthiness"
# error: [invalid-syntax]
static_assert(**)

# error: [too-many-positional-arguments] "Too many positional arguments to function `static_assert`: expected 2, got 3"
# error: [invalid-argument-type] "Argument to function `static_assert` is incorrect: Expected `LiteralString | None`, found `Literal[2]`"
static_assert(True, 2, 3)

len

# error: [missing-argument] "No argument provided for required parameter `obj` of function `len`"
len()

# error: [too-many-positional-arguments] "Too many positional arguments to function `len`: expected 1, got 2"
len([], 1)

Type property predicates

from ty_extensions._internal import is_subtype_of

# error: [missing-argument]
is_subtype_of()

# error: [missing-argument]
is_subtype_of(int)

# error: [too-many-positional-arguments]
is_subtype_of(int, int, int)

# error: [too-many-positional-arguments]
is_subtype_of(int, int, int, int)

Keywords argument

A double-starred argument (**kwargs) can be used to pass an argument that implements the mapping protocol. This is matched against any of the unmatched standard (positional or keyword), keyword-only, and keywords (**kwargs) parameters.

Empty

def empty() -> None: ...
def _(kwargs: dict[str, int]) -> None:
    empty(**kwargs)

empty(**{})
empty(**dict())

Single parameter

from typing_extensions import TypedDict

def f(**kwargs: int) -> None: ...

class Foo(TypedDict):
    a: int
    b: int

def _(kwargs: dict[str, int]) -> None:
    f(**kwargs)

f(**{"foo": 1})
f(**dict(foo=1))
# error: [invalid-argument-type] "Argument to function `f` is incorrect: Possible extra items in unpacked open `TypedDict` have type `object`, expected `int`"
f(**Foo(a=1, b=2))

Positional-only and variadic parameters

def f1(a: int, b: int, /) -> None: ...
def f2(*args: int) -> None: ...
def _(kwargs: dict[str, int]) -> None:
    # error: [missing-argument] "No arguments provided for required parameters `a`, `b` of function `f1`"
    f1(**kwargs)

    # This doesn't raise an error because `*args` is an optional parameter and `**kwargs` can be empty.
    f2(**kwargs)

Standard parameters

from typing_extensions import TypedDict

class Foo(TypedDict):
    a: int
    b: int

def f(a: int, b: int) -> None: ...
def _(kwargs: dict[str, int]) -> None:
    f(**kwargs)

f(**{"a": 1, "b": 2})
f(**dict(a=1, b=2))
f(**Foo(a=1, b=2))

Unpacked keyword values retain their individual generic types

Each named value in an unpacked TypedDict must be related to its own generic parameter instead of using the type of the complete mapping.

from typing_extensions import TypedDict, TypeVar

T = TypeVar("T")
U = TypeVar("U")

class Values(TypedDict, closed=True):
    first: int
    second: str

def combine(*, first: T, second: U) -> tuple[T, U]:
    return first, second

values: Values = {"first": 1, "second": "value"}

reveal_type(combine(**values))  # revealed: tuple[int, str]

Keyword-only parameters

from typing_extensions import TypedDict

class Foo(TypedDict):
    a: int
    b: int

def f(*, a: int, b: int) -> None: ...
def _(kwargs: dict[str, int]) -> None:
    f(**kwargs)

f(**{"a": 1, "b": 2})
f(**dict(a=1, b=2))
f(**Foo(a=1, b=2))

Multiple keywords argument

def f(**kwargs: int) -> None: ...
def _(kwargs1: dict[str, int], kwargs2: dict[str, int], kwargs3: dict[str, str], kwargs4: dict[int, list[int]]) -> None:
    f(**kwargs1, **kwargs2)
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `str`"
    f(**kwargs1, **kwargs3)
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `str`"
    # error: [invalid-argument-type] "Argument expression after ** must be a mapping with `str` key type: Found `int`"
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `list[int]`"
    f(**kwargs3, **kwargs4)

Keyword-only after keywords

class B: ...

def f(*, a: int, b: B, **kwargs: int) -> None: ...
def _(kwargs: dict[str, int]):
    # Make sure that the `b` argument is not being matched against `kwargs` by passing an integer
    # instead of the annotated type which should raise an
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `B`, found `Literal[2]`"
    f(a=1, **kwargs, b=2)

Mixed parameter kind

def f1(*, a: int, b: int, **kwargs: int) -> None: ...
def f2(a: int, *, b: int, **kwargs: int) -> None: ...
def f3(a: int, /, *args: int, b: int, **kwargs: int) -> None: ...
def _(kwargs1: dict[str, int], kwargs2: dict[str, str]):
    f1(**kwargs1)
    f2(**kwargs1)
    f3(1, **kwargs1)

TypedDict

from typing_extensions import NotRequired, TypedDict

class Foo1(TypedDict):
    a: int
    b: str

class Foo2(TypedDict):
    a: int
    b: NotRequired[str]

def f(**kwargs: int) -> None: ...

# snapshot: invalid-argument-type
# snapshot: invalid-argument-type
f(**Foo1(a=1, b="b"))
# error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `int`, found `str`"
# error: [invalid-argument-type] "Argument to function `f` is incorrect: Possible extra items in unpacked open `TypedDict` have type `object`, expected `int`"
f(**Foo2(a=1))
error[invalid-argument-type]: Argument to function `f` is incorrect
  --> src/mdtest_snippet.py:15:3
   |
15 | f(**Foo1(a=1, b="b"))
   |   ^^^^^^^^^^^^^^^^^^ Expected `int`, found `str`
info: Function defined here
  --> src/mdtest_snippet.py:11:5
   |
11 | def f(**kwargs: int) -> None: ...
   |     ^ ------------- Parameter declared here


error[invalid-argument-type]: Argument to function `f` is incorrect
  --> src/mdtest_snippet.py:15:3
   |
15 | f(**Foo1(a=1, b="b"))
   |   ^^^^^^^^^^^^^^^^^^ Possible extra items in unpacked open `TypedDict` have type `object`, expected `int`
info: Function defined here
  --> src/mdtest_snippet.py:11:5
   |
11 | def f(**kwargs: int) -> None: ...
   |     ^ ------------- Parameter declared here

TypedDict union

from typing_extensions import TypedDict

class GoodA(TypedDict):
    a: int
    b: int

class GoodB(TypedDict):
    a: int
    b: int

class BadA(TypedDict):
    a: int
    b: str

class BadB(TypedDict):
    a: int
    b: str

def needs_known_keys(*, a: int, b: int, c: int) -> None: ...
def takes_int_kwargs(**kwargs: int) -> None: ...
def _(good: GoodA | GoodB, bad: BadA | BadB) -> None:
    # error: [missing-argument] "No argument provided for required parameter `c` of function `needs_known_keys`"
    needs_known_keys(**good)

    # error: [invalid-argument-type] "Argument to function `takes_int_kwargs` is incorrect: Expected `int`, found `str`"
    # error: [invalid-argument-type] "Argument to function `takes_int_kwargs` is incorrect: Possible extra items in unpacked open `TypedDict` have type `object`, expected `int`"
    takes_int_kwargs(**bad)

Keys must be strings

The keys of the mapping passed to a double-starred argument must be strings.

from collections.abc import Mapping

def f(**kwargs: int) -> None: ...

class DictSubclass(dict[int, int]): ...

class MappingSubclass(Mapping[int, int]):
    def __iter__(self): ...
    def __len__(self): ...
    def __getitem__(self, key): ...

class MappingProtocol:
    def keys(self) -> list[int]:
        return [1]

    def __getitem__(self, key: int) -> int:
        return 1

def _(kwargs: dict[int, int]) -> None:
    # error: [invalid-argument-type] "Argument expression after ** must be a mapping with `str` key type: Found `int`"
    f(**kwargs)

# error: [invalid-argument-type] "Argument expression after ** must be a mapping with `str` key type: Found `int`"
f(**DictSubclass())
# error: [invalid-argument-type] "Argument expression after ** must be a mapping with `str` key type: Found `int`"
f(**MappingSubclass())
# error: [invalid-argument-type] "Argument expression after ** must be a mapping with `str` key type: Found `int`"
f(**MappingProtocol())

The key can also be a custom type that inherits from str.

class SubStr(str): ...
class SubInt(int): ...

def _(kwargs1: dict[SubStr, int], kwargs2: dict[SubInt, int]) -> None:
    f(**kwargs1)
    # error: [invalid-argument-type] "Argument expression after ** must be a mapping with `str` key type: Found `SubInt`"
    f(**kwargs2)

Or, it can be a type that is assignable to str.

from typing import Any
from ty_extensions._internal import Unknown

def _(kwargs1: dict[Any, int], kwargs2: dict[Unknown, int]) -> None:
    f(**kwargs1)
    f(**kwargs2)

Invalid value type

from collections.abc import Mapping

def f(**kwargs: str) -> None: ...

class DictSubclass(dict[str, int]): ...

class MappingSubclass(Mapping[str, int]):
    def __iter__(self): ...
    def __len__(self): ...
    def __getitem__(self, key) -> int:
        return 42

class MappingProtocol:
    def keys(self) -> list[str]:
        return ["foo"]

    def __getitem__(self, key: str) -> int:
        return 1

def _(kwargs: dict[str, int]) -> None:
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `str`, found `int`"
    f(**kwargs)
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `str`, found `int`"
    f(**DictSubclass())
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `str`, found `int`"
    f(**MappingSubclass())
    # error: [invalid-argument-type] "Argument to function `f` is incorrect: Expected `str`, found `int`"
    f(**MappingProtocol())

Unknown type

from ty_extensions._internal import Unknown

def f(**kwargs: int) -> None: ...
def _(kwargs: Unknown):
    f(**kwargs)

Not a mapping

def f(**kwargs: int) -> None: ...

class A: ...

class InvalidMapping:
    def keys(self) -> A:
        return A()

    def __getitem__(self, key: str) -> int:
        return 1

def _(kwargs: dict[str, int] | int):
    # error: [invalid-argument-type] "Argument expression after ** must be a mapping type: Found `dict[str, int] | int`"
    f(**kwargs)
    # error: [invalid-argument-type] "Argument expression after ** must be a mapping type: Found `InvalidMapping`"
    f(**InvalidMapping())

Not a mapping with overloaded function

When **kwargs with a non-mapping type is passed to an overloaded function, the error should report the specific mapping type error.

overloaded.pyi:

from typing import overload

@overload
def f(x: int, **kwargs: int) -> int: ...
@overload
def f(x: str, **kwargs: str) -> str: ...
from overloaded import f

# error: [invalid-argument-type] "Argument expression after ** must be a mapping type: Found `None`"
f(1, **None)

def _(kwargs: dict[str, int] | int):
    # error: [invalid-argument-type] "Argument expression after ** must be a mapping type: Found `dict[str, int] | int`"
    f(1, **kwargs)

Generic

For a generic keywords parameter, the type variable should be specialized to the value type of the mapping.

from typing import TypeVar

_MappingT = TypeVar("_MappingT")

def f(**kwargs: _MappingT) -> _MappingT:
    return kwargs["a"]

def _(kwargs: dict[str, int]) -> None:
    reveal_type(f(**kwargs))  # revealed: int

For an open TypedDict, the type variable must also account for hidden values of type object.

from typing import TypeVar
from typing_extensions import TypedDict

_T = TypeVar("_T")

class Foo(TypedDict):
    a: int
    b: str

def f(**kwargs: _T) -> _T:
    return kwargs["a"]

reveal_type(f(**Foo(a=1, b="b")))  # revealed: object

Non-iterable variadic argument

A starred argument must be iterable. If it is not, an error should be reported.

def some_fn(a: int):
    pass

# error: [not-iterable] "Object of type `None` is not iterable"
some_fn(*None)

This also applies when the type might not be iterable:

def f(*args: int) -> int:
    return 1

def _(x: int | list[int]):
    # error: [not-iterable] "Object of type `int | list[int]` may not be iterable"
    f(*x)

Non-iterable variadic argument with overloaded functions

overloaded.pyi:

from typing import overload

@overload
def foo(a: int) -> tuple[int]: ...
@overload
def foo(a: int, b: int) -> tuple[int, int]: ...
from overloaded import foo

# error: [not-iterable] "Object of type `None` is not iterable"
foo(*None)

def _(arg: int):
    # error: [not-iterable] "Object of type `int` is not iterable"
    foo(*arg)

Union variadic unpacking with explicit keyword arguments

When a union type containing variable-length elements (like Unknown) is unpacked as *args, the variadic expansion should not greedily consume optional positional parameters that are also provided as explicit keyword arguments.

from ty_extensions._internal import Unknown

def f(a: int = 0, b: int = 0, c: int = 0, fmt: str | None = None) -> None: ...
def _(args: "Unknown | tuple[int, int, int]"):
    f(*args, fmt="{key}")  # fine

def g(a: int, b: int = 0, c: int = 0) -> None: ...
def _(args: tuple[int, int] | tuple[int, int, int]):
    g(*args, c=1)  # error: [parameter-already-assigned]

Variadic unpacking should stop at max known arity

When unpacking (a union of) fixed-length tuples, variadic matching should stop once the known positions are exhausted. Otherwise, optional positional parameters can be incorrectly treated as already assigned, causing false positives for **kwargs.

(This test uses **kwargs unpacking of a TypedDict instead of the simpler c=1 keyword argument, because c=1 is a known keyword argument and we always prevent unpacking *args over an explicitly-provided keyword argument. The case shown here, without the explicit keyword argument, requires instead that we use our knowledge of the tuple length to prevent over-unpacking.)

from typing import TypedDict

class CKwargs(TypedDict):
    c: int

def f(a: int = 0, b: int = 0, c: int = 0) -> None: ...
def _(args_tuple: tuple[int, int], args_union: tuple[int] | tuple[int, int], kwargs: CKwargs) -> None:
    f(*args_tuple, **kwargs)  # fine
    f(*args_union, **kwargs)  # fine