Text of peps.python.org › pep-0692 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 692 – Using TypedDict for more precise **kwargs typing | peps.python.org

PEP 692 – Using TypedDict for more precise **kwargs typing PEP 692 – Using TypedDict for more precise **kwargs typing Author : Franek Magiera <framagie at gmail.com> Sponsor : Jelle Zijlstra <jelle.zijlstra at gmail.com> Discussions-To : Discourse thread Status : Final Type : Standards Track Topic : Typing Created : 29-May-2022 Python-Version : 3.12 Post-History : 29-May-2022 , 12-Jul-2022 , 12-Jul-2022 Resolution : Discourse message Table of Contents Abstract Motivation Rationale Specification Function calls with standard dictionaries Keyword collisions Required and non-required keys Assignment Source and destination contain **kwargs Source contains **kwargs and destination doesn’t Source contains untyped **kwargs Source contains traditionally typed **kwargs: T Passing kwargs inside a function to another function Using Unpack with types other than TypedDict Changes to Unpack Intended Usage How to Teach This Reference Implementation Rejected Ideas TypedDict unions Changing the meaning of **kwargs annotations Introducing a new syntax Copyright Important This PEP is a historical document: see Unpack for keyword arguments for up-to-date specs and documentation.

Canonical typing specs are maintained at the typing specs site ; runtime typing behaviour is described in the CPython documentation. × See the typing specification update process for how to propose changes to the typing spec. Abstract Currently **kwargs can be type hinted as long as all of the keyword arguments specified by them are of the same type. However, that behaviour can be very limiting. Therefore, in this PEP we propose a new way to enable more precise **kwargs typing.

The new approach revolves around using TypedDict to type **kwargs that comprise keyword arguments of different types. Motivation Currently annotating **kwargs with a type T means that the kwargs type is in fact dict[str, T] . For example: def foo ( ** kwargs : str ) -> None : ... means that all keyword arguments in foo are strings (i.e., kwargs is of type dict[str, str] ). This behaviour limits the ability to type annotate **kwargs only to the cases where all of them are of the same type.

However, it is often the case that keyword arguments conveyed by **kwargs have different types that are dependent on the keyword’s name. In those cases type annotating **kwargs is not possible. This is especially a problem for already existing codebases where the need of refactoring the code in order to introduce proper type annotations may be considered not worth the effort. This in turn prevents the project from getting all of the benefits that type hinting can provide.

Moreover, **kwargs can be used to reduce the amount of code needed in cases when there is a top-level function that is a part of a public API and it calls a bunch of helper functions, all of which expect the same keyword arguments. Unfortunately, if those helper functions were to use **kwargs , there is no way to properly type hint them if the keyword arguments they expect are of different types. In addition, even if the keyword arguments are of the same type, there is no way to check whether the function is being called with keyword names that it actually expects.

As described in the Intended Usage section, using **kwargs is not always the best tool for the job. Despite that, it is still a widely used pattern. As a consequence, there has been a lot of discussion around supporting more precise **kwargs typing and it became a feature that would be valuable for a large part of the Python community. This is best illustrated by the mypy GitHub issue 4441 which contains a lot of real world cases that could benefit from this propsal.

One more use case worth mentioning for which **kwargs are also convenient, is when a function should accommodate optional keyword-only arguments that don’t have default values. A need for a pattern like that can arise when values that are usually used as defaults to indicate no user input, such as None , can be passed in by a user and should result in a valid, non-default behavior. For example, this issue came up in the popular httpx library.

Rationale PEP 589 introduced the TypedDict type constructor that supports dictionary types consisting of string keys and values of potentially different types. A function’s keyword arguments represented by a formal parameter that begins with double asterisk, such as **kwargs , are received as a dictionary. Additionally, such functions are often called using unpacked dictionaries to provide keyword arguments. This makes TypedDict a perfect candidate to be used for more precise **kwargs typing.

In addition, with TypedDict keyword names can be taken into account during static type analysis. However, specifying **kwargs type with a TypedDict means, as mentioned earlier, that each keyword argument specified by **kwargs is a TypedDict itself. For instance: class Movie ( TypedDict ): name : str year : int def foo ( ** kwargs : Movie ) -> None : ... means that each keyword argument in foo is itself a Movie dictionary that has a name key with a string type value and a year key with an integer type value.

Therefore, in order to support specifying kwargs type as a TypedDict without breaking current behaviour, a new construct has to be introduced. To support this use case, we propose reusing Unpack which was initially introduced in PEP 646 . There are several reasons for doing so: Its name is quite suitable and intuitive for the **kwargs typing use case as our intention is to “unpack” the keywords arguments from the supplied TypedDict .

The current way of typing *args would be extended to **kwargs and those are supposed to behave similarly. There would be no need to introduce any new special forms. The use of Unpack for the purposes described in this PEP does not interfere with the use cases described in PEP 646 . Specification With Unpack we introduce a new way of annotating **kwargs . Continuing the previous example: def foo ( ** kwargs : Unpack [ Movie ]) -> None : ... would mean that the **kwargs comprise two keyword arguments specified by Movie (i.e. a name keyword of type str and a year keyword of type int ).

This indicates that the function should be called as follows: kwargs : Movie = { "name" : "Life of Brian" , "year" : 1979 } foo ( ** kwargs ) # OK! foo ( name = "The Meaning of Life" , year = 1983 ) # OK! When Unpack is used, type checkers treat kwargs inside the function body as a TypedDict : def foo ( ** kwargs : Unpack [ Movie ]) -> None : assert_type ( kwargs , Movie ) # OK! Using the new annotation will not have any runtime effect - it should only be taken into account by type checkers.

Any mention of errors in the following sections relates to type checker errors. Function calls with standard dictionaries Passing a dictionary of type dict[str, object] as a **kwargs argument to a function that has **kwargs annotated with Unpack 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 : Unpack [ 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 parameter, an error should be reported by type checkers.

If the duplicate name is a positional-only parameter, no errors should be generated. For example: def foo ( name , ** kwargs : Unpack [ Movie ]) -> None : ... # WRONG! "name" will # always bind to the # first parameter. def foo ( name , / , ** kwargs : Unpack [

The rest of this page is on the live site.