Python Dataclasses

3Python Dataclasses: explained step by step

Many classes exist mostly to carry a few values around: a Product with a name and a price, a Point with x and y, a Config with a handful of settings. Setting each one up by hand means writing the same three things again and again: an __init__ that copies every argument onto self, a __repr__ so printing is readable, and an __eq__ so two objects holding the same values count as equal. It is dull work, and it is easy to add a field and forget to update one of the three.

The boilerplate problem

Here is a plain class. Two points with identical coordinates are not equal, because without an __eq__ Python only asks "is this the very same object?":

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

p1 = Point(2, 3)
p2 = Point(2, 3)
print(p1 == p2)
print(p1 is p2)

To fix that you would add an __eq__, then a __repr__ so the object prints nicely, and then repeat the whole routine for every data class you write.

The @dataclass decorator

Import dataclass, put it above the class, and list the fields as annotated names in the class body. Each name: type line becomes a field, and the order of the lines is the order of the __init__ parameters.

from dataclasses import dataclass

@dataclass
class Point:
    x: int
    y: int

p1 = Point(2, 3)
p2 = Point(2, 3)
print(p1)
print(p1 == p2)
print(p1.x + p1.y)

The annotation is required, because it is how Python finds the fields, but Python does not check it. Point("a", "b") works without complaint. Treat type hints as documentation that your editor can also use.

Default values and default_factory

A field with a default value follows the same rule as function parameters: fields with defaults must come after fields without. Writing price: float = 0.0 before name: str raises TypeError: non-default argument 'name' follows default argument 'price'.

A list, dict or set cannot be written as a default directly. Just like a list in a class body, one shared list would be reused by every object, so tags: list = [] raises ValueError: mutable default <class 'list'> for field tags is not allowed: use default_factory. Use field(default_factory=list) instead: it calls list() separately for each new object.

from dataclasses import dataclass, field

@dataclass
class Product:
    name: str
    price: float
    in_stock: bool = True
    tags: list = field(default_factory=list)

lamp = Product("Lamp", 24.5)
mug = Product("Mug", 8.0, tags=["kitchen"])
lamp.tags.append("home")
print(lamp)
print(mug)

Frozen: objects that cannot change

@dataclass(frozen=True) makes every assignment to a field raise FrozenInstanceError after the object is created. That is perfect for values that should never change, such as coordinates or money. As a bonus, a frozen dataclass can be used as a dictionary key or stored in a set, because its fields never change underneath it.

from dataclasses import dataclass, FrozenInstanceError

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

home = Coordinate(51.5, -0.12)
try:
    home.lat = 40.0
except FrozenInstanceError:
    print("Cannot change a frozen dataclass")

visited = {home: "Home"}
print(visited[Coordinate(51.5, -0.12)])

Sorting with order=True

@dataclass(order=True) adds <, <=, > and >=. Objects are compared field by field, in the order the fields are declared, exactly like tuples. That means the first field is the most important one.

from dataclasses import dataclass

@dataclass(order=True)
class Version:
    major: int
    minor: int

releases = [Version(2, 1), Version(1, 9), Version(2, 0)]
print(sorted(releases))
print(Version(1, 9) < Version(2, 0))
print(max(releases))

post_init and field(init=False)

The generated __init__ finishes by calling __post_init__(self) if you have written one. It is the right place to validate values or to compute a field from the others. A field marked field(init=False) is left out of __init__, so callers cannot pass it, and you fill it in yourself.

from dataclasses import dataclass, field

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

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

box = Rectangle(3, 4)
print(box)
try:
    Rectangle(-1, 5)
except ValueError as err:
    print("Rejected:", err)

Converting and copying: asdict, astuple, replace

The dataclasses module also has helpers. asdict(obj) gives a plain dictionary (nested dataclasses become nested dictionaries, ready for json.dumps), astuple(obj) gives a tuple, and replace(obj, field=value) builds a new object with one or more fields changed. This is how you "edit" a frozen object.

Be careful with replace(): it copies the field values as they are, so a list inside the object is shared between the original and the copy (a shallow copy).

from dataclasses import dataclass, field, asdict, astuple, replace

@dataclass
class Task:
    title: str
    done: bool = False
    tags: list = field(default_factory=list)

task = Task("Write report", tags=["work"])
print(asdict(task))
print(astuple(task))

finished = replace(task, done=True)
print(finished)
print(task.done, finished.tags is task.tags)

When a plain class or a dict is better

A dataclass is not always the right tool. It fits when the class is mostly data and you want repr and == for free. It can still have ordinary methods, as you will see below.

Prefer a plain class when the object is mostly behaviour with hidden internal state, when __init__ takes arguments that are not stored as they are, or when you need full control over how the object is created. Prefer a plain dictionary for quick, throwaway data, or when the keys are not known in advance (for example JSON you do not control). If you need a fixed record that is also a tuple, typing.NamedTuple is another option.