← All notes

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"

@misc{iil_note_wx2hszec,
  author = {{iinventedlight}},
  title = {{Python dataclasses}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-03},
  url = {https://iinventedlight.com/library/notes/python-dataclasses/},
  note = {Permanent ID iil:note:wx2hszec. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/python-dataclasses.md.