Function calls with standard dictionaries

Calling a function that has **kwargs typed using the **kwargs: **Movie syntax with a dictionary of type dict[str, object] must generate a type checker error. On the other hand, the behaviour for functions using standard, untyped dictionaries can depend on the type checker. For example:

def foo(**kwargs: **Movie) -> None: ...

movie: dict[str, object] = {"name": "Life of Brian", "year": 1979}
foo(**movie)  # WRONG! Movie is of type dict[str, object]

typed_movie: Movie = {"name": "The Meaning of Life", "year": 1983}
foo(**typed_movie)  # OK!

another_movie = {"name": "Life of Brian", "year": 1979}
foo(**another_movie)  # Depends on the type checker.

Keyword collisions

A TypedDict that is used to type **kwargs could potentially contain keys that are already defined in the function’s signature. If the duplicate name is a standard argument, an error should be reported by type checkers. If the duplicate name is a positional only argument, no errors should be generated. For example:

def foo(name, **kwargs: **Movie) -> None: ...     # WRONG! "name" will
                                                  # always bind to the
                                                  # first parameter.

def foo(name, /, **kwargs: **Movie) -> None: ...  # OK! "name" is a
                                                  # positional argument,
                                                  # so **kwargs can contain
                                                  # a "name" keyword.

Required and non-required keys

By default all keys in a TypedDict are required. This behaviour can be overridden by setting the dictionary’s total parameter as False. Moreover, PEP 655 introduced new type qualifiers - typing.Required and typing.NotRequired - that enable specifying whether a particular key is required or not:

class Movie(TypedDict):
    title: str
    year: NotRequired[int]

When using a TypedDict to type **kwargs all of the required and non-required keys should correspond to required and non-required function keyword parameters. Therefore, if a required key is not supported by the caller, then an error must be reported by type checkers.

Assignment

Assignments of a function typed with the **kwargs: **Movie construct and another callable type should pass type checking only if they are compatible. This can happen for the scenarios described below.

class Animal(TypedDict):
    name: str

class Dog(Animal):
    breed: str

def accept_animal(**kwargs: **Animal): ...
def accept_dog(**kwargs: **Dog): ...

accept_dog = accept_animal  # OK! Expression of type Dog can be
                            # assigned to a variable of type Animal.

accept_animal = accept_dog  # WRONG! Expression of type Animal
                            # cannot be assigned to a variable of type Dog.

class Example(TypedDict):
    animal: Animal
    string: str
    number: NotRequired[int]

def src(**kwargs: **Example): ...
def dest(*, animal: Dog, string: str, number: int = ...): ...

dest = src  # OK!

def dest(animal: Dog, string: str, number: int = ...): ...
dest(animal_instance, "some string")  # OK!
dest = src
dest(animal_instance, "some string")  # WRONG! The same call fails at
                                      # runtime now because 'src' expects
                                      # keyword arguments.

def dest(**Animal): ...
def src(name: str): ...

dog: Dog = {"name": "Daisy", "breed": "Labrador"}
animal: Animal = dog

dest = src      # WRONG!
dest(**animal)  # Fails at runtime.

def src(**kwargs): ...
def dest(**kwargs: **Movie): ...

dest = src  # OK!

class Vehicle:
    ...

class Car(Vehicle):
    ...

class Motorcycle(Vehicle):
    ...

class Vehicles(TypedDict):
    car: Car
    moto: Motorcycle

def dest(**kwargs: **Vehicles): ...
def src(**kwargs: Vehicle): ...

dest = src  # OK!

Passing kwargs inside a function to another function

A previous point mentions the problem of possibly passing additional keyword arguments by assigning a subclass instance to a variable that has a base class type. Let’s consider the following example:

class Animal(TypedDict):
    name: str

class Dog(Animal):
    breed: str

def takes_name(name: str): ...

dog: Dog = {"name": "Daisy", "breed": "Labrador"}
animal: Animal = dog

def foo(**kwargs: **Animal):
    print(kwargs["name"].capitalize())

def bar(**kwargs: **Animal):
    takes_name(**kwargs)

def baz(animal: Animal):
    takes_name(**animal)

def spam(**kwargs: **Animal):
    baz(kwargs)

foo(**animal)   # OK! foo only expects and uses keywords of 'Animal'.

bar(**animal)   # WRONG! This will fail at runtime because 'breed' keyword
                # will be passed to 'takes_name' as well.

spam(**animal)  # WRONG! Again, 'breed' keyword will be eventually passed
                # to 'takes_name'.

In the example above, the call to foo will not cause any issues at runtime. Even though foo expects kwargs of type Animal it doesn’t matter if it receives additional arguments because it only reads and uses what it needs completely ignoring any additional values.

The calls to bar and spam will fail because an unexpected keyword argument will be passed to the takes_name function.

Therefore, kwargs hinted with an unpacked TypedDict can only be passed to another function if the function to which unpacked kwargs are being passed to has **kwargs in its signature as well, because then additional keywords would not cause errors at runtime during function invocation. Otherwise, the type checker should generate an error.

In cases similar to the bar function above the problem could be worked around by explicitly dereferencing desired fields and using them as parameters to perform the function call:

def bar(**kwargs: **Animal):
    name = kwargs["name"]
    takes_name(name)

Intended Usage

This proposal will bring a large benefit to the codebases that already use **kwargs because of the flexibility that they provided in the initial phases of the development, but now are mature enough to use a stricter contract via type hints.

Adding type hints directly in the source code as opposed to the *.pyi stubs benefits anyone who reads the code as it is easier to understand. Given that currently precise **kwargs type hinting is impossible in that case the choices are to either not type hint **kwargs at all, which isn’t ideal, or to refactor the function to use explicit keyword arguments, which often exceeds the scope of time and effort allocated to adding type hinting and, as any code change, introduces risk for both project maintainers and users. In that case hinting **kwargs using a TypedDict as described in this PEP will not require refactoring and function body and function invocations could be appropriately type checked.

Another useful pattern that justifies using and typing **kwargs as proposed is when the function’s API should allow for optional keyword arguments that don’t have default values.

However, it has to be pointed out that in some cases there are better tools for the job than using TypedDict to type **kwargs as proposed in this PEP. For example, when writing new code if all the keyword arguments are required or have default values then writing everything explicitly is better than using **kwargs and a TypedDict:

def foo(name: str, year: int): ...  # Preferred way.
def foo(**kwargs: **Movie): ...

Similarly, when type hinting third party libraries via stubs it is again better to state the function signature explicitly - this is the only way to type such a function if it has default parameters. Another issue that may arise in this case when trying to type hint the function with a TypedDict is that some standard function arguments may be treated as keyword only:

def foo(name, year): ...              # Function in a third party library.

def foo(**Movie): ...                 # Function signature in a stub file.

foo("Life of Brian", 1979)            # This would be now failing type
                                      # checking but is fine.

foo(name="Life of Brian", year=1979)  # This would be the only way to call
                                      # the function now that passes type
                                      # checking.

Therefore, in this case it is again preferred to type hint such function explicitly as:

def foo(name: str, year: int): ...

Backwards Compatibility

Using the double asterisk syntax for annotating **kwargs would be available only in new versions of Python. PEP 646 dealt with the similar problem and its authors introduced a new type operator Unpack. For the purposes of this PEP, the proposition is to reuse Unpack for more precise **kwargs typing. For example:

def foo(**kwargs: Unpack[Movie]) -> None: ...

There are several reasons for reusing PEP 646’s Unpack. Firstly, the name is quite suitable and intuitive for the **kwargs typing use case as the keywords arguments are “unpacked” from the TypedDict. Secondly, there would be no need to introduce any new special forms. Lastly, the use of Unpack for the purposes described in this PEP does not interfere with the use cases described in PEP 646.

Alternatives

Instead of making the grammar change, Unpack could be the only way to annotate **kwargs of different types. However, introducing the double asterisk syntax has two advantages. Namely, it is more concise and more intuitive than using Unpack.

TypedDict unions

It is possible to create unions of typed dictionaries. However, supporting typing **kwargs with a union of typed dicts would greatly increase the complexity of the implementation of this PEP and there seems to be no compelling use case to justify the support for this. Therefore, using unions of typed dictionaries to type **kwargs as described in the context of this PEP can result in an error:

class Book(TypedDict):
    genre: str
    pages: int

TypedDictUnion = Movie | Book

def foo(**kwargs: **TypedDictUnion) -> None: ...  # WRONG! Unsupported use
                                                  # of a union of
                                                  # TypedDicts to type
                                                  # **kwargs

Instead, a function that expects a union of TypedDicts can be overloaded:

@overload
def foo(**kwargs: **Movie): ...

@overload
def foo(**kwargs: **Book): ...