How should I define a small record with dataclasses?

A dataclass is a good fit when the class’s main job is to hold related fields. Annotate each field, then use @dataclass above the class. The dataclass decorator uses annotated fields to generate methods, including an initializer and a representation by default. [S1]

For example:

from dataclasses import dataclass, field

@dataclass
class Task:
    title: str
    owner: str
    labels: list[str] = field(default_factory=list)
    done: bool = False

Here, title and owner have no defaults, so a caller supplies them when creating a task. labels and done have defaults, so a caller can leave them out. The factory gives each Task a fresh labels list rather than using one shared mutable default. [S1]

For example, Task("Review draft", "Mina") represents a task with no labels and done set to False. This is a compact record, not a guarantee that the values are valid for every application; add any needed validation separately.

A list can be changed after an instance is created, so a mutable default needs special care. The dataclasses reference recommends field(default_factory=...) when a field needs a fresh mutable default, such as a list. [S1] In this example, default_factory=list tells the dataclass how to obtain a list for an instance when the caller does not supply labels.

That choice expresses the intended behavior clearly: labels belong to a particular task, and callers can also provide their own list when creating one. If a field is not mutable—for example, a boolean such as done—a direct default like False is suitable for this example.

A useful decision is: should every new record start with its own empty collection? If yes, use a factory. If the field is required instead, omit its default and have the caller provide it. The reference explains how to set these defaults, but it does not establish what values or validation rules your application should use.

You can create a record by passing its required values, then read or update its fields as your program needs. For example:

task = Task("Review draft", "Mina")
task.labels.append("writing")
print(task)

The generated representation can make a record easier to inspect while developing; the dataclass reference says a representation is generated by default. [S1] Treat this as a convenience, not as an application-specific display format.

A dataclass is a reasonable starting point when your main need is a named group of related values and the fields are the important part. If creating a record must enforce rules, perform work, or coordinate complicated changes, consider whether those responsibilities need explicit methods or a different design. That is a design judgment, not something the dataclass decorator decides for you.

One more option is frozen=True when you want assignment to fields to raise an error. The documentation describes this as emulating read-only instances, not making objects truly immutable. [S1] So do not choose it assuming that it guarantees deep immutability.

Use this checklist:

1. Name the record after the thing it represents, such as Task.
2. Add an annotated field for each piece of information that belongs in every record.
3. Decide which fields callers must supply and which should have defaults.
4. Use field(default_factory=...) for a mutable default such as a list.
5. Decide whether the record only holds data or also needs explicit behavior or validation.
6. Check your target Python version before relying on the syntax. The official reference describes the version documented on its page and advises checking compatibility when targeting another version. [S1]

The reference establishes the dataclass field and generated-method behavior, the mutable-default factory approach, and the limited meaning of frozen=True. [S1] It does not establish that a particular record design is best for your program, nor does it verify compatibility for every Python installation. Test your chosen definition in the environment you plan to use.