Skip to content

typed dict literals

a dict-shaped expression in an annotation position is a TypedDict:

def get_user() -> {"name": str, "age": int}: ...

shape identity ignores key order — {"a": int, "b": str} and {"b": str, "a": int} are the same type

closed by default, **: T for extra items

dict literal types are closed by default, so extra keys are rejected. a **: T entry switches that to "extra keys allowed, must match T":

a: {"key": int}              # closed — extra keys rejected
b: {"key": int, **: str}     # extra keys allowed, must be str

nested shapes

nested typed-dict literals work transparently:

addr: {"city": str, "zip": str}
user: {"name": str, "address": {"city": str, "zip": str}}

type variables

a dict literal type is not a generic class of its own, but its fields can name the type variables of the scope it is written in. specializing that scope substitutes them:

class B[T]:
    def get(self) -> {"a": T}: ...

def f(b: B[int]):
    reveal_type(b.get())  # {"a": int}

a keyword-variadic pack splices its whole field list in with {**Kwargs}

display

a dict literal type reads back as its shape rather than as the generated class name, with keys quoted the way the source spells them and fields ordered by key:

def f(x: {"name": str, "age": int}):
    reveal_type(x)  # {"age": int, "name": str}

a pack that hasn't been specialized yet shows as the pending splice — {"tag": int, **Kwargs@A}

lowering

each shape is hoisted to one module-level TypedDict class. those classes land ahead of everything the module defines, and a field can name a class declared later, so field types are emitted as forward references:

class _TypedDict_<hash>(TypedDict, closed=True):
    name: "str"
    age: "int"

closed= and extra_items= are PEP 728, which typing.TypedDict takes from python 3.15, and a module for 3.15 declares its classes on it. a module for an older python needs no typing_extensions for them: its classes are made by typing.TypedDict all the same, so typing.is_typeddict and typing.get_type_hints read them as they would any other, and they record what 3.15 would:

  • __closed__ is True for a closed class and None for one with **: T
  • __extra_items__ is T for one with **: T. a closed class has none, since the NoExtraItems 3.15 gives it does not exist before 3.15
  • __readonly_keys__ is empty and __mutable_keys__ holds every key, below 3.13 too

a checker reading the generated python for an older python, or a generated stub for one, reads the base as typing_extensions.TypedDict

a field naming a type parameter of the generic the literal was written in reads that parameter from module scope, where typing.get_type_hints resolves it, and a field whose type is another typed dict literal, an anonymous named tuple or an inline protocol names that type's class

a {**Kwargs} splice has no fields to erase to — they are only known at the specialization site, and python erases type arguments anyway — so it lowers to extra_items="object"

scope

the rewrite fires only in annotation positions — function parameter and return annotations, variable annotations, and nested type arguments. dict expressions in value positions (real dicts) are never affected