Totality¶

By default mypy ensures that aTypedDict object has all the specifiedkeys. This will be flagged as an error:

# Error: 'year' missingtoy_story:Movie={'name':'Toy Story'}

Sometimes you want to allow keys to be left out when creating aTypedDict object. You can provide thetotal=False argument toTypedDict(...) to achieve this:

GuiOptions=TypedDict('GuiOptions',{'language':str,'color':str},total=False)options:GuiOptions={}# Okayoptions['language']='en'

You may need to useget() to access items of a partial (non-total)TypedDict, since indexing using[] could fail at runtime.However, mypy still lets use[] with a partialTypedDict – youjust need to be careful with it, as it could result in aKeyError.Requiringget() everywhere would be too cumbersome. (Note that youare free to useget() with totalTypedDicts as well.)

Keys that aren’t required are shown with a? in error messages:

# Revealed type is "TypedDict('GuiOptions', {'language'?: builtins.str,#                                            'color'?: builtins.str})"reveal_type(options)

Totality also affects structural compatibility. You can’t use a partialTypedDict when a total one is expected. Also, a totalTypedDict is notvalid when a partial one is expected.

Supported operations¶

TypedDict objects support a subset of dictionary operations and methods.You must use string literals as keys when calling most of the methods,as otherwise mypy won’t be able to check that the key is valid. Listof supported operations:

• Anything included inMapping:

  • d[key]

  • keyind

  • len(d)

  • forkeyind (iteration)

  • d.get(key[,default])

  • d.keys()

  • d.values()

  • d.items()

• d.copy()

• d.setdefault(key,default)

• d1.update(d2)

• d.pop(key[,default]) (partialTypedDicts only)

• deld[key] (partialTypedDicts only)

Class-based syntax¶

An alternative, class-based syntax to define aTypedDict is supportedin Python 3.6 and later:

fromtypingimportTypedDict# "from typing_extensions" in Python 3.7 and earlierclassMovie(TypedDict):name:stryear:int

The above definition is equivalent to the originalMoviedefinition. It doesn’t actually define a real class. This syntax alsosupports a form of inheritance – subclasses can define additionalitems. However, this is primarily a notational shortcut. Since mypyuses structural compatibility withTypedDicts, inheritance is notrequired for compatibility. Here is an example of inheritance:

classMovie(TypedDict):name:stryear:intclassBookBasedMovie(Movie):based_on:str

NowBookBasedMovie has keysname,year andbased_on.

Mixing required and non-required items¶

In addition to allowing reuse acrossTypedDict types, inheritance also allowsyou to mix required and non-required (usingtotal=False) itemsin a singleTypedDict. Example:

classMovieBase(TypedDict):name:stryear:intclassMovie(MovieBase,total=False):based_on:str

NowMovie has required keysname andyear, whilebased_oncan be left out when constructing an object. ATypedDict with a mix of requiredand non-required keys, such asMovie above, will only be compatible withanotherTypedDict if all required keys in the otherTypedDict are required keys in thefirstTypedDict, and all non-required keys of the otherTypedDict are also non-required keysin the firstTypedDict.

Read-only items¶

You can usetyping.ReadOnly, introduced in Python 3.13, ortyping_extensions.ReadOnly to mark TypedDict items as read-only (PEP 705):

fromtypingimportTypedDict# Or "from typing ..." on Python 3.13+fromtyping_extensionsimportReadOnlyclassMovie(TypedDict):name:ReadOnly[str]num_watched:intm:Movie={"name":"Jaws","num_watched":1}m["name"]="The Godfather"# Error: "name" is read-onlym["num_watched"]+=1# OK

A TypedDict with a mutable item can be assigned to a TypedDictwith a corresponding read-only item, and the type of the item canvarycovariantly:

classEntry(TypedDict):name:ReadOnly[str|None]year:ReadOnly[int]classMovie(TypedDict):name:stryear:intdefprocess_entry(i:Entry)->None:...m:Movie={"name":"Jaws","year":1975}process_entry(m)# OK

Unions of TypedDicts¶

Since TypedDicts are really just regular dicts at runtime, it is not possible touseisinstance checks to distinguish between different variants of a Union ofTypedDict in the same way you can with regular objects.

Instead, you can use thetagged union pattern. The referencedsection of the docs has a full description with an example, but in short, you willneed to give each TypedDict the same key where each value has a uniqueLiteral type. Then, check that key to distinguishbetween your TypedDicts.

Inline TypedDict types¶

Sometimes you may want to define a complex nested JSON schema, or annotatea one-off function that returns a TypedDict. In such cases it may be convenientto use inline TypedDict syntax. For example:

deftest_values()->{"width":int,"description":str}:return{"width":42,"description":"test"}classResponse(TypedDict):status:intmsg:str# Using inline syntax here avoids defining two additional TypedDicts.content:{"items":list[{"key":str,"value":str}]}

Inline TypedDicts can also by used as targets of type aliases, but due toambiguity with a regular variables it is only allowed for (newer) explicittype alias forms:

fromtypingimportTypeAliasX={"a":int,"b":int}# creates a variable with type dict[str, type[int]]Y:TypeAlias={"a":int,"b":int}# creates a type aliastypeZ={"a":int,"b":int}# same as above (Python 3.12+ only)

Also, due to incompatibility with runtime type-checking it is strongly recommendedtonot use inline syntax in union types.