Python Data Class: A Better Way to Store Data

That’s a good thing. A default value is created only once, so every hand would share the same list, and adding a card to one hand would add it to all of them. The error message already tells you the fix: use field() with a default_factory. That’s a function that Python calls to create a fresh default for every new object:

from dataclasses import dataclass, field

@dataclass
class Hand:
    player: str
    cards: list[str] = field(default_factory=list)

alice = Hand('Alice')
bob = Hand('Bob')
alice.cards.append('Q of hearts')

print(alice)
# Hand(player='Alice', cards=['Q of hearts'])
print(bob)
# Hand(player='Bob', cards=[])Code language: Python (python)

The same goes for dictionaries and sets: use field(default_factory=dict) or field(default_factory=set).

Data class options

You can pass options to the decorator to change what it generates. These are the ones you’ll use most.

frozen=True: read-only data classes

With frozen=True, you can’t change the fields after the object is created. A frozen data class is also hashable, so you can use it as a dictionary key or put it in a set:

from dataclasses import dataclass

@dataclass(frozen=True)
class Card:
    rank: str
    suit: str

card = Card('Q', 'hearts')
seen = {card}
print(card in seen)
# True

card.rank = 'K'
# dataclasses.FrozenInstanceError: cannot assign to field 'rank'Code language: Python (python)

order=True: sorting data classes

By default, you can only compare data classes with ==. With order=True, you also get <, <=, > and >=. Python compares the fields one by one, in the order you defined them, so you can sort a list of objects:

from dataclasses import dataclass

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

versions = [Version(3, 15, 2), Version(3, 9, 0), Version(3, 14, 1)]
print(sorted(versions))
# [Version(major=3, minor=9, patch=0), Version(major=3, minor=14, patch=1), Version(major=3, minor=15, patch=2)]Code language: Python (python)

slots=True and kw_only=True

Since Python 3.10, there are two more useful options:

• slots=True gives your class slots. Objects use less memory, and assigning to a field that doesn’t exist raises an error instead of silently creating a new attribute.
• kw_only=True makes all fields keyword-only. That makes calls easier to read when a class has many fields, and prevents mixing up arguments of the same type.

from dataclasses import dataclass

@dataclass(slots=True, kw_only=True)
class User:
    name: str
    email: str
    admin: bool = False

user = User(name='Erik', email='erik@example.com')
print(user)
# User(name='Erik', email='erik@example.com', admin=False)

User('Erik', 'erik@example.com')
# TypeError: User.__init__() takes 1 positional argument but 3 were givenCode language: Python (python)

Validation and computed fields with __post_init__

Since the decorator writes __init__ for you, where do you put extra setup code? In a method called __post_init__. The generated __init__ calls it right after it has set all fields. You can use it to validate the data or to calculate fields from other fields:

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

print(Rectangle(3, 4))
# Rectangle(width=3, height=4, area=12)

Rectangle(-1, 4)
# ValueError: width and height must be positiveCode language: Python (python)

The field(init=False) tells the decorator that area is not an argument of __init__. It’s still a field, so it shows up when you print the object.

Converting a data class to JSON

A common use case is to convert your nicely structured data class to JSON. E.g., if you want to export the data to a database, or send it to the browser. For simple cases, the standard library has you covered. The asdict() function turns a data class into a dictionary, and json.dumps() turns that dictionary into JSON:

import json
from dataclasses import dataclass, asdict

@dataclass
class Card:
    rank: str = 'Q'
    suit: str = 'hearts'

card = Card()
print(json.dumps(asdict(card)))
# {"rank": "Q", "suit": "hearts"}Code language: Python (python)

This works as long as your fields contain types that JSON knows about: strings, numbers, booleans, None, lists, and dictionaries. asdict() also converts nested data classes. For other types, like a date, json.dumps() raises TypeError: Object of type date is not JSON serializable. A quick fix is to pass default=str, which converts anything unknown to a string:

import json
from dataclasses import dataclass, asdict
from datetime import date

@dataclass
class Event:
    name: str
    day: date

event = Event('PyCon', date(2026, 5, 13))
print(json.dumps(asdict(event), default=str))
# {"name": "PyCon", "day": "2026-05-13"}Code language: Python (python)

Converting back from JSON to a data class is where the standard library stops helping. If you need both directions, or you want the types checked, use a package. The most popular one is Pydantic. It has its own drop-in @dataclass decorator that validates and converts the data you pass in:

from datetime import date
from pydantic.dataclasses import dataclass
from pydantic import TypeAdapter

@dataclass
class Event:
    name: str
    day: date

event = Event('PyCon', '2026-05-13')
print(event)
# Event(name='PyCon', day=datetime.date(2026, 5, 13))

print(TypeAdapter(Event).dump_json(event).decode())
# {"name":"PyCon","day":"2026-05-13"}Code language: Python (python)

Note how Pydantic turned the string '2026-05-13' into a real date object.

A lighter alternative is a package called dataclasses-json. It requires an extra decorator. Like Pydantic, you’ll need to install it, preferably inside a virtual environment, with the pip install command or with uv:

Here’s an example of how you can use the package:

from dataclasses import dataclass
from dataclasses_json import dataclass_json

@dataclass_json
@dataclass
class Card:
    rank: str = 'Q'
    suit: str = 'hearts'

card = Card()
print(card.to_json())Code language: Python (python)

This results in the following output:

Keep learning

• The Python attrs package has an advanced version of the native Python data class
• The official documentation on Python.org
• How to return multiple values in Python