---
title: "Python dataclasses"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source: https://iinventedlight.com/library/notes/python-dataclasses.md
source_license: "PSF License 2.0 docs; restated in our own words"
attribution: "Summary by iinventedlight (AI-assisted). Sources: Python Software Foundation, dataclasses — Data Classes, PSF License 2.0 docs; Python Software Foundation, 9. Classes, PSF License 2.0 docs."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-03
status: published
checked_on: 2026-11-03
as_of: 2026-11-03
confidence: medium
untested: "No Python interpreter was run; decorator options and examples were not executed; only the fetched documentation pages were read."
category: coverage-gaps
topic_area: "code-python: dataclasses"
tags: python, dataclasses, classes, stdlib
sources:
  - id: S1
    title: "dataclasses — Data Classes"
    publisher: Python Software Foundation
    url: https://docs.python.org/3/library/dataclasses.html
    accessed: 2026-11-03
    license: "PSF License 2.0 docs"
  - id: S2
    title: "9. Classes"
    publisher: Python Software Foundation
    url: https://docs.python.org/3/tutorial/classes.html
    accessed: 2026-11-03
    license: "PSF License 2.0 docs"
---
# Python dataclasses

## Summary
A class bundles data and behavior. For a named bundle of fields, the tutorial's usual pattern is a dataclass: `@dataclass` writes `__init__`, `__repr__`, and related methods from annotated attributes.

## Classes and fields
Classes make a new type, hold state on each instance, and define methods. Instance attributes are per object; class attributes are shared. A mutable list on the class is shared, so per-instance lists belong on `self`. Dataclasses are still ordinary classes with generated boilerplate.

A field is a class variable with a type annotation. Generated methods follow field order. By default the decorator adds `__init__`, `__repr__`, and equality, and returns the same class (unless you ask for slots). You can still write methods such as `total_cost`. If you already defined `__init__` or `__repr__`, those options are ignored.

## Defaults, frozen, helpers
A field without a default cannot follow one that has a default. Do not write `x: list = []`; an unhashable default raises `ValueError`. Use `field(default_factory=list)` so each instance gets a fresh list. `frozen=True` makes assignment raise (a stand-in for immutability). `replace` builds a new instance through `__init__`, so `__post_init__` still runs — use it for derived fields or a non-dataclass base `__init__`. `asdict` / `astuple` walk nested structures. `fields()` skips `ClassVar` and `InitVar`. Init-only variables are constructor args for `__post_init__`, not stored fields.

The tutorial's `Employee` record (`name`, `dept`, `salary`) is the idiomatic stand-in for a small named record. Handwrite a class when construction is unusual or generated methods would fight yours.

## Claims
- id: C1
  claim: The dataclasses module supplies a decorator and helpers that generate methods such as __init__ and __repr__ on your class.
  source: S1
  evidence: "This module provides a decorator and functions for automatically adding generated special methods such as __init__() and __repr__() to user-defined classes."
- id: C2
  claim: A dataclass field is a class variable that has a type annotation.
  source: S1
  evidence: "A field is defined as a class variable that has a type annotation"
- id: C3
  claim: With frozen=True, assigning to fields raises, which stands in for read-only instances.
  source: S1
  evidence: "assigning to fields will generate an exception. This emulates read-only frozen instances."
- id: C4
  claim: Unhashable field defaults are rejected; use a default factory to give each instance its own mutable value.
  source: S1
  evidence: "Using default factory functions is a way to create new instances of mutable types as default values for fields"
- id: C5
  claim: Classes bundle data and functionality and let you create instances of a new type.
  source: S2
  evidence: "Classes provide a means of bundling data and functionality together."
- id: C6
  claim: For a small named record of data items, the usual approach in the tutorial is a dataclass.
  source: S2
  evidence: "The idiomatic approach is to use dataclasses for this purpose"