Python Data Classes Beyond the Boilerplate

Introduction

Most developers see Python dataclasses as a shortcut for avoiding repetitive dunder methods like __init__ and __repr__. So at first look, it seems like a simple way to write less code and move faster.

In practice, dataclasses are designed to reduce boilerplate in data-focused classes while keeping behavior clear and under your control. Instead of writing initialization, comparison, and representation logic by hand, you define the fields and let Python generate the standard methods automatically, while still retaining the flexibility to customize behavior when needed.

This article goes beyond the basics and focuses on several practical features you'll use in real projects:

• Customizing field behavior with field()
• Using __post_init__() for validation and computed values
• Building immutable and memory-efficient classes with frozen=True and slots=True

By the end, you'll know how to use dataclasses in a way that goes well beyond eliminating boilerplate.

You can get the code on GitHub.

Building a Baseline Class

Throughout this article, we'll work with a simple shipment-tracking example. Here's a starting implementation without dataclasses:

class Shipment:
    def __init__(self, tracking_id, origin, destination, weight_kg, priority):
        self.tracking_id = tracking_id
        self.origin = origin
        self.destination = destination
        self.weight_kg = weight_kg
        self.priority = priority

    def __repr__(self):
        return (
            f"Shipment(tracking_id={self.tracking_id!r}, origin={self.origin!r}, "
            f"destination={self.destination!r}, weight_kg={self.weight_kg!r}, "
            f"priority={self.priority!r})"
        )

    def __eq__(self, other):
        if not isinstance(other, Shipment):
            return NotImplemented
        return (
            self.tracking_id == other.tracking_id
            and self.origin == other.origin
            and self.destination == other.destination
            and self.weight_kg == other.weight_kg
            and self.priority == other.priority
        )

This implementation spans more than 30 lines, yet it contains no domain-specific logic. Every method exists solely to support object construction, comparison, and representation.

Using the @dataclass decorator, the same functionality becomes:

from dataclasses import dataclass

@dataclass
class Shipment:
    tracking_id: str
    origin: str
    destination: str
    weight_kg: float
    priority: str

The @dataclass decorator reads each annotated attribute and generates methods such as __init__, __repr__, and __eq__ when the class is defined. The annotations themselves are simply type hints — Python does not enforce them at runtime — but the decorator uses them to determine which fields belong to the class and in what order.

The result is the same behavior in just a few lines. More importantly, dataclasses provide capabilities that go far beyond reducing boilerplate.

Controlling Fields With field()

The field() function is the escape hatch from simple annotation syntax. It lets you configure each field individually, allowing you to define defaults, exclude fields from comparisons, hide them from object representations, and much more.

Using Default Factories

A common Python gotcha involves mutable default values. Lists and dictionaries should never be used directly as defaults because every instance would share the same object. Dataclasses prevent this by requiring mutable defaults to be created through default_factory.

Here we add a route_stops field to track intermediate shipment locations:

from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class Shipment:
    tracking_id: str
    origin: str
    destination: str
    weight_kg: float
    priority: str = "standard"
    route_stops: list[str] = field(default_factory=list)
    created_at: datetime = field(default_factory=datetime.utcnow)

The default_factory argument accepts any zero-argument callable. Each new Shipment instance receives its own fresh list, eliminating shared mutable state between objects.

Excluding Fields From repr and eq

Some fields are purely operational and should not affect equality checks or clutter debugging output. You can control this with repr=False and compare=False.

@dataclass
class Shipment:
    tracking_id: str
    origin: str
    destination: str
    weight_kg: float
    priority: str = "standard"
    route_stops: list[str] = field(default_factory=list)
    created_at: datetime = field(default_factory=datetime.utcnow)
    _internal_notes: str = field(default="", repr=False, compare=False)

Two shipments with identical logistics data compare as equal even if their internal notes differ. Likewise, _internal_notes is omitted from the generated __repr__, keeping log output focused on the information that actually matters.

This level of fine-grained control is one of the reasons dataclasses are well suited for real-world domain models rather than simple data containers.

Using __post_init__() for Validation and Derived Fields

The generated __init__() method initializes your fields automatically, but real-world classes often need validation or values derived from other fields. That's exactly what __post_init__() is for.

The generated __init__() calls __post_init__() immediately after assigning every field, making it the ideal place for validation and computed attributes.

Validating Input Data

Suppose every shipment must have a positive weight and its priority must be one of a predefined set of values.

from dataclasses import dataclass, field

VALID_PRIORITIES = {"economy", "standard", "express", "critical"}

@dataclass
class Shipment:
    tracking_id: str
    origin: str
    destination: str
    weight_kg: float
    priority: str = "standard"
    route_stops: list[str] = field(default_factory=list)

    def __post_init__(self):
        if self.weight_kg <= 0:
            raise ValueError(
                f"weight_kg must be positive, got {self.weight_kg}"
            )
        if self.priority not in VALID_PRIORITIES:
            raise ValueError(
                f"priority must be one of {VALID_PRIORITIES}, got {self.priority!r}"
            )

The generated __init__() assigns every field before calling __post_init__(). If either validation check fails, object construction immediately stops and the invalid instance is never returned to the caller.

Trying to construct a shipment with an invalid weight:

s = Shipment(
    "SHP-9921",
    "Hamburg",
    "Rotterdam",
    weight_kg=-3.5,
    priority="standard"
)

This gives:

ValueError: weight_kg must be positive, got -3.5

The error is raised during object construction rather than later in the application's execution, ensuring invalid objects never exist.

Computing Derived Fields

Besides validation, __post_init__() is also the right place to compute attributes that depend on other fields.

The key is declaring those attributes with field(init=False), which prevents the generated constructor from expecting them as input.

from dataclasses import dataclass, field

FREIGHT_RATE_PER_KG = {
    "economy": 1.20,
    "standard": 1.85,
    "express": 3.40,
    "critical": 6.00
}

@dataclass
class Shipment:
    tracking_id: str
    origin: str
    destination: str
    weight_kg: float
    priority: str = "standard"
    route_stops: list[str] = field(default_factory=list)
    freight_cost: float = field(init=False)

    def __post_init__(self):
        if self.weight_kg <= 0:
            raise ValueError(f"weight_kg must be positive, got {self.weight_kg}")

        if self.priority not in FREIGHT_RATE_PER_KG:
            raise ValueError(f"Invalid priority: {self.priority!r}")

        self.freight_cost = (
            self.weight_kg * FREIGHT_RATE_PER_KG[self.priority]
        )

Using field(init=False) tells the decorator not to include freight_cost in the generated constructor. Instead, it is calculated inside __post_init__() after weight_kg and priority have already been initialized.

Constructing a shipment:

s = Shipment(
    "SHP-9921",
    "Hamburg",
    "Rotterdam",
    weight_kg=120.0,
    priority="express"
)

print(f"Freight cost: €{s.freight_cost:.2f}")

Output:

Freight cost: €408.00

Because freight_cost is always computed during construction, it stays synchronized with weight_kg and priority. There is no separate calculation method to remember to call and no risk of stale derived data.

Creating Immutable Dataclasses

Passing frozen=True to the @dataclass decorator makes instances immutable. Once an object has been created, assigning to any field raises a FrozenInstanceError.

Immutability is useful whenever your objects represent values that should never change after creation. As an added benefit, frozen dataclasses are hashable by default, allowing them to be used as dictionary keys or stored in sets.

from dataclasses import dataclass

@dataclass(frozen=True)
class RouteSegment:
    from_hub: str
    to_hub: str
    distance_km: float
    carrier: str

With frozen=True, the decorator generates versions of __setattr__() and __delattr__() that immediately reject any attempt to modify the object after construction. This has nothing to do with runtime type checking; Python simply prevents attribute assignment once initialization is complete.

Attempting to modify an instance:

segment = RouteSegment(
    "Hamburg",
    "Rotterdam",
    120.5,
    "DHL Freight"
)

segment.distance_km = 150.0

Output:

FrozenInstanceError: cannot assign to field 'distance_km'

Since frozen dataclasses are hashable, they work naturally as dictionary keys:

transit_costs = {
    RouteSegment(
        "Hamburg",
        "Rotterdam",
        120.5,
        "DHL Freight"
    ): 340.00,
    RouteSegment(
        "Rotterdam",
        "Antwerp",
        80.0,
        "DB Schenker"
    ): 210.00,
}

The same example using a regular dataclass raises a TypeError because mutable dataclass instances are not hashable by default. Frozen dataclasses automatically generate a compatible __hash__() implementation based on the same fields used by __eq__().

Reducing Memory Usage With slots=True

When processing tens of thousands of objects, every instance carries some overhead. Standard Python objects store their attributes inside an instance __dict__, and that dictionary consumes memory even before accounting for the actual data stored in the object.

Starting with Python 3.10, dataclasses can eliminate this overhead by enabling slots=True.

from dataclasses import dataclass

@dataclass(slots=True)
class ShipmentRecord:
    tracking_id: str
    origin: str
    destination: str
    weight_kg: float
    priority: str

To see the difference, compare a regular dataclass with a slotted one:

import sys
from dataclasses import dataclass

@dataclass
class ShipmentNormal:
    tracking_id: str
    origin: str
    destination: str
    weight_kg: float
    priority: str

@dataclass(slots=True)
class ShipmentSlotted:
    tracking_id: str
    origin: str
    destination: str
    weight_kg: float
    priority: str

normal = ShipmentNormal(
    "SHP-0001",
    "Frankfurt",
    "Lyon",
    55.0,
    "standard"
)

slotted = ShipmentSlotted(
    "SHP-0001",
    "Frankfurt",
    "Lyon",
    55.0,
    "standard"
)

print(f"Normal instance:  {sys.getsizeof(normal.__dict__)} bytes (dict overhead)")
print(f"Slotted instance: {sys.getsizeof(slotted)} bytes")

Output:

Normal instance:  296 bytes (dict overhead)
Slotted instance: 72 bytes

Using slots=True saves several MB of memory purely from object overhead, before considering the memory used by the field values themselves. For extract, transform, load (ETL) pipelines and other data-processing workloads that keep many objects in memory simultaneously, those savings accumulate quickly.

One limitation is that slots=True and inheritance require some planning. While slots=True works perfectly with __post_init__(), every class in an inheritance hierarchy must also define slots. Mixing slotted and non-slotted classes generally leads to errors, so it's best to decide on your class hierarchy before adopting slots.

Putting Everything Together

Here's a production-ready Shipment class that combines the techniques covered throughout this article.

from dataclasses import dataclass, field
from datetime import datetime

FREIGHT_RATE_PER_KG = {
    "economy": 1.20,
    "standard": 1.85,
    "express": 3.40,
    "critical": 6.00
}

@dataclass(slots=True)
class Shipment:
    tracking_id: str
    origin: str
    destination: str
    weight_kg: float
    priority: str = "standard"
    route_stops: list[str] = field(default_factory=list)
    created_at: datetime = field(default_factory=datetime.utcnow)
    freight_cost: float = field(init=False)
    _audit_tag: str = field(default="", repr=False, compare=False)

    def __post_init__(self):
        if self.weight_kg <= 0:
            raise ValueError(
                f"weight_kg must be positive, got {self.weight_kg}"
            )

        if self.priority not in FREIGHT_RATE_PER_KG:
            raise ValueError(
                f"Invalid priority: {self.priority!r}"
            )

        self.freight_cost = round(
            self.weight_kg * FREIGHT_RATE_PER_KG[self.priority],
            2
        )

This class demonstrates how the different dataclass features complement one another:

• slots=True removes the per-instance __dict__, reducing memory usage.
• __post_init__() validates the input and computes freight_cost.
• field(init=False) ensures callers cannot manually provide derived values.
• field(default_factory=list) gives every shipment its own route_stops list.
• repr=False and compare=False keep internal bookkeeping fields out of object representations and equality comparisons.

Constructing an instance looks like this:

s = Shipment(
    tracking_id="SHP-4477",
    origin="Düsseldorf",
    destination="Marseille",
    weight_kg=88.5,
    priority="express",
    route_stops=[
        "Cologne Hub",
        "Lyon Distribution"
    ],
)

print(s)
print(f"Cost: €{s.freight_cost}")

Output:

Shipment(
    tracking_id='SHP-4477',
    origin='Düsseldorf',
    destination='Marseille',
    weight_kg=88.5,
    priority='express',
    route_stops=['Cologne Hub', 'Lyon Distribution'],
    created_at=datetime.datetime(...),
    freight_cost=300.9
)

Cost: €300.9

The result is a class that validates input during construction, keeps derived values synchronized automatically, uses memory efficiently, and avoids writing a single dunder method manually.

What To Explore Next

If your dataclasses need to serialize to JSON or interact with APIs, consider exploring dacite, which simplifies constructing nested dataclass instances from dictionaries.

Another useful library is marshmallow-dataclass, which generates Marshmallow schemas directly from dataclass definitions, making serialization and deserialization straightforward.

If you need richer validation than __post_init__() provides, Pydantic dataclasses integrate field validators with the familiar dataclass syntax while preserving most of the standard dataclass experience.

Finally, the official Python dataclasses documentation is well worth reading in full. Features such as metadata, kw_only, and additional options for field() cover several advanced use cases that go beyond the scope of this article.
 
 

Bala Priya C is a developer and technical writer from India. She likes working at the intersection of math, programming, data science, and content creation. Her areas of interest and expertise include DevOps, data science, and natural language processing. She enjoys reading, writing, coding, and coffee! Currently, she's working on learning and sharing her knowledge with the developer community by authoring tutorials, how-to guides, opinion pieces, and more. Bala also creates engaging resource overviews and coding tutorials.