Python TypedDict - SyntBlaze

TypedDict is a type hint construct from the typing module used to specify the expected types of values associated with specific string keys in a dictionary. It provides structural type information to static type checkers (such as mypy or pyright) without altering the runtime behavior of the dictionary. At runtime, an instance of a TypedDict is a standard Python dict, and no type validation or enforcement occurs.

Syntax

TypedDict can be defined using two syntaxes: the class-based syntax (preferred for readability) and the alternative assignment syntax (required when dictionary keys are not valid Python identifiers or are reserved keywords).

from typing import TypedDict


# Class-based syntax
class Point2D(TypedDict):
    x: int
    y: int
    label: str


# Alternative assignment syntax
Point3D = TypedDict('Point3D', {'x': int, 'y': int, 'z': int, 'in-bounds': bool})

Runtime Behavior

TypedDict is strictly a static typing tool subject to type erasure. Instantiating a TypedDict creates a standard dictionary. It does not enforce types, restrict extra keys, or provide default values during execution.

# Static type checkers will flag the incorrect type for 'y' and the missing 'label'.

# However, the Python interpreter will execute this without raising an exception.
p: Point2D = {'x': 10, 'y': 'twenty'} 

print(type(p))  # Output: <class 'dict'>

Totality and Key Presence

By default, a TypedDict is total, meaning every key defined in the type definition must be present in the dictionary instance. You can modify this behavior at the class level using the total parameter, or at the granular key level using Required and NotRequired (introduced in Python 3.11 via PEP 655).

Class-Level Totality

Setting total=False makes all keys in the dictionary optional.

class Config(TypedDict, total=False):
    timeout: int
    retries: int


# Valid: Neither key is strictly required by the type checker
c: Config = {}

Key-Level Totality (Python 3.11+)

NotRequired marks specific keys as optional within a total TypedDict. Conversely, Required marks specific keys as mandatory within a non-total (total=False) TypedDict.

from typing import TypedDict, NotRequired, Required

class User(TypedDict):
    username: str
    email: str
    bio: NotRequired[str]  # Optional key

class PartialUpdate(TypedDict, total=False):
    username: str
    email: str
    id: Required[int]      # Mandatory key

Inheritance

TypedDict supports multiple inheritance, allowing the composition of complex dictionary types from simpler ones. A subclass inherits all key-type pairs from its base classes. If multiple base classes define the same key, the type annotations for that key must match exactly, otherwise static type checkers will report a conflict.

class BaseItem(TypedDict):
    id: int
    name: str

class PhysicalItem(BaseItem):
    weight_kg: float


# PhysicalItem structurally expects: {'id': int, 'name': str, 'weight_kg': float}
item: PhysicalItem = {'id': 101, 'name': 'Anvil', 'weight_kg': 45.5}