When does __post_init__ run in a Python dataclass, and what is it for?

## What the decorator actually writes When `@dataclass` runs, it inspects the class's annotations, builds a descriptor-free `Field` record for each annotated name, and compiles a genuine `__init__` (plus `__repr__` and `__eq__`, unless switched off) from generated source. The body of that constructor does exactly one kind of thing: it assigns each field, in declaration order, from its parameter, from its default, or from a `default_factory` call. That is all. Since you did not write the constructor, you have nowhere to put the other two jobs a constructor normally does — checking that the arguments make sense together, and deriving values from them. `__post_init__` is the seam the module leaves for both. ## The exact contract If the class has an attribute named `__post_init__` **at the moment the decorator runs**, the generated `__init__` ends with a call to `self.__post_init__(...)`. The call happens after every field has been assigned, so the instance is fully populated by then. Its parameters are `self` plus one positional parameter per `InitVar` pseudo-field, in declaration order; regular fields are *not* passed, because they are already attributes. The return value is thrown away. Beyond that there is no magic: it is an ordinary method, and an exception raised inside it propagates straight out of the constructor, so a failed object never escapes to the caller. ```python from dataclasses import dataclass, field @dataclass class Rect: width: float height: float area: float = field(init=False) def __post_init__(self) -> None: if self.width <= 0 or self.height <= 0: raise ValueError("sides must be positive") self.area = self.width * self.height ``` ## Two conditions people miss **It must exist at decoration time.** The constructor's source is compiled once, when the decorator runs; the `self.__post_init__()` line is emitted only if the attribute is found then. Attaching the method to the class afterwards has no effect at all — instances are built by a constructor that simply does not contain the call. **It only lives in a generated constructor.** `@dataclass(init=False)` tells the decorator not to write `__init__`, and a hand-written `__init__` in the class body is likewise left alone. In both cases nothing calls `__post_init__`, and the usual symptom is a derived attribute that is missing or stale rather than a loud error. If you write your own constructor and still want the hook, call it explicitly. By the same logic, `copy.deepcopy` and `pickle` do **not** re-run it: both restore instance state directly rather than calling `__init__`, so any normalization that lives only in `__post_init__` is simply carried over from the original object, not recomputed. ## The two idiomatic uses **Validation.** Raise `ValueError` (or `TypeError` for a wrong kind of argument) on a combination the type cannot represent — a negative size, an end before a start, a currency mismatch. This is the single construction-time gate a dataclass gets. **Derived fields.** Declare the computed attribute with `field(init=False)` so it is not a constructor parameter, then assign it in `__post_init__`. A field declared `init=False` with no default is never assigned by the generated `__init__`; if `__post_init__` forgets it, the attribute does not exist and even `repr()` fails with `AttributeError: 'Rect' object has no attribute 'area'`. That crash is a feature — it is loud, and it happens on the first use. ## Inheritance Nothing chains automatically. `self.__post_init__(...)` is one attribute lookup, so the most-derived definition wins and the base's version runs only if the subclass calls `super().__post_init__()`. Because the subclass's generated `__init__` assigns the inherited fields as well as its own, the base's checks are silently skipped when that call is forgotten — a common bug in a small hierarchy of value types. ## What it is not It is not a replacement `__init__`: it cannot change the constructor's signature, cannot decide *which* fields exist, and cannot return a different object. It is not a validation framework either — it fires exactly once, at construction, and a plain dataclass stays mutable afterwards, so a later attribute assignment sails past every check it performs. And on a frozen dataclass, `self.attr = value` inside `__post_init__` raises `dataclasses.FrozenInstanceError` like any other assignment; the escape hatch there is `object.__setattr__`. ## What the hook can already see Every field is assigned before the call, defaults included, and that covers the less obvious cases. A field declared `field(init=False, default_factory=list)` is still populated by the generated constructor — `init=False` removes it from the parameter list, not from the assignment — so `__post_init__` can append to the list it finds rather than creating one. A field declared `init=False` with no default at all is the only gap: nothing assigns it, and the hook must, or the attribute simply does not exist. It is also worth remembering that this is a per-instantiation method call, so anything expensive inside it — reading a file, compiling a pattern, hitting a network — is paid on every construction, including the constructions a test suite performs thousands of times. Keep the hook to cheap checks and arithmetic, and push real work into a factory the caller invokes deliberately.