Python Dataclasses: Clean Data Models Without Boilerplate

Learn Python dataclasses — auto-generated constructors, field defaults, frozen instances, ordering, utility functions, and when to use them vs Pydantic.

Dataclasses were introduced in Python 3.7 (PEP 557) to solve a specific, common problem: when you create a class whose primary purpose is to hold data, you inevitably write the same boilerplate over and over — __init__, __repr__, __eq__. The @dataclass decorator eliminates this entirely. Python generates those methods automatically from your type-annotated fields, giving you a clean, readable data model with almost no ceremony. This page covers everything from basic usage to frozen instances, ordering, class variables, utility functions, and how dataclasses compare to Pydantic’s BaseModel.

What is a Dataclass?

A dataclass is a class decorated with @dataclass that automatically generates common dunder methods based on its type-annotated attributes. Import the decorator from the dataclasses module:

from dataclasses import dataclass

Before and After

Without dataclass — verbose boilerplate:

class Student:
    def __init__(self, name, age):
        self.name = name
        self.age = age

    def __repr__(self):
        return f"Student(name={self.name!r}, age={self.age!r})"

    def __eq__(self, other):
        return self.name == other.name and self.age == other.age

With dataclass — concise and clear:

from dataclasses import dataclass

@dataclass
class Student:
    name: str
    age: int

s = Student("John", 20)
print(s)   # Student(name='John', age=20)

Python automatically generates __init__(), __repr__(), and __eq__() from the type-annotated fields.

Fields and Default Values

Every type-annotated attribute becomes a dataclass field:

@dataclass
class Product:
    id:    int
    name:  str
    price: float

Fields can have default values to make them optional:

@dataclass
class User:
    name:   str
    active: bool = True   # optional — defaults to True

u = User("Alice")
print(u)   # User(name='Alice', active=True)

Never use a mutable object (like a list or dict) as a default value directly. All instances would share the same object, causing hard-to-debug bugs:

# ❌ Wrong — all Team instances share the same list
@dataclass
class Team:
    members: list = []

Use field(default_factory=...) instead:

from dataclasses import dataclass, field

# ✅ Correct — each instance gets its own fresh list
@dataclass
class Team:
    members: list = field(default_factory=list)

Adding Methods

Dataclasses are still regular classes — you can add any methods you need:

@dataclass
class Rectangle:
    width:  int
    height: int

    def area(self) -> int:
        return self.width * self.height

    def perimeter(self) -> int:
        return 2 * (self.width + self.height)

r = Rectangle(10, 5)
print(r.area())      # 50
print(r.perimeter()) # 30

Immutable Dataclasses with frozen=True

Pass frozen=True to make all instances immutable. Attempting to modify a field raises a FrozenInstanceError:

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

p = Point(3, 4)
# p.x = 10   # FrozenInstanceError: cannot assign to field 'x'

Frozen dataclasses are hashable by default, making them suitable as dictionary keys or set members.

Ordering with order=True

Pass order=True to generate comparison methods (<, <=, >, >=) based on field values in declaration order:

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

students = [Student(20, "Bob"), Student(18, "Alice"), Student(22, "Carol")]
print(sorted(students))
# [Student(age=18, name='Alice'), Student(age=20, name='Bob'), Student(age=22, name='Carol')]

Decorator Options Summary

Option	Description
frozen=True	Makes instances immutable (and hashable)
order=True	Generates <, <=, >, >= comparison methods
slots=True	Uses __slots__ for reduced memory usage (Python 3.10+)
kw_only=True	All fields must be passed as keyword arguments

@dataclass(frozen=True, order=True)
class Employee:
    id:   int
    name: str

Instance Variables vs. Class Variables

Instance Variables

Type-annotated attributes become instance fields — each object gets its own copy:

@dataclass
class Student:
    name: str
    age:  int

s1 = Student("Alice", 20)
s2 = Student("Bob", 22)
print(s1.name)   # Alice
print(s2.name)   # Bob

Class Variables with ClassVar

Use ClassVar from typing to declare class-level attributes that are shared by all instances. Dataclasses exclude ClassVar fields from __init__ and __repr__:

from dataclasses import dataclass
from typing import ClassVar

@dataclass
class Student:
    school: ClassVar[str] = "ABC School"   # class variable

    name: str
    age:  int

s = Student("John", 20)
print(Student.school)   # ABC School
print(s.school)         # ABC School
print(s)                # Student(name='John', age=20)  — school not shown

Utility Functions

The dataclasses module provides three helpful utility functions:

asdict() — Convert to Dictionary

from dataclasses import asdict

s = Student("John", 20)
print(asdict(s))   # {'name': 'John', 'age': 20}

astuple() — Convert to Tuple

from dataclasses import astuple

print(astuple(s))  # ('John', 20)

replace() — Create a Modified Copy

from dataclasses import replace

s2 = replace(s, age=21)
print(s2)   # Student(name='John', age=21)
print(s)    # Student(name='John', age=20)  — original unchanged

Dataclass vs. Pydantic BaseModel

Both are used for structured data, but they serve different purposes:

Feature	@dataclass	Pydantic BaseModel
Auto-generates __init__, __repr__, __eq__	✅	✅
Runtime type validation	❌	✅
Automatic type coercion ("25" → 25)	❌	✅
Serialisation	asdict()	model_dump()
Built-in JSON support	Manual	✅
Detailed validation error messages	❌	✅
Performance	Faster	Slight overhead for validation
Best suited for	Internal/domain models	API request & response models

Type Validation Comparison

Dataclass — no validation:

@dataclass
class User:
    age: int

u = User("25")
print(u.age)         # "25"  — still a string!
print(type(u.age))   # <class 'str'>

Pydantic — validates and coerces:

from pydantic import BaseModel

class User(BaseModel):
    age: int

u = User(age="25")
print(u.age)         # 25  — coerced to int
print(type(u.age))   # <class 'int'>

When to Use Each

Use @dataclass when:

• You’re building internal domain or business models.
• You already trust the data (it was created by your own code).
• You want a lightweight container without validation overhead.
• Examples: Product, Employee, Point, Config

Use Pydantic BaseModel when:

• You’re accepting external input (HTTP requests, JSON files, user forms).
• You need automatic type coercion and detailed error messages.
• You’re building FastAPI request/response models.
• Examples: API request schemas, response bodies, configuration settings

Rule of thumb: @dataclass → “I already trust this data; I just need a convenient container.” Pydantic BaseModel → “I don’t trust this data yet; validate it before I use it.”