TypedDict, NamedTuple, Literal and Final

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

`TypedDict`

A dictionary type with named keys and a type for each value.

`NotRequired`

Marks a TypedDict key that may be missing.

`Literal`

A type that allows only the listed values, like Literal["a", "b"].

`NamedTuple`

A tuple whose items have names and types.

`Final`

A label for a name that should never be reassigned.

`Self`

A hint meaning "an instance of the same class as this one".

`Annotated`

A type plus extra notes that libraries can read; checkers ignore the notes.

`@override`

A decorator marking that a method replaces one from a parent class.

Tag (discriminator)

A field such as role whose value tells you which shape of data you have.

1. 1

   Add an optional key

   In the first example, add tool_call_id: NotRequired[str] to Message and print sorted(Message.__optional_keys__). Both optional keys appear.

2. 2

   Chain a method

   In the second example, change -> Self to -> Builder on add and run again. It still works at run time (Python ignores hints), but a checker would now reject .bold() after .add(...). Put Self back.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

from typing import override

class Animal:
    def speak(self) -> str:
        return "..."

class Cat(Animal):
    @override
    def spek(self) -> str:        # typo
        return "Meow"

print(Cat().speak())

1. 1

   **TypedDict** describes a dictionary (Topic 4.4) with known keys, each with its own type. It is how you label data that arrives as dictionaries, such as a chat message or a web API reply, without turning it into a class. You write it like a small class with one field per line: a role that is a str and a content that is a str.

2. 2

   At run time a TypedDict is a plain dict (check with isinstance(msg, dict)), so nothing is enforced. The checker, though, rejects a missing key, a misspelled key or a wrong value type.

3. 3

   By default every key of a TypedDict is required. NotRequired[str] (Python 3.11) marks one key as optional. Writing total=False on the class makes every key optional, and Required[...] then marks the ones that must stay. The class keeps the two sets in __required_keys__ and __optional_keys__.

4. 4

   **Literal** allows only specific values: Literal["user", "assistant", "system"]. This is exactly how chat-message roles or modes such as "fast" and "slow" are described. Because the allowed list is known, a checker can warn about the typo "asistant" and, with assert_never (Topic 10.8), can tell you when you forgot to handle one of them.

5. 5

   **NamedTuple** is a tuple (Topic 4.3) whose positions have names and types. You write class Point(NamedTuple) with fields x: int and y: int = 0, one per line. It unpacks like a tuple, indexes like a tuple, and reads like an object (p.x). It cannot be changed after creation (immutable), it is light, and it suits small records.

6. 6

   Dataclasses (Topic 8.8) are the choice when you need your own methods, changeable fields or inheritance.

7. 7

   **Final** tells the checker that a name must not be reassigned: MAX_TOKENS: Final = 4096. Python itself still lets you reassign it (there are no real constants in Python); the checker will object. The same module also has @final to forbid subclassing (building a new class on top of this one, Topic 8.5) or overriding.

8. 8

   Three more helpers.

9. 9

   **Self** (3.11) means "the same class as the object that called the method". A method that returns self so calls can be chained (a.add().add()) then keeps the exact class.

10. 10

    **Annotated[int, "years"]** attaches extra notes (metadata) to a type without changing the type. Checkers ignore the notes; libraries read them (Pydantic uses them for rules like Field(ge=0), meaning "greater than or equal to 0").

11. 11

    **@override** (3.12) marks a method that is meant to replace a method of the parent class. A decorator is a line starting with @ above a function that adds behaviour to it (Topic 9.6). The checker fails if the parent has no such method, which catches typos and renames.

• ↔

  TypedDict versus dataclass versus Pydantic. TypedDict labels data you already hold as dicts (JSON) with no conversion. A dataclass gives behaviour. Pydantic validates. Pick by where the data comes from and what you need to do with it.

• ↔

  Literal is strict and brittle. Adding a new allowed value touches every place that handles them, which is the point (exhaustive checks) but costs effort.

• ↔

  Hints only. None of these tools stops a wrong value while running; they move mistakes from production to your editor.

• Done when you can describe a dictionary's shape with a TypedDict, including an optional key.

• Done when you can restrict a value with Literal.

• Done when you can write a NamedTuple and say how it differs from a dataclass.

• Done when you can use Final, Self and @override and say what they do at run time.

• Done when you can read extra metadata from Annotated.