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.

17 min read

In short

  • @dataclass: fields in, methods out
  • default_factory for mutable defaults, __post_init__ to validate
  • frozen, order, slots, kw_only as needed
  • StrEnum for statuses, match for 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

▶ Try
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:

GeneratedWhat 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:

▶ Try
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:

▶ Try
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:

▶ Try
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:

▶ Try
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 with object.__setattr__(self, "currency", self.currency.upper()). That's the documented idiom.
  • Frozen is shallow. A frozen dataclass holding a list can still have that list mutated. Use a tuple (or frozenset) 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:

▶ Try
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

▶ Try
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=True stores 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=True makes every field keyword-only, so RetryPolicy(5, 1.0) can't mix up two numbers. The _: KW_ONLY marker does it for the fields after it only. Keyword-only fields also lift the "defaults last" rule.

replace, asdict, astuple

▶ Try
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 the with expression of C# records and { ...obj, city } in TypeScript.
  • asdict converts 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-in fromdict; 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.

▶ Try
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.

MutableHashableEqual toExtras
@dataclassyesnosame class onlymethods, __post_init__, field()
@dataclass(frozen=True)noyessame class onlythe value-object choice
NamedTuplenoyesany equal tupleunpacking, indexing, _replace
TypedDictyes (it's a dict)noany equal dictfor JSON-shaped dicts, see below
dictyesnoany equal dictno names checked at all

Enums: a fixed set of named values

▶ Try
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 Enum member equals only itself: Color.RED == 1 is False. That's safer than C#, where an enum is an integer underneath and (Color)42 is legal.
  • StrEnum (3.11+) and IntEnum members are strings and ints, so they compare equal to their values, serialise to JSON as plain values, and drop into f-strings cleanly. StrEnum is 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 raises KeyError (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.PENDING works, 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

▶ Try
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:

▶ Try
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:

▶ Try
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:

▶ Try
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:

▶ Try
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:

▶ Try
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 wantWriteTypeScriptC#
A list of intslist[int]number[]List<int>
A dictdict[str, int]Record<string, number>Dictionary<string, int>
Maybe missingstr | Nonestring | undefinedstring?
One of several typesint | strnumber | string(no direct equivalent)
A functionCallable[[int], str](n: number) => stringFunc<int, string>
Exactly these valuesLiteral["asc", "desc"]"asc" | "desc"an enum
Opt out of checkingAnyanydynamic

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

▶ Try
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:

▶ Try
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:

▶ Try
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

▶ Try
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__)
  • TypedDict describes a dict with known keys, which is how JSON arrives. At runtime it is a plain dict (the last line prints dict), so it costs nothing, and the checker still catches u["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.
  • Final marks a constant the checker won't let you reassign. Python itself has no const.

What to reach for

SituationUse
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 valuesa NamedTuple or a plain tuple
A fixed set of statesStrEnum (or Enum when values don't matter)
JSON payloads you pass throughTypedDict
"Anything with a now() method"Protocol
Branching on the shape of datamatch 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