Python Dataclass: The Complete Guide to Boilerplate-Free Data Classes in Python

`print(item)` can produce a useful, named summary of an object before you write a custom `__repr__`. I keep trying new things, and dataclasses make me curious about how much of a class Python can generate from a few annotated fields.

The same class can still define calculations and other methods, so a dataclass is more than a passive record. Start by looking at what Python generates for it.

What a Python dataclass generates

A Python dataclass is a class whose annotated fields drive generated methods such as __init__, __repr__, and __eq__. The decorator leaves the class itself in place, so you can add methods and properties as you would on any other class.

from dataclasses import dataclass

@dataclass
class InventoryItem:
    name: str
    unit_price: float
    quantity: int = 0

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

item = InventoryItem("Notebook", 4.5, 3)
print(item)
print(item.total_cost())

The generated constructor assigns each argument to the matching instance field, and the representation names those fields when you print the object. The method is ordinary class behavior, so a dataclass can hold data and define operations that use it, just like other Python classes and objects.

For a compact command-line example, make_dataclass() accepts the class name and field definitions as data:

python3 -c 'from dataclasses import make_dataclass; Item = make_dataclass("InventoryItem", [("name", str), ("unit_price", float), ("quantity", int, 0)]); item = Item("Notebook", 4.5, 3); print(item); print(item.unit_price * item.quantity)'

The dynamic form is useful when field names come from data, while the readable class definition above is clearer for a fixed model. An annotation describes the field for tools and generated methods, but it does not validate the value at runtime.

What annotations and defaults mean

A dataclass treats an annotated class variable as a field, unless it is marked as a class-only variable or an initialization-only value. Python does not check that a value matches the annotation when you construct the object.

from dataclasses import dataclass

@dataclass
class Reading:
    sensor: str
    value: float

reading = Reading("west", "warm")
print(reading.value, type(reading.value).__name__)

try:
    @dataclass
    class InvalidOrder:
        label: str = "sample"
        count: int
except TypeError as error:
    print(type(error).__name__, error)

I ran the annotated float example with a string, and Python printed warm str instead of rejecting it, so add explicit checks when constructor values need validation.

Keyword-only fields let you keep required positional fields ahead of optional fields while making selected arguments explicit at the call site. Use the field-level option when that makes construction clearer, and remember it requires a Python version that supports the option.

Build and shape a dataclass

Start with fields that describe one value in your program, then add only the generated behavior your code needs. The same InventoryItem can validate inputs, compute a result, and convert to a dictionary without replacing its ordinary methods.

Give mutable fields their own factory

Use field(default_factory=…) for each list or dictionary that belongs to an instance, because the factory creates a fresh value when that instance is constructed.

from dataclasses import dataclass, field

@dataclass
class Basket:
    owner: str
    items: list[str] = field(default_factory=list)

first = Basket("Ari")
second = Basket("Bea")
first.items.append("tea")
print(first.items)
print(second.items)

A new list is allocated for each Basket, and any zero-argument callable can serve as the factory when an empty list is not the value you need.

Validate or derive values after initialization

__post_init__ runs after the generated constructor has assigned fields. Raise an exception for invalid input, or use an init=False field for a value derived from the constructor arguments.

from dataclasses import dataclass, field

@dataclass
class Rectangle:
    width: float
    height: float
    area: float = field(init=False)

    def __post_init__(self) -> None:
        if self.width <= 0 or self.height <= 0:
            raise ValueError("Dimensions must be positive")
        self.area = self.width * self.height

shape = Rectangle(4, 2.5)
print(shape.area)

Input annotations still do not perform the checks here. The explicit conditional supplies that contract, and the exception stops construction before an invalid rectangle can be used.

Choose generated representation and equality

Set repr=False on a field to keep it out of the generated representation, or compare=False to exclude it from generated equality. Excluding a secret from repr reduces accidental display, but it does not make logs or objects safe to expose.

from dataclasses import dataclass, field

@dataclass
class Account:
    username: str
    token: str = field(repr=False, compare=False)

left = Account("sam", "secret-a")
right = Account("sam", "secret-b")
print(left)
print(left == right)

The two accounts compare equal because only username participates in equality. A field omitted from repr remains stored on the object, so treat redaction as display control rather than data protection.

Convert fields with asdict

dataclasses.asdict() recursively turns dataclass instances into dictionaries and traverses nested dataclasses, dictionaries, lists, and tuples. It also deep-copies other values, so it is not a zero-copy view of the object.

from dataclasses import asdict, dataclass

@dataclass
class Point:
    x: int
    y: int

@dataclass
class Route:
    start: Point
    stops: list[Point]

route = Route(Point(0, 0), [Point(2, 1)])
print(asdict(route))

The nested Point values become nested dictionaries, while the list remains a list containing converted dictionaries. For a shallow mapping, read each declared field directly instead of paying for recursive conversion and copying.

Where dataclass behavior surprises

Dataclasses keep normal Python object behavior, so options such as frozen, slots, inheritance, and hashing have specific limits. Pick them for a stated requirement rather than treating them as a bundle of safety switches.

• Frozen is shallow. frozen=True blocks ordinary assignment to fields, but a list stored in a frozen object can still be mutated.
• Hashing follows equality and mutability. A mutable dataclass with generated equality is normally unhashable. With eq=True and frozen=True, Python generates a hash from comparable fields.
• Slots change instance storage. The option creates slots and can remove the per-instance dictionary. It does not promise a measured memory saving for every workload.
• Inheritance keeps field order. A required subclass field cannot follow a default-valued field inherited from a base class in the generated constructor.

Dataclasses leave validation of external data to checks you add or to a separate model library. That choice determines where input errors are reported.

Choose the class shape that matches the data

A named tuple fits a fixed positional record with tuple behavior, while a dataclass gives you a regular class with configurable generated methods. Keep a regular class when the object’s behavior and lifecycle matter more than its stored fields, and choose a validation model when untrusted input needs parsing and explicit error reporting.

from dataclasses import dataclass

@dataclass(frozen=True)
class Temperature:
    celsius: float

reading = Temperature(21.5)
print(reading)

Start with one small record and inspect its generated representation. When a requirement appears, add the matching behavior explicitly instead of assuming annotations, frozen fields, or serialization provide more than they do.

Frequently asked questions about Python dataclasses

These answers clarify behavior that gets confused with type checking or validation.