Dataclasses for plain records

What it is

The @dataclass decorator reads the class's annotated attributes and generates __init__, __repr__, __eq__ and, on request, ordering and hashing methods. Options include frozen=True (assignments raise, instances are hashable if fields are), slots=True (no per-instance __dict__), kw_only=True (keyword-only constructor) and field(default_factory=list) for mutable defaults.

Why it matters

Records with several fields written by hand accumulate inconsistencies between constructor, representation and equality. A dataclass declares the shape once, keeps type hints as documentation, and integrates with tooling that understands annotations.

How to apply

• Use dataclasses for data that is passed around and compared; use plain classes when behaviour dominates.
• Make value objects frozen=True so they can be dictionary keys and cannot be mutated by accident.
• Validate or normalise in __post_init__; keep it light, or validate at the boundary with a schema library instead.
• Convert with dataclasses.asdict / astuple for serialisation, remembering that they recurse into nested dataclasses.

Pitfalls

A mutable default such as [] is rejected by the decorator; a default of a mutable object created elsewhere is shared by all instances. Inheritance with defaults must keep non-default fields before default ones unless kw_only is used. Dataclasses do not validate types at run time.