Python Dataclass: Practical Usage and Code Examples

Python's dataclass decorator reduces boilerplate for classes that mainly store data. Instead of writing __init__, __repr__, __eq__, and comparison methods by hand, you declare type-annotated fields and the decorator generates these methods. This article covers the core syntax, field defaults, immutability, ordering, inheritance, and runtime tradeoffs to consider before using dataclasses in production.

What Dataclasses Replace

Without dataclasses, a simple Point class requires manual methods:

class Point:
    def __init__(self, x: float, y: float):
        self.x = x
        self.y = y

    def __repr__(self):
        return f"Point(x={self.x!r}, y={self.y!r})"

    def __eq__(self, other):
        if not isinstance(other, Point):
            return NotImplemented
        return (self.x, self.y) == (other.x, other.y)

That's a lot of code for a simple value object. The dataclass version does the same with less repetition.

Defining a Dataclass

from dataclasses import dataclass

@dataclass
class Point:
    x: float
    y: float

The decorator reads the class attributes and generates __init__, __repr__, and __eq__. It also controls __hash__: a frozen dataclass with eq=True gets a field-based hash, while a non-frozen dataclass with eq=True sets __hash__ to None, making instances unhashable. You can still override any generated method if needed. The generated __init__ assigns fields in the order they are declared, and type hints are not enforced at runtime; they serve as documentation and for static analysis tools.

Field Defaults and Factories

You can assign defaults to fields:

@dataclass
class Rectangle:
    width: float = 1.0
    height: float = 1.0

But avoid mutable defaults like list or dict because they are evaluated once at class definition time and shared across all instances. Use field(default_factory=list) instead:

from dataclasses import field

@dataclass
class ShoppingCart:
    items: list = field(default_factory=list)

default_factory calls the given callable each time a new instance is created, giving each instance its own list. This is a common source of bugs when developers use items: list = [] directly.

Immutable Dataclasses with frozen=True

Set frozen=True to make instances immutable:

@dataclass(frozen=True)
class Point:
    x: float
    y: float

Attempting to assign to a field raises FrozenInstanceError. Frozen dataclasses with the default eq=True also generate __hash__ based on fields, making them usable as dictionary keys. If you need validation after initialization, define __post_init__:

@dataclass(frozen=True)
class PositiveNumber:
    value: float

    def __post_init__(self):
        if self.value <= 0:
            raise ValueError("value must be positive")

Note that __post_init__ runs after the generated __init__, so you can enforce invariants without writing a full constructor.

Ordering and Comparison

Set order=True to generate comparison methods (__lt__, __le__, __gt__, __ge__) that compare fields as tuples in declaration order:

@dataclass(order=True)
class Student:
    name: str
    grade: int

Now Student("Alice", 85) < Student("Bob", 90) works. This is useful for sorting and for classes that need a natural ordering. If you need custom ordering, override the comparison methods manually.

Inheritance and Composition

Dataclasses support inheritance, but field ordering rules apply. If a base class has fields with defaults, all derived fields must also have defaults, or you get a TypeError. A common pattern is to define a base with no defaults and derived classes with additional fields:

@dataclass
class Base:
    id: int

@dataclass
class User(Base):
    name: str

When you inherit, the generated __init__ includes base fields first, then derived fields. This can become confusing with multiple levels, so composition is often cleaner. Prefer composition over deep inheritance for data containers.

Performance and Runtime Cost

Dataclasses are ordinary Python classes; they do not provide a performance boost. The generated methods are regular Python methods, so attribute access and method calls have the same overhead as hand-written code. The main benefit is reduced source code and fewer chances for inconsistent implementations. Frozen dataclasses use a generated __setattr__ that checks frozen state and raises FrozenInstanceError for direct field assignment after initialization. If you need high-performance attribute access, consider __slots__ (available via slots=True in Python 3.10+) or namedtuples, which are more memory-efficient. However, for most applications, the maintainability gain outweighs the negligible runtime cost.

When to Use a Dataclass vs Namedtuple or Dictionary

A plain namedtuple is immutable and memory-efficient but has no annotations and little room for custom behavior; typing.NamedTuple adds annotations while keeping tuple behavior. A dictionary is flexible but has no attribute access and no validation. A dataclass gives you type hints, defaults, custom methods, and control over mutability. Use a dataclass when you need a structured object with behavior, validation, or mutable state. Use a namedtuple for simple immutable records without extra logic. Use a dictionary when the structure is dynamic and keys vary at runtime. The choice depends on whether the data shape is fixed and whether you need methods beyond data access.