What does typing.TypedDict express that a plain dict[str, str] annotation cannot?

## The problem it solves A great deal of real Python moves dictionaries whose key names are fixed and known in advance: a decoded JSON payload, a config blob, a bundle of keyword arguments, a row handed to a library that wants a mapping. Annotating one of those as `dict[str, str]` says almost nothing useful. It commits every value to the same type — usually forcing `dict[str, Any]`, which turns checking off altogether — and it says nothing at all about *which* keys exist, so a typo in a key name is invisible until it raises `KeyError` in production. `typing.TypedDict` (PEP 589, added in Python 3.8) closes that gap. It describes a dictionary type by listing its keys and giving each key its own value type. ```python from typing import TypedDict class Ticket(TypedDict): id: int title: str priority: str ``` ## What a checker enforces Against that declaration, a static type checker will flag a dict literal that omits a required key, a literal that carries a key the class never declared, a value whose type does not match the declared one, and a read or write of a key that is not part of the shape. `ticket["prioroty"]` is an error at check time rather than a crash at run time, which is the entire point of the construct. Compatibility between `TypedDict` types is **structural**: a checker compares keys and value types, not class names. Two `TypedDict` classes that declare the same keys with the same types are mutually assignable, which is convenient for describing the same wire shape in two places and a limitation if you actually wanted two distinguishable types. ## What happens at runtime Nothing. Calling the class returns a plain `dict`: ```python t = Ticket(id=7, title="queue backlog", priority="high") type(t) # <class 'dict'> ``` The object has no special class, no `__slots__`, no attribute access — `t.id` raises `AttributeError`, you write `t["id"]`. Values are not coerced and not checked: `Ticket(id="T-42", priority=7)` builds happily, and so does a call that omits a required key. There is deliberately no runtime cost, and equally no runtime safety net. Because there is no class to test against, `isinstance(t, Ticket)` raises `TypeError: TypedDict does not support instance and class checks`. The introspection that *is* available comes from `typing`: `typing.is_typeddict(Ticket)` returns `True`, and `typing.get_type_hints(Ticket)` returns the declared key-to-type mapping. Those are the hooks a framework or a hand-rolled boundary validator uses. ## The functional form A class body cannot spell a key that is not a valid Python identifier, and wire formats are full of such keys. The functional form takes a dictionary of fields: ```python Row = TypedDict("Row", {"ticket-id": int, "from": str}) ``` An older keyword-argument form, `TypedDict("Row", id=int)`, was deprecated in 3.11 and **removed in Python 3.13** — it now raises `TypeError`. Passing no fields at all is deprecated too; pass `{}` for an empty shape. ## Nesting and inheritance Value types can themselves be `TypedDict` classes, which is how nested JSON is described, and a `TypedDict` may inherit from one or more other `TypedDict` classes to merge their keys. What it may not do is mix in an ordinary base class: `class Bad(Ticket, dict)` raises `TypeError: cannot inherit from both a TypedDict type and a non-TypedDict base class`. This is the usual first surprise for someone who expects `TypedDict` to behave like a normal class — it is a *type-level* description of a dictionary, not a class hierarchy. Nesting is worth a line of its own, because it is how most real payloads are described. A key's declared type can be another `TypedDict`, and checking then applies all the way down: ```python class Reporter(TypedDict): name: str email: str class Ticket(TypedDict): id: int reporter: Reporter # nested shape, checked to the leaf ``` Reading `ticket["reporter"]["emial"]` is an error at check time, two levels deep, which is exactly the class of typo that otherwise surfaces as a `KeyError` in production. ## Where it fits Reach for `TypedDict` when the data genuinely is and stays a dictionary and you want its shape checked for free. Since the checking is static, keep it on the trusted side of a boundary: decode and validate untrusted input first, then let the `TypedDict` document and check the shape everywhere inward. Later versions added per-key modifiers on top of the basic idea — `Required` and `NotRequired` in 3.11, `ReadOnly` in 3.13 — but the core contract is the one above: named keys, per-key types, checked by a tool, invisible at run time.