Dataclasses

Writing a Python class often requires a lot of repetitive boilerplate code. You have to define __init__ to assign arguments to attributes, __repr__ for readable printing, and __eq__ for value comparison.

Python’s dataclasses module provides a powerful decorator that automates this entire process. By simply adding @dataclass above your class definition and providing type hints for your fields, Python writes the tedious dunder methods for you.

Basic Usage

The @dataclass decorator reads your class variables and automatically generates an __init__ method and a clean __repr__ method.

from dataclasses import dataclass

@dataclass
class Point:
    x: int
    y: int

p = Point(10, 20)
print(p)

Point(x=10, y=20)

Crucial detail: You must include type hints (like : int). The dataclass generator relies entirely on these annotations to determine which variables are actually fields. Without a type hint, the generator completely ignores the variable.

Value Equality

By default, standard Python classes compare object memory addresses (identity) when you use ==. Dataclasses are smarter: they automatically generate an __eq__ method that compares the object field-by-field.

from dataclasses import dataclass

@dataclass
class Product:
    name: str
    price: float

p1 = Product('Apple', 1.0)
p2 = Product('Apple', 1.0)
print(p1 == p2)

True

Managing Mutable Defaults with field()

If you want a field to have a default value, you simply assign it: is_active: bool = True. However, if you attempt to use an empty list [] as a default, Python will raise a ValueError because mutable defaults cause dangerous shared-state bugs across all instances.

To safely use dynamic or mutable defaults (like a fresh list for every new instance), you must use the field() function and provide a default_factory.

from dataclasses import dataclass, field

@dataclass
class Team:
    name: str
    members: list = field(default_factory=list)

t1 = Team('Red')
t1.members.append('Alice')
t2 = Team('Blue')
print(f'{t1.name}: {t1.members}')
print(f'{t2.name}: {t2.members}')

Red: ['Alice']
Blue: []

Immutability: Frozen Dataclasses

Sometimes you want an object to be read-only after it is created. You can achieve this by passing frozen=True to the decorator. Any attempt to modify a field on a frozen dataclass raises a FrozenInstanceError.

from dataclasses import dataclass

@dataclass(frozen=True)
class Location:
    lat: float
    lon: float

loc = Location(37.77, -122.41)
try:
    loc.lat = 0.0
except Exception as e:
    print(type(e).__name__)

FrozenInstanceError

Because frozen dataclasses cannot be modified, Python can safely generate a __hash__ method for them (as long as all of their fields are also hashable). This allows you to use your dataclasses as dictionary keys or inside sets.

from dataclasses import dataclass

@dataclass(frozen=True)
class Location:
    name: str

# Because it is frozen and its fields are hashable, it can be a dict key
visited = {Location('Paris'): True}
print(visited[Location('Paris')])

True

Note on Immutability: frozen=True only prevents reassignment of the object’s direct attributes (shallow immutability). If a field holds a mutable list, you can still append to that list!

Post-Initialization

Because the @dataclass decorator writes the __init__ method for you, you can’t put custom logic inside __init__ (like calculating a derived field). To solve this, dataclasses provide __post_init__, a special method that automatically runs immediately after the generated __init__ finishes.

from dataclasses import dataclass

@dataclass
class Rectangle:
    width: float
    height: float
    area: float = 0.0

    def __post_init__(self):
        self.area = self.width * self.height

rect = Rectangle(5.0, 4.0)
print(rect.area)

20.0

Dataclasses drastically reduce visual clutter, keep your code DRY (Don’t Repeat Yourself), and represent the modern Pythonic standard for defining data-heavy structures.