Python Dataclasses: Auto-Generated Data Containers

Whenever you write a class whose main job is to hold a group of related values, you end up writing the same boilerplate over and over: __init__, __repr__, __eq__. Dataclasses, introduced in Python 3.7, generate all of that automatically from your type-annotated field declarations — leaving you with a clean, expressive data container in a handful of lines.

The Problem Dataclasses Solve

# Without a dataclass — lots of repetitive boilerplate
class Product:
    def __init__(self, name: str, price: float, in_stock: bool = True):
        self.name = name
        self.price = price
        self.in_stock = in_stock

    def __repr__(self) -> str:
        return f"Product(name={self.name!r}, price={self.price}, in_stock={self.in_stock})"

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Product):
            return NotImplemented
        return (self.name, self.price, self.in_stock) == (other.name, other.price, other.in_stock)

# With a dataclass — Python generates all three methods for you
from dataclasses import dataclass

@dataclass
class Product:
    name:     str
    price:    float
    in_stock: bool = True

p = Product("Laptop", 999.0)
print(p)              # Product(name='Laptop', price=999.0, in_stock=True)
print(repr(p))        # Product(name='Laptop', price=999.0, in_stock=True)

p2 = Product("Laptop", 999.0)
print(p == p2)        # True  — __eq__ compares field values

Field Definitions and Default Values

Every type-annotated class attribute becomes a dataclass field and a parameter in the generated __init__. Fields without defaults must come before fields with defaults (same rule as regular function parameters).

from dataclasses import dataclass

@dataclass
class User:
    user_id:  int
    username: str
    email:    str
    active:   bool  = True
    role:     str   = "viewer"

u = User(101, "alice", "[email protected]")
print(u)
# User(user_id=101, username='alice', email='[email protected]', active=True, role='viewer')

# Override defaults
admin = User(1, "admin", "[email protected]", role="admin")

`field()` for Advanced Field Configuration

When your default value is a mutable object (list, dict, set), you must use field(default_factory=...) — otherwise all instances share the same mutable object.

from dataclasses import dataclass, field

@dataclass
class ShoppingCart:
    owner:    str
    items:    list[str]  = field(default_factory=list)
    metadata: dict       = field(default_factory=dict)

cart1 = ShoppingCart("Alice")
cart2 = ShoppingCart("Bob")

cart1.items.append("Laptop")
print(cart1.items)  # ['Laptop']
print(cart2.items)  # []  ← independent list, not shared

field() also lets you hide a field from __repr__ or exclude it from __init__:

from dataclasses import dataclass, field

@dataclass
class ApiCredential:
    api_key:     str
    secret:      str = field(repr=False)     # hidden from print output
    _token:      str = field(default="", init=False)  # not in __init__

Frozen Dataclasses (Immutable)

Pass frozen=True to make instances immutable. Attempting to assign to a field raises FrozenInstanceError. Frozen dataclasses are also hashable by default, so you can use them as dictionary keys or in sets.

from dataclasses import dataclass

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

p = Point(3.0, 4.0)
# p.x = 10.0  # raises FrozenInstanceError

# Hashable — can be used as a dict key
distances = {Point(0, 0): 0.0, Point(3, 4): 5.0}
print(distances[Point(3, 4)])   # 5.0

Ordering Support

Add order=True to generate __lt__, __le__, __gt__, __ge__ methods based on all fields in declaration order:

from dataclasses import dataclass

@dataclass(order=True)
class Employee:
    department: str
    name:       str
    salary:     float

team = [
    Employee("Engineering", "Charlie", 95000),
    Employee("Engineering", "Alice",   110000),
    Employee("Design",      "Bob",     88000),
]

# Sorted by department, then name, then salary (field declaration order)
for e in sorted(team):
    print(e.name, e.department)
# Bob    Design
# Alice  Engineering
# Charlie Engineering

Utility Functions

from dataclasses import dataclass, asdict, astuple, replace

@dataclass
class Address:
    street: str
    city:   str
    country: str = "India"

addr = Address("123 Main St", "Mumbai")

# Convert to dict
print(asdict(addr))
# {'street': '123 Main St', 'city': 'Mumbai', 'country': 'India'}

# Convert to tuple
print(astuple(addr))
# ('123 Main St', 'Mumbai', 'India')

# Create a modified copy (original unchanged)
new_addr = replace(addr, city="Delhi")
print(new_addr)   # Address(street='123 Main St', city='Delhi', country='India')
print(addr.city)  # Mumbai  ← original untouched

Class Variables vs Instance Fields

Use ClassVar from typing to declare attributes that belong to the class, not individual instances. Dataclasses ignore ClassVar fields — they don’t appear in __init__ or __repr__.

from dataclasses import dataclass
from typing import ClassVar

@dataclass
class Product:
    category: ClassVar[str] = "Electronics"  # shared by all instances
    name:  str
    price: float

p = Product("Laptop", 999.0)
print(p)                   # Product(name='Laptop', price=999.0)
print(Product.category)    # Electronics

Adding Methods

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

from dataclasses import dataclass

@dataclass
class Rectangle:
    width:  float
    height: float

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

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

    def is_square(self) -> bool:
        return self.width == self.height

r = Rectangle(4.0, 6.0)
print(r.area())       # 24.0
print(r.is_square())  # False

Dataclass vs NamedTuple vs Pydantic Model

Choosing the right container depends on what you need to do with the data.

Feature	`@dataclass`	`NamedTuple`	Pydantic `BaseModel`
Auto-generates `__init__` / `__repr__`	✅	✅	✅
Mutable by default	✅	❌ (always immutable)	✅
Runtime type validation	❌	❌	✅
Automatic type coercion	❌	❌	✅
JSON serialisation built-in	❌ (`asdict()` → manual)	❌	✅ (`model_dump()`)
Detailed validation errors	❌	❌	✅
Can be used as dict key	Only with `frozen=True`	✅	❌
Best suited for	Internal domain models	Lightweight immutable records	API request/response, external data

Type coercion comparison

# Dataclass — no coercion, no error, type hint is ignored at runtime
from dataclasses import dataclass

@dataclass
class UserDC:
    age: int

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

# Pydantic — coerces "25" → 25, raises ValidationError for invalid input
from pydantic import BaseModel

class UserPM(BaseModel):
    age: int

u2 = UserPM(age="25")
print(u2.age, type(u2.age))  # 25 <class 'int'>  ← converted correctly

When to Use Each

Use @dataclass when…

You trust the data source (it comes from inside your application) and you just need a convenient, readable container. Internal domain models — Product, Order, Employee, Point, Config — are perfect candidates.

@dataclass
class CartItem:
    product_id: int
    quantity:   int
    unit_price: float

    def subtotal(self) -> float:
        return self.quantity * self.unit_price

Use NamedTuple when…

You want a lightweight, always-immutable, hashable record and you never need to add methods or complex defaults.

from typing import NamedTuple

class Coordinate(NamedTuple):
    latitude:  float
    longitude: float

loc = Coordinate(51.5, -0.1)
lat, lon = loc   # supports unpacking

Use Pydantic BaseModel when…

Data comes from an external source you don’t control: an HTTP request body, a JSON file, a CSV import, user input. Use Pydantic when you need validation, coercion, and clear error messages.

from pydantic import BaseModel, field_validator

class CreateProductRequest(BaseModel):
    name:  str
    price: float
    qty:   int = 0

    @field_validator("price")
    def price_must_be_positive(cls, v: float) -> float:
        if v <= 0:
            raise ValueError("Price must be greater than zero")
        return v

Rule of thumb: If you already trust the data, use @dataclass. If you’re receiving data from the outside world and need to validate it, use a Pydantic BaseModel.

Core Python

Advanced Python

Pydantic

Python Dataclasses: Auto-Generated Data Containers

The Problem Dataclasses Solve

Field Definitions and Default Values

`field()` for Advanced Field Configuration

Frozen Dataclasses (Immutable)

Ordering Support

Utility Functions

Class Variables vs Instance Fields

Adding Methods

Dataclass vs NamedTuple vs Pydantic Model

Type coercion comparison

When to Use Each

​The Problem Dataclasses Solve

​Field Definitions and Default Values

​field() for Advanced Field Configuration

​Frozen Dataclasses (Immutable)

​Ordering Support

​Utility Functions

​Class Variables vs Instance Fields

​Adding Methods

​Dataclass vs NamedTuple vs Pydantic Model

​Type coercion comparison

​When to Use Each

The Problem Dataclasses Solve

Field Definitions and Default Values

`field()` for Advanced Field Configuration

Frozen Dataclasses (Immutable)

Ordering Support

Utility Functions

Class Variables vs Instance Fields

Adding Methods

Dataclass vs NamedTuple vs Pydantic Model

Type coercion comparison

When to Use Each