Type checking for *args and **kwargs when passing them to another function

[t1m013y]

Feature

Add type checking for passing *args and **kwargs to another function.

It may be enabled by default when mypy detects *args and **kwargs are passed to the same function or it may be enabled only by decorator (for example, @mypy_extensions.pass_args. This will overwrite *args and **kwargs in the function signature with signature of the function to which they are passed. Also it should be possible to explicitly mark the function to which arguments are passed and specify whether to pass *args, **kwargs or both.

Pitch

I'll give an example with usual functions but it will be useful for decorators too.

For example, function wrapper passes its arguments to function inner and adds its own arguments:

def inner(a: int, b: int) -> None:
    ...


def wrapper(arg1: str, *args, **kwargs) -> None:
    inner(*args, **kwargs)  # It will automatically detect passing arguments to another function

This will automatically detect passing *args and **kwargs to another function and change the function signature to:

def wrapper(arg1: str, a: int, b: int):
    ...

It should successfully process and type-check the following calls:

wrapper("foo", 1, 2)  # All positional arguments
wrapper(arg1="foo", b=1, a=2)  # All keyword arguments
wrapper("foo", 1, a=2)  # Mix positional and keyword

wrapper([], 1, 2)
#       ^^ Type error in wrapper's argument (list passed instead of str)

wrapper("foo", [], 2)
#              ^^ Type error in inner's argument (list passed instead of int)

Also multiple passes to the same function should be successfully processed:

def wrapper(arg1: str, *args, **kwargs) -> None:
    if some_condition:
        inner(1, *args, **kwargs)  # Multiple same function calls with passed arguments
    elif condition2:
        inner(2, *args, **kwargs)
    else:
        inner(*args, **kwargs)

Also these cases should be processed:

def wrapper(arg1: str, *args, **kwargs) -> None:
    inner(*args)  # Only args are passed

def wrapper(arg1: str, *args, **kwargs) -> None:
    inner(**kwargs)  # Only kwargs are passed

There should be an option to overwrite this behavior using decorator (or this feature may be disabled by default and be enabled by the decorator). The decorator factory signature concept:

def pass_args(func: collections.abc.Callable | None, pass_args: bool = False, pass_kwargs: bool = False):
    ...

func – The function to copy arguments from. Use None value to force disable this feature.
pass_args – whether to copy arguments that may be passed as positional (passing *args)
pass_kwargs – whether to copy arguments that may be passed as keyword (passing **kwargs)

[t1m013y]

Annotation:

If a normal/keyword-only inner's argument name matches wrapper's argument name, inner's argument doesn't overwrite wrapper's one (wrapper's arguments have precedence).

If a positional-only inner's argument name matches wrapper's argument name, inner's is appended to wrapper's arguments list under alternative name.

Example:

def wrapper(arg1: int, /, arg2: int, *args, arg3: int, **kwargs) -> None:
    # All have type int
    inner(*args, **kwargs)
    ...


def inner(arg1: str, /, arg2: str, *, arg3: str = "") -> None:
    # All have type str
    print(arg1, arg2, arg3)
    ...

Wrapper's signature with replaced arguments:

def wrapper(arg1: int, /, arg2: int, _inner_arg1: str, *, arg3: int):
    # int = from wrapper
    # str = from inner
    # inner's arg1 is added to the wrapper under the alternative name
    # inner's arg2, arg3 are overridden by wrapper's arguments because they aren't positional-only
    ...

This is my personal opinion on how argument overwriting should work, the final version of this feature may use a different mechanism