Dataclasses — `@dataclass` decorator, `__post_init__`: Visual walkthrough

Step 0 — The three words we must earn first

Before any pictures, three plain-word definitions. Every later step uses these.

Everything below is the story of how the decorator turns fields into dunders.

Step 1 — The raw material: a class body with sticky notes

WHAT. We start from the class you actually type. Nothing has run yet.
@dataclass
class Point:
    x: float
    y: float
    label: str = "P"
WHY start here. The decorator is a function that receives this class after Python has read its body. So the only thing it has to work with is what's written between the colons — the annotations and any default values. If we understand exactly what data is sitting there, we can predict everything the robot produces.

PICTURE. Each line becomes a labelled slot. The accent (red) marks the one line with a default value (label = "P") — remember it, it changes the assembly later.

Figure — Dataclasses — `@dataclass` decorator, `__post_init__`

Read the picture as: three sticky notes (x, y, label), each with a type, and one of them (red) also carrying a pre-filled value.

Step 2 — Collect the fields, in order

WHAT. The decorator reads Point.__annotations__. This is an ordered dictionary:

$__annotations__= {1st field "x" : float, 2nd field "y" : float, 3rd field "label" : str}$

Every term: the keys ("x", "y", "label") are the field names; the values (float, str) are the type labels the decorator uses only to know "yes, this is a field."

WHY order matters. The generated __init__ will list its parameters in this exact order. If the dict were unordered, Point(1, 2) wouldn't know whether 1 is x or y. Since Python 3.7 the annotation dict preserves source order for free — that is why the field order equals the line order you typed.

PICTURE. The three sticky notes drop onto a numbered conveyor belt. The number is the parameter position they will occupy.

Step 3 — Split each field: does it have a default?

WHAT. Walking the belt left to right, the robot asks one yes/no question per field: "Is there a class-level value for this name?"

x → no value → required parameter.

y → no value → required parameter.

label → value "P" exists → optional parameter with default "P".

WHY. Python's rule for function parameters is iron-clad: every parameter with a default must come after every parameter without one. So the split isn't cosmetic — it decides whether the class is even legal.

PICTURE. The belt splits into two lanes: black "required" lane (no fill) and red "has default" lane. label moves to the red lane. Notice all reds sit to the right of all blacks.

Common mistake Default before non-default

@dataclass
class Bad:
    x: int = 0
    y: int        # TypeError at class creation!

Why it feels fine: you just wanted x to have a default. But now the required y sits after the defaulted x, which the generated __init__(self, x=0, y) cannot express. Python raises TypeError: non-default argument 'y' follows default argument. Fix: put defaulted fields last, or give y a default too.

Step 4 — Weld the parameters into an `init`

WHAT. The robot now writes a real function as text and compiles it. Conceptually it emits:

$def __init__(the new object self, req x, req y, optional label="P") :$ $copy arg \to attribute self.x = x; self.y = y; self.label = label$

Every term: self is the fresh, empty object being filled; each self.name = name copies the incoming argument onto the object so it survives after __init__ returns.

WHY generate real code (instead of looping over fields at runtime every time)? Because this welds once, at class-creation time, into a plain fast function. Every Point(...) call afterwards is as cheap as a hand-written __init__.

PICTURE. Arrows carry each belt slot into a matching parameter box; then a second arrow set copies parameter → self. attribute. The red arrow is the defaulted label, showing its default value riding along.

Step 5 — The degenerate default: mutable defaults are refused

WHAT. Suppose a field's default is a list: items: list = []. The robot stops and raises ValueError at class-creation time.

WHY. A default value written in the class body is created once and would be shared by every instance — change one cart's list, every cart changes. This is the classic mutable-default trap, and dataclasses refuse it outright instead of letting it bite you later. The fix is a factory:

$a callable field(default_factory=list) called once per __init__fresh list per object []$

Term-by-term: default_factory holds a function (here list); the generated __init__ calls it anew on every construction, so each object gets its own independent list.

PICTURE. Left: one shared red list wired to three objects (the danger). Right: three separate red lists, one per object (the factory fix).

Step 6 — Two free bonus dunders: `repr` and `eq`

WHAT. Still at class-creation time, the robot also welds:

__repr__ → returns the string "Point(x=1, y=2, label='P')".

__eq__ → compares the tuple of fields:

$this object’s fields (se l f . x, se l f . y, se l f . l ab e l) == other object’s fields (o t h er . x, o t h er . y, o t h er . l ab e l)$

WHY a tuple? Python already knows how to compare tuples element by element. By packing the fields into a tuple, the robot gets correct field-by-field equality for free, in one line, with no manual loop.

WHY this beats a plain class: a plain class's default __eq__ compares identity (are these the same object in memory?), so two identical-looking points would be "not equal". The generated one compares values.

PICTURE. Two separate memory boxes (different addresses) whose field tuples are identical; the red == bridge says "equal by value" even though the addresses differ.

Step 7 — The final weld point: `__post_init__` runs LAST

WHAT. If you defined a method named __post_init__, the generated __init__ calls it as its very last line, after every self.name = name assignment. This is the hook for validation and for derived fields (fields you compute, not receive).

$__init__: assign all fields first self.width=...; self.height=... ⟶ your code, last self.__post__init__()$

WHY last? Your derived logic needs the plain fields already set. In area = width * height, both self.width and self.height must already exist — and they do, because assignment happens before the call. A field marked field(init=False) is skipped in the parameter list precisely so you can fill it here.

PICTURE. A timeline arrow: assignments fill in one by one (black), then the red __post_init__ box fires at the end, reading the black values to compute the red derived value.

Worked example Trace it once, concretely

@dataclass
class Rectangle:
    width: float
    height: float
    area: float = field(init=False)
    def __post_init__(self):
        self.area = self.width * self.height
 
r = Rectangle(3, 4)   # width=3, height=4 assigned; then area = 3*4 = 12
r.area                # 12.0

Rectangle(3, 4) — only two args, because area is init=False. After assignment, __post_init__ computes area = 12.

Step 8 — The frozen edge case: same pipeline, one welded lock

WHAT. With @dataclass(frozen=True) the robot replaces every self.x = x with a locking assignment and refuses all later writes via FrozenInstanceError. It also welds a __hash__.

WHY a hash appears only when frozen. A hash is a fingerprint used by dicts and sets. If a field could change, the fingerprint would go stale and the object would get "lost" inside a set. Mutable dataclasses therefore set __hash__ = None (unhashable). Freeze the fields → fingerprint can't go stale → Python safely generates __hash__. This is the Immutability and Hashing rule in action.

THE CATCH inside __post_init__. The lock blocks all writes, even your derived-field write. To set one derived field you must bypass the lock explicitly:

$low-level write object.__setattr__(se l f, field name "area", computed value)$

PICTURE. A padlocked object: normal self.x = ... arrows bounce off (crossed out), but the single red object.__setattr__ arrow slips through the one keyhole.

The one-picture summary

The whole pipeline on one belt. Fields collected → defaults split → __init__ welded → __repr__/__eq__ welded → __post_init__ fires last. Mutable-default and frozen are the two side-doors.

Recall Feynman retelling — explain the whole walkthrough in plain words

A robot stands at a conveyor belt. You hand it a class body full of sticky notes (x: float, y: float, label = "P"). The robot reads the notes in order (Step 2), sorts them into "you must give me this" versus "I have a default" (Step 3), and then welds a real __init__ function that copies each argument onto the new object (Step 4). If any default is a shared mutable thing like [], it slams the emergency stop and tells you to use a factory instead (Step 5). It throws in two freebies: a nice printout (__repr__) and a value-based equality check that packs the fields into a tuple (Step 6). If you left a note called __post_init__, it runs that last of all, once every field is already set, so you can validate or compute extras like area (Step 7). And if you asked for frozen=True, it welds a padlock on the object plus a stable fingerprint (__hash__) so it can live in sets — with one tiny keyhole (object.__setattr__) for derived fields (Step 8). That is the entire magic: fields in, dunders out, your checklist runs at the very end.

Recall Quick self-test

Predict the generated __init__ signature of Point ::: def __init__(self, x: float, y: float, label: str = "P") — field order, defaults last. Why does the field order in __init__ equal the source order? ::: __annotations__ preserves insertion order, and the decorator walks it in that order. When exactly does __post_init__ run? ::: As the last statement of the generated __init__, after every field is assigned. Why can only frozen dataclasses be dict keys? ::: Their fields can't change, so __hash__ stays valid; mutable ones set __hash__ = None.

Related: NamedTuple vs Dataclass vs TypedDict · Type Annotations in Python · OOP Fundamentals