Python · Lesson 6
Dataclasses, Enums, Pattern Matching and Type Hints
Model data with @dataclass (defaults, frozen, order, slots, __post_init__), NamedTuple and Enum, take it apart with match, and describe it with type hints, generics, Protocol, TypedDict and Literal that tools check and the runtime ignores.
In short
@dataclass: fields in, methods outdefault_factoryfor mutable defaults,__post_init__to validatefrozen,order,slots,kw_onlyas neededStrEnumfor statuses,matchfor shapes- Hints are checked by tools, never at runtime
Most backend code moves data around: a request body becomes an order, an order becomes a row, a row
becomes an event. In TypeScript you'd write an interface or a type; in C# a record. Python's answer
is the dataclass: you list the fields with type hints, and Python writes __init__, __repr__ and
__eq__ for you. Around it sit a few tools that work well together: Enum for fixed sets of values,
match for taking data apart by shape, and type hints that describe it all for your editor and for mypy.
The one idea to hold on to: type hints are not checked when the code runs. They are documentation that
tools can verify. A dataclass with price: int happily stores a string. Validation is your job, and this
topic shows where it goes.
Every python snippet has a ▶ Try button. Predict the output, then run it.
@dataclass: a class from a list of fields
from dataclasses import dataclass
@dataclass
class Order:
id: int
customer: str
total_cents: int = 0
a = Order(1, "ann", 4200)
b = Order(1, "ann", 4200)
print(a)
print(a == b, a is b)
print(Order(2, "bob"))
The decorator reads the annotated class attributes, in order, and generates:
| Generated | What it does |
|---|---|
__init__ | Takes the fields as parameters, in order, with their defaults |
__repr__ | Order(id=1, customer='ann', total_cents=4200) |
__eq__ | Equal when the other object is the same class and all fields are equal |
Without the decorator, a == b would be False (plain objects compare by identity) and printing would
show <__main__.Order object at 0x...>. The class is still an ordinary class: add methods, properties and
class methods as usual.
Fields without defaults must come before fields with defaults, the same rule as function parameters. And the hints are only read, never enforced:
from dataclasses import dataclass
@dataclass
class Order:
id: int
customer: str
o = Order("not a number", 42) # no error: hints are not checked at runtime
print(o)
Mutable defaults: field(default_factory=...)
A default value is shared by every instance, so a mutable default would be one list for all orders (the
same trap as def f(items=[])). Dataclasses refuse it outright:
from dataclasses import dataclass, field
try:
@dataclass
class Cart:
items: list[str] = []
except ValueError as e:
print(e)
@dataclass
class Cart:
items: list[str] = field(default_factory=list)
a, b = Cart(), Cart()
a.items.append("book")
print(a, b)
default_factory is called once per instance. Any zero-argument callable works: list, dict, set,
lambda: {"retries": 3}, or a function that returns a new id. field(...) also takes repr=False (hide
a secret from logs), compare=False (leave a field out of == and ordering) and init=False (a field the
constructor doesn't take, usually computed in __post_init__).
post_init: validation and derived fields
The generated __init__ calls self.__post_init__() at the end, if you define it. That's the place to
validate, normalise and compute:
from dataclasses import dataclass, field
@dataclass
class LineItem:
sku: str
quantity: int
unit_cents: int
total_cents: int = field(init=False)
def __post_init__(self) -> None:
if self.quantity < 1:
raise ValueError(f"quantity must be at least 1, got {self.quantity}")
self.sku = self.sku.strip().upper()
self.total_cents = self.quantity * self.unit_cents
print(LineItem(" ab-1 ", 3, 250))
try:
LineItem("X", 0, 100)
except ValueError as e:
print("rejected:", e)
Validation in __post_init__ runs on construction only. Assigning item.quantity = -5 later is not
checked. If that matters, make the class frozen.
frozen=True: immutable value objects
frozen=True makes assignment to a field raise FrozenInstanceError (a subclass of AttributeError), and
it also generates __hash__, so instances work as dict keys and set members. This is the C# record or a
TypeScript Readonly<T> that is actually enforced:
from dataclasses import dataclass, FrozenInstanceError
@dataclass(frozen=True)
class Money:
cents: int
currency: str
price = Money(999, "EUR")
try:
price.cents = 0
except FrozenInstanceError as e:
print(type(e).__name__, "-", e)
print({Money(1, "EUR"), Money(1, "EUR"), Money(1, "USD")} == {Money(1, "EUR"), Money(1, "USD")})
Two details come up in reviews:
- To normalise a field in
__post_init__of a frozen class, go around the guard withobject.__setattr__(self, "currency", self.currency.upper()). That's the documented idiom. - Frozen is shallow. A frozen dataclass holding a
listcan still have that list mutated. Use atuple(orfrozenset) for collections inside value objects.
A plain @dataclass with eq=True (the default) sets __hash__ to None, so it can't go in a set at all.
That's deliberate: a hash that changes when a field changes would corrupt the set.
order=True: sorting by fields
order=True generates <, <=, > and >=, which compare instances as tuples of their fields, in
declaration order. Put the sort key first, and exclude fields that shouldn't count:
from dataclasses import dataclass, field
@dataclass(order=True)
class Task:
priority: int
seq: int
title: str = field(compare=False)
tasks = [Task(2, 1, "write docs"), Task(1, 3, "fix prod"), Task(1, 2, "page on-call")]
for t in sorted(tasks):
print(t.priority, t.seq, t.title)
That's exactly what heapq needs for a priority queue: the lowest priority first, and seq breaking ties
in arrival order. Note that compare=False also removes the field from ==.
slots=True and kw_only=True
from dataclasses import dataclass, KW_ONLY
@dataclass(slots=True)
class Point:
x: float
y: float
p = Point(1.0, 2.0)
try:
p.z = 3.0 # typo protection
except AttributeError as e:
print("AttributeError:", e)
@dataclass(kw_only=True)
class RetryPolicy:
attempts: int = 3
backoff_s: float = 0.5
print(RetryPolicy(attempts=5))
try:
RetryPolicy(5, 1.0)
except TypeError as e:
print("TypeError:", e)
@dataclass
class Request:
url: str
_: KW_ONLY
timeout_s: float = 10.0
verify: bool = True
print(Request("https://api.example.com", timeout_s=2.0))
slots=Truestores fields in fixed slots instead of a per-instance__dict__: less memory, faster attribute access, and assigning a misspelt attribute fails instead of silently creating it.kw_only=Truemakes every field keyword-only, soRetryPolicy(5, 1.0)can't mix up two numbers. The_: KW_ONLYmarker does it for the fields after it only. Keyword-only fields also lift the "defaults last" rule.
replace, asdict, astuple
from dataclasses import dataclass, replace, asdict, astuple, field
@dataclass(frozen=True)
class Address:
city: str
country: str
@dataclass(frozen=True)
class Customer:
name: str
address: Address
tags: tuple[str, ...] = field(default=())
c = Customer("Ann", Address("Lisbon", "PT"))
moved = replace(c, address=replace(c.address, city="Porto"))
print(moved)
print(c.address.city)
print(asdict(moved))
print(astuple(moved))
replace(obj, **changes)builds a new instance with some fields changed. It calls__init__, so__post_init__validation runs again. It's thewithexpression of C# records and{ ...obj, city }in TypeScript.asdictconverts recursively (nested dataclasses, lists and dicts) and copies as it goes, which makes it the first step of JSON serialisation:json.dumps(asdict(order)). There's no built-infromdict; the Load typed config exercise writes one.
NamedTuple: a tuple with field names
typing.NamedTuple creates an immutable tuple subclass with named fields. Use it when the value really is
a small tuple: a function returning two things, a row, a coordinate.
from typing import NamedTuple
class MinMax(NamedTuple):
low: int
high: int
def bounds(xs: list[int]) -> MinMax:
return MinMax(min(xs), max(xs))
r = bounds([4, 1, 9])
print(r, r.high, r[0])
low, high = r # unpacks like any tuple
print(low, high)
print(r == (1, 9)) # equal to a plain tuple!
print(r._replace(high=10), r._asdict())
That last comparison is the catch: a NamedTuple is a tuple, so it equals any tuple with the same items,
including a different NamedTuple type. A dataclass compares only with its own class.
| Mutable | Hashable | Equal to | Extras | |
|---|---|---|---|---|
@dataclass | yes | no | same class only | methods, __post_init__, field() |
@dataclass(frozen=True) | no | yes | same class only | the value-object choice |
NamedTuple | no | yes | any equal tuple | unpacking, indexing, _replace |
TypedDict | yes (it's a dict) | no | any equal dict | for JSON-shaped dicts, see below |
dict | yes | no | any equal dict | no names checked at all |
Enums: a fixed set of named values
from enum import Enum, StrEnum, IntEnum, auto
class Color(Enum):
RED = 1
GREEN = 2
class Status(StrEnum):
PENDING = auto() # auto() on a StrEnum gives the lowercased name
SHIPPED = auto()
class Priority(IntEnum):
LOW = 1
HIGH = 2
print(Color.RED, repr(Color.RED), Color.RED.name, Color.RED.value)
print(Color(2), Color["GREEN"]) # by value, by name
print([c.name for c in Color]) # members in definition order
print(Color.RED == 1, Status.PENDING == "pending", Priority.HIGH > Priority.LOW)
print(f"status={Status.SHIPPED}")
- A plain
Enummember equals only itself:Color.RED == 1isFalse. That's safer than C#, where an enum is an integer underneath and(Color)42is legal. StrEnum(3.11+) andIntEnummembers are strings and ints, so they compare equal to their values, serialise to JSON as plain values, and drop into f-strings cleanly.StrEnumis the right choice for statuses stored in a database or sent over an API.- Looking up a bad value raises
ValueError(Color(7)), a bad name raisesKeyError(Color["BLUE"]). Wrap that in your own parser with a clearer message when the input comes from users. - Members are singletons, so
status is Status.PENDINGworks, and enums are hashable, which makes them good dict keys for lookup tables.
In TypeScript, the closest thing is a union of string literals, "pending" | "shipped", and the type hint
equivalent of that in Python is Literal["pending", "shipped"]. Use an Enum when the set of values
deserves a name, methods, or iteration.
Structural pattern matching: match
match (3.10+) compares a value against patterns, top to bottom, and runs the first case that matches.
It looks like a switch, but patterns can test shapes and pull values out at the same time, like C#'s
switch expressions with property patterns.
Literals, OR patterns, capture and wildcard
def http_status(code: int) -> str:
match code:
case 200 | 201 | 204:
return "ok"
case 404:
return "not found"
case 500 | 502 | 503:
return "server error"
case other:
return f"unexpected {other}"
print(http_status(201), "/", http_status(404), "/", http_status(418))
A bare name like other is a capture pattern: it always matches and binds the value. case _: is the
wildcard that matches without binding. There's no fallthrough, and if nothing matches, nothing happens
(no error), so add case _: when you want to handle "anything else".
The classic bug: a bare name never compares, it captures. To compare with a constant, use a dotted name
(Status.PENDING, http.HTTPStatus.OK) or a literal:
from enum import Enum
class Light(Enum):
RED = 1
GREEN = 2
RED = Light.RED
def wrong(light: Light) -> str:
match light:
case RED: # captures into a new variable named RED: matches everything
return "stop"
return "go"
def right(light: Light) -> str:
match light:
case Light.RED: # a dotted name is a value pattern: compared with ==
return "stop"
return "go"
print(wrong(Light.GREEN), right(Light.GREEN))
Sequence patterns
A list or tuple pattern matches a sequence of that length, and *rest collects the middle. This is how a
command parser reads:
def run(command: str) -> str:
match command.split():
case []:
return "empty"
case ["help"]:
return "usage: get KEY | set KEY VALUE | del KEY..."
case ["get", key]:
return f"get {key}"
case ["set", key, value]:
return f"set {key}={value}"
case ["del", first, *others]:
return f"delete {[first, *others]}"
case [verb, *_]:
return f"unknown command {verb!r}"
for line in ["", "help", "get user:1", "set user:1 ann", "del a b c", "drop table"]:
print(run(line))
Sequence patterns match lists and tuples (anything that is a collections.abc.Sequence) but not strings,
so case [first, *rest] never takes a string apart character by character.
Mapping patterns
A dict pattern lists the keys it needs. Unlike a sequence pattern, it matches dicts with extra keys too, which is what you want for JSON payloads that grow new fields:
def handle(event: dict) -> str:
match event:
case {"type": "user.created", "user": {"email": str(email)}}:
return f"welcome mail to {email}"
case {"type": "order.paid", "amount": int(cents)} if cents >= 100_000:
return f"large order: {cents / 100:.2f}, notify finance"
case {"type": "order.paid", "amount": int(cents)}:
return f"order paid: {cents / 100:.2f}"
case {"type": str(kind), **rest}:
return f"ignored {kind} with keys {sorted(rest)}"
case _:
return "not an event"
print(handle({"type": "user.created", "user": {"email": "ann@example.com", "id": 7}}))
print(handle({"type": "order.paid", "amount": 250_000}))
print(handle({"type": "order.paid", "amount": 1999, "currency": "EUR"}))
print(handle({"type": "order.paid", "amount": "1999"}))
print(handle([1, 2, 3]))
str(email) and int(cents) are class patterns: they check isinstance and bind the value. The
fourth payload has the amount as a string, so neither order.paid case matches and it falls through to the
generic case. The if after a pattern is a guard: the case matches only if the pattern matches and the
guard is true.
Class patterns with dataclasses
A class pattern checks the type and then matches attributes. Dataclasses define __match_args__ (the
fields in order), so positional sub-patterns work too:
from dataclasses import dataclass
@dataclass
class Circle:
radius: float
@dataclass
class Rect:
width: float
height: float
def describe(shape: Circle | Rect) -> str:
match shape:
case Circle(radius=0):
return "a point"
case Circle(r):
return f"circle r={r}"
case Rect(w, h) if w == h:
return f"square {w}"
case Rect(width=w, height=h):
return f"rect {w}x{h}"
for s in [Circle(0), Circle(2.5), Rect(3, 3), Rect(2, 5)]:
print(describe(s))
This is the Python version of a discriminated union: a union of dataclasses, and a match that handles
each one. A type checker can even tell you when a case is missing, if you end with
case _: assert_never(shape) from typing.
case Circle(radius=0) compares 0 == 0.0, which is true, so Circle(0.0) is a point too. And
case x as name, for example case Rect() as r, binds the whole matched value.
Type hints in practice
Annotations go on parameters, return values and variables. Modern syntax (3.10+) needs no imports for the common cases:
def average(xs: list[float]) -> float | None:
return sum(xs) / len(xs) if xs else None
scores: dict[str, list[int]] = {"ann": [90, 85]}
pair: tuple[str, int] = ("ann", 1)
anything: tuple[int, ...] = (1, 2, 3) # any length
maybe: str | None = None # Optional[str] in older code
print(average([1.0, 2.0]), average([]))
print(average.__annotations__)
| You want | Write | TypeScript | C# |
|---|---|---|---|
| A list of ints | list[int] | number[] | List<int> |
| A dict | dict[str, int] | Record<string, number> | Dictionary<string, int> |
| Maybe missing | str | None | string | undefined | string? |
| One of several types | int | str | number | string | (no direct equivalent) |
| A function | Callable[[int], str] | (n: number) => string | Func<int, string> |
| Exactly these values | Literal["asc", "desc"] | "asc" | "desc" | an enum |
| Opt out of checking | Any | any | dynamic |
Callable, Literal, Any, Protocol, TypedDict and Final come from typing (Callable is also in
collections.abc). Older code uses List[int], Optional[str] and Union[int, str] from typing; they
mean the same thing.
Hints are not checked at runtime
def add_tax(cents: int, rate: float) -> int:
return round(cents * (1 + rate))
print(add_tax(1000, 0.2))
print(add_tax(1000, True)) # a bool where a float belongs: no error
try:
add_tax("ab", 1)
except TypeError as e:
print("TypeError:", e)
The second call passes True as the rate, and since bool is a subclass of int, it quietly computes
1000 * 2. The third call passes a string, and nothing checks it at the call: "ab" * 2 is "abab", and
Python only fails one step later, inside the function, with a message about round. That's why teams run
a type checker in the editor and in CI:
$ mypy billing.py
billing.py:6: error: Argument 1 to "add_tax" has incompatible type "str"; expected "int" [arg-type]
mypy and pyright (the engine behind VS Code's Pylance) read the hints statically, like tsc reads
TypeScript, and never run the code. At runtime the hints are just data in __annotations__. Data from the
outside world (JSON, environment variables, CSV) needs real validation: __post_init__ checks, a parser
function, or a library like Pydantic, which reads the hints at runtime and enforces them.
Generics: TypeVar and the 3.12 syntax
A generic function keeps the link between input and output types. Python 3.12 added a syntax very close to TypeScript's:
from typing import TypeVar
T = TypeVar("T")
def first_old(xs: list[T]) -> T | None: # before 3.12
return xs[0] if xs else None
def first[T](xs: list[T]) -> T | None: # 3.12+
return xs[0] if xs else None
class Stack[T]:
def __init__(self) -> None:
self._items: list[T] = []
def push(self, item: T) -> None:
self._items.append(item)
def pop(self) -> T:
return self._items.pop()
type Pair[T] = tuple[T, T] # a generic type alias, 3.12+
s = Stack[int]()
s.push(1)
print(first(["a", "b"]), first_old([]), s.pop())
first(["a", "b"]) is typed str | None by the checker. Bounds and constraints read def f[T: Base] (T
must be a subtype of Base, like TypeScript's T extends Base or C#'s where T : Base) and
def f[T: (int, str)] (T is exactly one of these). At runtime the [int] in Stack[int]() changes
nothing; the generic parameters exist for the checker.
Protocol: structural typing
A Protocol describes what an object can do, and any class with matching methods satisfies it, without
inheriting from it. It's TypeScript's structural interfaces, in Python, and the typed version of duck
typing:
from typing import Protocol, runtime_checkable
@runtime_checkable
class Clock(Protocol):
def now(self) -> float: ...
class SystemClock:
def now(self) -> float:
return 1_700_000_000.0
class FakeClock:
def __init__(self) -> None:
self.t = 0.0
def now(self) -> float:
return self.t
def is_expired(created_at: float, ttl_s: float, clock: Clock) -> bool:
return clock.now() - created_at >= ttl_s
fake = FakeClock()
print(is_expired(0, 30, fake))
fake.t = 31
print(is_expired(0, 30, fake))
print(isinstance(SystemClock(), Clock), isinstance("text", Clock))
Neither clock mentions Clock, and both are accepted. In C# both would have to declare : IClock; here the
checker compares the shapes. That makes Protocols ideal for dependencies you want to fake in tests. Use an
abc.ABC instead when you want classes to opt in explicitly and share implementation.
@runtime_checkable allows isinstance checks, but they only test that the methods exist, not their
signatures.
TypedDict, Literal and Final
from typing import Final, Literal, NotRequired, TypedDict
MAX_PAGE_SIZE: Final = 100 # the checker rejects reassignment
class UserJson(TypedDict):
id: int
email: str
nickname: NotRequired[str]
SortOrder = Literal["asc", "desc"]
def list_users(order: SortOrder = "asc", limit: int = 20) -> list[UserJson]:
users: list[UserJson] = [{"id": 2, "email": "bo@example.com"}, {"id": 1, "email": "ann@example.com", "nickname": "A"}]
users.sort(key=lambda u: u["id"], reverse=order == "desc")
return users[: min(limit, MAX_PAGE_SIZE)]
rows = list_users("desc")
print(rows)
print(type(rows[0]).__name__)
TypedDictdescribes a dict with known keys, which is how JSON arrives. At runtime it is a plaindict(the last line printsdict), so it costs nothing, and the checker still catchesu["emial"]. It's the closest thing to a TypeScript object type for JSON.Literal["asc", "desc"]accepts exactly those values.list_users("random")is a checker error, and still runs.Finalmarks a constant the checker won't let you reassign. Python itself has noconst.
What to reach for
| Situation | Use |
|---|---|
| Domain data with behaviour or validation | @dataclass, with __post_init__ |
| Value objects, dict keys, config | @dataclass(frozen=True) (add slots=True for many instances) |
| A function returning several values | a NamedTuple or a plain tuple |
| A fixed set of states | StrEnum (or Enum when values don't matter) |
| JSON payloads you pass through | TypedDict |
"Anything with a now() method" | Protocol |
| Branching on the shape of data | match with class and mapping patterns |
The exercises put these together in job-shaped tasks: a product record with validation, a money value object, an order status machine, a priority job queue, a webhook parser, a generic repository, and a config loader that checks types at runtime because Python won't.
Practise this lesson
In the app: a short video, 7 exercises checked by real tests and a 12-question concept check. Free with a GitHub account.
Open in the app