In this article, you will learn how Python’s dataclass decorator can replace fragile configuration dictionaries with structured, readable, and maintainable data models.
Topics we will cover include:
- How to build and compose dataclasses for real application configurations, including handling mutable defaults and nested records.
- How to enforce local invariants at construction time using __post_init__, and how to express immutability with frozen=True.
- How to serialize and deserialize dataclasses at JSON boundaries deliberately, and when to reach for a heavier tool like Pydantic instead.
The configuration dictionary in your batch job probably works fine today. It worked fine last month too, which is exactly how it accumulated a misspelled key nobody noticed and an optional field that two call sites default differently. Somewhere in there is also a nested dictionary whose shape depends on which function built it. The dictionary didn’t fail loudly; it let three parts of the application disagree quietly, and the disagreement only surfaces when a routine change lands on the wrong assumption.
config = {
“batch_size”: 500,
“max_attempts”: 3,
“output”: {“format”: “parquet”, “compress”: True},
}
# …three modules away
size = config.get(“batchsize”, 100) # typo: silently runs with 100
config = {
“batch_size”: 500,
“max_attempts”: 3,
“output”: {“format”: “parquet”, “compress”: True},
}
# …three modules away
size = config.get(“batchsize”, 100) # typo: silently runs with 100
Python’s standard library has had a better tool for this since 3.7, and it asks for almost nothing in return. Decorate a class with @dataclass, annotate the fields, and the dataclasses module generates the initializer, representation, and equality methods for you. One boundary needs stating before anything else, though, because it shapes every design decision in this article: those field annotations describe the model, but the generated code does not check them at runtime. A dataclass is a contract you can read, not a validator that enforces itself. What that contract buys you, where its edges are, and when to reach for a heavier tool is what the rest of this article works through, using one batch-processing job that grows the way real application code does.
Start With the Smallest Useful Data Model
Here’s the loose dictionary’s replacement in its minimal form:
from dataclasses import dataclass
@dataclass
class JobConfig:
name: str
batch_size: int = 500
job = JobConfig(“nightly-import”)
print(job) # JobConfig(name=”nightly-import”, batch_size=500)
print(job == JobConfig(“nightly-import”)) # True
from dataclasses import dataclass
@dataclass
class JobConfig:
name: str
batch_size: int = 500
job = JobConfig(“nightly-import”)
print(job) # JobConfig(name=”nightly-import”, batch_size=500)
print(job == JobConfig(“nightly-import”)) # True
Three generated methods are doing the work. __init__ accepts the fields in declaration order, __repr__ prints something you’d actually want in a log line, and __eq__ compares by field values rather than identity. None of that is exotic, and that’s the appeal: you’d write the same boilerplate by hand, slightly differently each time, in every project.
The typo from the opening also changes character. job.batchsize raises an AttributeError at the line that’s wrong, and your IDE or type checker flags it before the code even runs, because attributes are checkable in a way string keys aren’t.
Now the boundary. Run JobConfig(“nightly-import”, batch_size=”lots”) and it constructs happily. As PEP 557 puts it, the decorator uses annotations to discover fields, and the types are otherwise not examined. The string will travel until something downstream does arithmetic on it. Keep that in mind every time a dataclass field looks like a guarantee; it’s documentation with excellent tooling support, and documentation doesn’t stop anyone at runtime.
Compose Nested Records Before One Class Becomes Everything
Real configurations sprawl, and the failure mode of a growing dataclass is the same as a growing dictionary: one bag holding twenty loosely related fields. Composition keeps each record responsible for one coherent slice.
from dataclasses import dataclass, field
@dataclass
class RetryPolicy:
max_attempts: int = 3
backoff_seconds: float = 2.0
@dataclass
class OutputConfig:
format: str = “parquet”
compress: bool = True
@dataclass
class JobConfig:
name: str
batch_size: int = 500
retry: RetryPolicy = field(default_factory=RetryPolicy)
output: OutputConfig = field(default_factory=OutputConfig)
job = JobConfig(
name=”nightly-import”,
retry=RetryPolicy(max_attempts=5),
)
print(job.retry.max_attempts) # 5
print(job.output.format) # ‘parquet’
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
from dataclasses import dataclass, field
@dataclass
class RetryPolicy:
max_attempts: int = 3
backoff_seconds: float = 2.0
@dataclass
class OutputConfig:
format: str = “parquet”
compress: bool = True
@dataclass
class JobConfig:
name: str
batch_size: int = 500
retry: RetryPolicy = field(default_factory=RetryPolicy)
output: OutputConfig = field(default_factory=OutputConfig)
job = JobConfig(
name=“nightly-import”,
retry=RetryPolicy(max_attempts=5),
)
print(job.retry.max_attempts) # 5
print(job.output.format) # ‘parquet’
Notice the construction is explicit. If you pass retry={“max_attempts”: 5} instead, the dataclass will store the dictionary as-is; nothing walks the annotations converting nested dictionaries into nested dataclasses for you. That surprises people who expect ORM-style magic, and it’s worth internalizing early because it comes back at the serialization boundary later.
The same composition pattern covers most structured data an application owns. A request object carrying per-run metadata, a dataset record, a model’s hyperparameter block: each is a small class with a readable shape, and nesting them keeps the shape legible as the system grows.
Figure 1. Where structure gets added, and which jobs stay explicitly yours at every stage. Sources: Python dataclasses and json documentation; PEP 557. Original diagram created for this article.
Treat Defaults as Part of the Contract
Scalar defaults work the way you’d expect, and batch_size: int = 500 is all you need. Mutable defaults are where dataclasses make you slow down, deliberately.
@dataclass
class ProcessingRequest:
job: JobConfig
tags: list[str] = field(default_factory=list)
a = ProcessingRequest(job)
b = ProcessingRequest(job)
a.tags.append(“rerun”)
print(b.tags) # [] — each instance got its own list
@dataclass
class ProcessingRequest:
job: JobConfig
tags: list[str] = field(default_factory=list)
a = ProcessingRequest(job)
b = ProcessingRequest(job)
a.tags.append(“rerun”)
print(b.tags) # [] — each instance got its own list
Write tags: list[str] = [] instead and Python raises a ValueError at class-definition time, refusing the shared mutable default outright. The default_factory callable communicates the actual intent: every instance gets a fresh list, built at construction. The same applies to nested records, which is why JobConfig above uses field(default_factory=RetryPolicy) rather than a single shared RetryPolicy() instance that every job would silently co-own.
Defaults are also where optional behavior becomes visible. A reader scanning the class sees exactly which fields the caller must supply and which arrive with sensible values, without hunting through call sites for config.get(…, fallback) patterns that may not agree with each other.
Put Local Invariants in __post_init__
The generated initializer assigns fields and nothing more. When some values would be nonsense, __post_init__ runs right after and gives you one place to say so:
@dataclass
class JobConfig:
name: str
batch_size: int = 500
retry: RetryPolicy = field(default_factory=RetryPolicy)
output: OutputConfig = field(default_factory=OutputConfig)
def __post_init__(self):
if not self.name:
raise ValueError(“name must be a non-empty string”)
if self.batch_size = 1, got {self.batch_size}”)
if not 1
@dataclass
class JobConfig:
name: str
batch_size: int = 500
retry: RetryPolicy = field(default_factory=RetryPolicy)
output: OutputConfig = field(default_factory=OutputConfig)
def __post_init__(self):
if not self.name:
raise ValueError(“name must be a non-empty string”)
if self.batch_size 1:
raise ValueError(f“batch_size must be >= 1, got {self.batch_size}”)
if not 1 self.retry.max_attempts 10:
raise ValueError(
f“retry.max_attempts must be 1-10, got {self.retry.max_attempts}”
)
Now an impossible configuration fails at construction, with an error message that names the field and the accepted range, instead of failing four function calls later where the stack trace points at the wrong suspect.
Keep this hook honest about its job. Checking invariants on values the application already trusts belongs here. Parsing strings into numbers does not, and neither does coercing arbitrary user payloads or building up rich multi-field error reports; once __post_init__ starts growing in that direction, it’s reimplementing a validation library one special case at a time, and that’s the signal to read the last section of this article carefully.
Freeze Configuration Snapshots, Not Every Object
Configuration has a property worth enforcing: once a run starts, it shouldn’t change. Dataclasses express that with frozen=True.
@dataclass(frozen=True)
class RetryPolicy:
max_attempts: int = 3
backoff_seconds: float = 2.0
# JobConfig and OutputConfig get the same treatment
config = JobConfig(name=”nightly-import”)
config.batch_size = 2000
# dataclasses.FrozenInstanceError: cannot assign to field ‘batch_size’
@dataclass(frozen=True)
class RetryPolicy:
max_attempts: int = 3
backoff_seconds: float = 2.0
# JobConfig and OutputConfig get the same treatment
config = JobConfig(name=“nightly-import”)
config.batch_size = 2000
# dataclasses.FrozenInstanceError: cannot assign to field ‘batch_size’
When you legitimately need a variant, dataclasses.replace() builds a modified copy, and it re-runs the initializer and __post_init__, so your invariants still apply to the new object:
from dataclasses import replace
bigger = replace(config, batch_size=2000) # validated again on the way in
from dataclasses import replace
bigger = replace(config, batch_size=2000) # validated again on the way in
Two qualifications keep this honest. First, frozen is emulated immutability: assignment through the generated machinery is blocked, but a frozen dataclass holding a list still holds a mutable list, and anyone can append to it. Prefer immutable field types — a tuple over a list — for values that genuinely must not move. Second, not everything wants freezing. The ProcessingRequest that accumulates results or per-run metadata should stay mutable, because that’s its job. Freeze the snapshot, not the workflow.
Serialize Deliberately at the Boundary
Sooner or later the config needs to become JSON, and this is where dataclasses hand the work back to you, politely.
import json
from dataclasses import asdict
payload = json.dumps(asdict(config), indent=2)
import json
from dataclasses import asdict
payload = json.dumps(asdict(config), indent=2)
asdict() walks the nested structure recursively, turning every dataclass into a dictionary, so the nested RetryPolicy and OutputConfig flatten cleanly into JSON-ready structures. It also deep-copies the values it encounters, which is safe but not free; for a hot path that just needs two fields, a manual projection is cheaper.
The trip back is the part people get wrong. JobConfig(**json.loads(payload)) runs without complaint and hands you a JobConfig whose retry field is a plain dictionary, because, as established earlier, nothing converts nested shapes automatically. Reconstruction has to be explicit:
@classmethod
def from_dict(cls, data: dict) -> “JobConfig”:
return cls(
name=data[“name”],
batch_size=data.get(“batch_size”, 500),
retry=RetryPolicy(**data.get(“retry”, {})),
output=OutputConfig(**data.get(“output”, {})),
)
@classmethod
def from_dict(cls, data: dict) -> “JobConfig”:
return cls(
name=data[“name”],
batch_size=data.get(“batch_size”, 500),
retry=RetryPolicy(**data.get(“retry”, {})),
output=OutputConfig(**data.get(“output”, {})),
)
Ten lines, and every one of them is a decision you can see and test. The json module handles the primitive types; dates, paths, enums, and custom objects need an encoding policy of your own, whether that’s converting them in from_dict or supplying encoder and decoder hooks. If you want the wider view of serialization formats beyond this narrow JSON boundary, the broader Python serialization guide covers that ground; the point here is narrower. Conversion is automatic in one direction and deliberate in the other, and treating asdict() as a complete round-trip schema is the most common way this tool gets misused.
Know When Dataclasses Stop Being Enough
Every tool in this space has a natural territory, and the boundaries are easier to state than people make them.
A plain dict still wins for short-lived, genuinely flexible data: a function assembling keyword arguments, a payload you inspect once and discard. Adding a class there is ceremony.
A dataclass earns its place when the application owns the data and can trust it by the time the object is built. Configuration after parsing is the obvious case, along with the internal request, result, and record objects flowing between your own functions: a light contract with a readable shape, and no dependencies at all.
Pydantic takes over when the data crosses in from somewhere you don’t control: user input, an external API’s response, or the config file a human just edited. Coercion and detailed multi-field validation errors are exactly the machinery __post_init__ shouldn’t try to grow, with schema generation thrown in, and Machine Learning Mastery’s Pydantic guide already covers it properly. Pydantic even offers validated dataclass-style models, though its own documentation is candid that they don’t replace BaseModel everywhere. The decision rule fits in a sentence: match the tool to who owns the data and how much you trust it on arrival.
dict
dataclass
Pydantic
Best for
short-lived, local, genuinely flexible data
trusted, application-owned structures
untrusted or external data with contracts
Runtime checks
none
your __post_init__ invariants only
coercion + rich validation errors
Dependencies
none
none (stdlib)
third-party
Serialization
already a dict
asdict() out; explicit rebuild in
model_dump / schema tooling
Figure 2. A qualified decision aid: match the tool to who owns the data and how much you trust it on arrival. Sources: PEP 557; Pydantic documentation. Original table created for this article.
Use Dataclasses Where the Data Is Yours
Model data after it has crossed a trustworthy boundary, and keep the records small enough that each one states a single idea. Encode defaults and invariants in the class definition, where every call site inherits them instead of reinventing them. Freeze the objects that represent decisions and keep the ones that represent work in progress mutable. And write the serialization boundary out in explicit code you can point to in review.
None of this is glamorous, which is rather the point. The same discipline quietly cleans up experiment configurations, request objects, dataset records, and model settings, because each becomes a contract someone can read rather than a convention buried in dictionary keys. The dictionary from the opening never warned anyone about anything. A dataclass at least puts the agreement in writing, and in this line of work, an agreement in writing is worth a great deal.