For variable positional arguments (*args) and variable keyword arguments (**kw) you only need to specify the expected value for one such argument.
From the Arbitrary argument lists and default argument values section of the Type Hints PEP:
Arbitrary argument lists can as well be type annotated, so that the definition:
def foo(*args: str, **kwds: int): ...is acceptable and it means that, e.g., all of the following represent function calls with valid types of arguments:
foo('a', 'b', 'c') foo(x=1, y=2) foo('', z=0)
So you'd want to specify your method like this:
def foo(*args: int):
However, if your function can only accept either one or two integer values, you should not use *args at all, use one explicit positional argument and a second keyword argument:
def foo(first: int, second: Optional[int] = None):
Now your function is actually limited to one or two arguments, and both must be integers if specified. *args always means 0 or more, and can't be limited by type hints to a more specific range.
For variable positional arguments (*args) and variable keyword arguments (**kw) you only need to specify the expected value for one such argument.
From the Arbitrary argument lists and default argument values section of the Type Hints PEP:
Arbitrary argument lists can as well be type annotated, so that the definition:
def foo(*args: str, **kwds: int): ...is acceptable and it means that, e.g., all of the following represent function calls with valid types of arguments:
foo('a', 'b', 'c') foo(x=1, y=2) foo('', z=0)
So you'd want to specify your method like this:
def foo(*args: int):
However, if your function can only accept either one or two integer values, you should not use *args at all, use one explicit positional argument and a second keyword argument:
def foo(first: int, second: Optional[int] = None):
Now your function is actually limited to one or two arguments, and both must be integers if specified. *args always means 0 or more, and can't be limited by type hints to a more specific range.
2022 Update
The mypy team added support for Unpack, this is available since Mypy 0.981 or higher.
Attention! Although this feature is complete, Unpack[...] is still considered experimental, so you will need to use --enable-incomplete-features to enable it.
You can use this feature as follows:
from typing import TypedDict
from typing_extensions import Unpack
class RequestParams(TypedDict):
url: str
allow_redirects: bool
def request(**kwargs: Unpack[RequestParams]) -> None:
...
If you call the request function with the arguments defined in the TypedDict, you won't get any errors:
# OK
request(url="https://example.com", allow_redirects=True)
If you forget to pass an argument, mypy will let you know now
# error: Missing named argument "allow_redirects" for "request" [call-arg]
request(url="https://example.com")
You can also make the fields non-required by adding total=False to the TypedDict:
class RequestParams(TypedDict, total=False):
url: str
allow_redirects: bool
# OK
request(url="https://example.com")
Alternatively, you can use the Required and NotRequired annotations to control whether a keyword argument is required or not:
from typing import TypedDict
from typing_extensions import Unpack, NotRequired
class RequestParams(TypedDict):
url: str
allow_redirects: NotRequired[bool]
def request(**kwargs: Unpack[RequestParams]) -> None:
...
# OK
request(url="https://example.com", allow_redirects=True)
Old answer below:
While you can annotate variadic arguments with a type, I don't find it very useful because it assumes that all arguments are of the same type.
The proper type annotation of *args and **kwargs that allows specifying each variadic argument separately is not supported by mypy yet. There is a proposal for adding an Expand helper on mypy_extensions module, it would work like this:
class Options(TypedDict):
timeout: int
alternative: str
on_error: Callable[[int], None]
on_timeout: Callable[[], None]
...
def fun(x: int, *, **options: Expand[Options]) -> None:
...
The GitHub issue was opened on January 2018 but it's still not closed. Note that while the issue is about **kwargs, the Expand syntax will likely be used for *args as well.
Python Type Hints – *args and **kwargs (2021)
ParamSpec: use P.args and P.kwargs in other scopes, such as return types
Variadic typing for kwargs, namedtuple - Typing - Discussions on Python.org
Is it possible to type hint `tuple` and `dict` equivalent to `P.args` and `P.kwargs`?
Videos
I tend to avoid *args and **kwargs in Python as they often obscure public APIs. But I'm glad that it's now at least possible to annotate them somewhat precisely.
https://rednafi.com/python/annotate_args_and_kwargs/