dataclasses

dataclasses (stdlib since 3.7) generates common method boilerplate for classes that primarily hold data. They are the default choice for internal records before reaching for full ORM models.

Recipe

from dataclasses import dataclass, field
 
@dataclass
class User:
    id: int
    name: str
    tags: list[str] = field(default_factory=list)

When to reach for this:

• Domain events and DTOs inside application layers
• Immutable config/value objects (frozen=True)
• Nested structures with readable __repr__ for debugging
• Replacing tuples where field names help readability

Working Example

from dataclasses import dataclass, field
 
@dataclass(frozen=True)
class Money:
    amount: int
    currency: str
 
    def __post_init__(self) -> None:
        if self.amount < 0:
            raise ValueError("amount must be non-negative")
 
@dataclass
class Order:
    id: int
    lines: list[Money] = field(default_factory=list)
 
    def total(self) -> Money:
        if not self.lines:
            return Money(0, "USD")
        currency = self.lines[0].currency
        amount = sum(line.amount for line in self.lines)
        return Money(amount, currency)
 
if __name__ == "__main__":
    order = Order(1, [Money(100, "USD"), Money(50, "USD")])
    print(order)
    print(order.total())

What this demonstrates:

• frozen=True prevents attribute reassignment after creation
• __post_init__ validates invariants post-__init__
• default_factory=list creates fresh list per instance
• Methods coexist with generated dataclass methods

Deep Dive

How It Works

• Decorator transforms class - Adds methods based on fields and flags at class creation time.
• Field ordering - Fields without defaults must precede fields with defaults.
• KW_ONLY - field(kw_only=True) forces keyword passing for late fields (3.10+).
• slots - @dataclass(slots=True) combines dataclass with __slots__ (3.10+).
• replace - dataclasses.replace(obj, amount=200) functional updates on frozen instances.

Useful Flags

Python Notes

from dataclasses import asdict, astuple
 
payload = asdict(order)  # shallow dict - nested dataclasses recurse
coords = astuple(point)

Gotchas

• Mutable default list - tags: list = [] still broken without field. Fix: field(default_factory=list).
• Inheritance field ordering - Subclass defaults tricky across MRO. Fix: Keep hierarchies shallow or use composition.
• asdict deep mutables - Copies structure but nested mutables still alias if not dataclasses. Fix: Know shallow vs deep needs.
• frozen with mutable fields - Frozen prevents rebinding lines but list inside still mutable. Fix: Tuple fields or immutable types.
• Comparing to dict - Dataclass instance != dict even if fields match. Fix: Convert explicitly for JSON APIs.

Alternatives

FAQs

Related

• Dunder / Magic Methods - generated methods
• Properties & Descriptors - computed fields
• TypedDict & NamedTuple - typing alternatives
• Immutability & Hashability - frozen objects

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.