What does the @dataclass decorator generate, and which class attributes become fields?

## What the decorator actually does `dataclasses.dataclass` is an ordinary decorator, not compiler magic. It runs exactly once — when the `class` statement finishes executing — and it does three things: it collects the class's annotations, turns each one into a field descriptor, and then generates source text for the methods you asked for, compiles it, and attaches the resulting functions to the class. After that the class is a normal class; instances pay no per-instance cost for having been generated this way, and you can still add methods, properties and inheritance as usual. `@dataclass` and `@dataclass()` are equivalent. ## The annotation is the switch This is the part interviewers actually probe: ```python from dataclasses import dataclass @dataclass class Employee: name: str hours: float = 0.0 grade = "junior" # no annotation -> NOT a field ``` `name` and `hours` are fields. `grade` is not: it never appears in the generated `__init__`, `__repr__` or `__eq__`, and it stays a single class-level object shared by every instance. Nothing warns you — the class builds and runs, and the missing constructor parameter shows up later as a confusing `TypeError` at a call site. The mirror-image mistake *is* caught: assigning `dataclasses.field(...)` to a name with no annotation raises `TypeError: 'x' is a field but has no type annotation`. When you genuinely want a class-level constant, annotate it `typing.ClassVar[...]`. `@dataclass` special-cases that annotation and leaves the name out of the field list entirely, which documents the intent instead of relying on a missing colon. ## The three generated methods **`__init__`** takes one parameter per field, in annotation order, and the value assigned in the class body becomes that parameter's default. A field with no assignment has no default — internally its default is the sentinel `dataclasses.MISSING` — and its argument is required. **`__repr__`** produces `Employee(name='Ada', hours=37.5)`: the class name plus each field as `name=repr(value)`. It is the eval-shaped debugging repr, which is most of why people reach for a dataclass in the first place. **`__eq__`** compares the two objects field-by-field, as if comparing tuples of their field values — but only when the other object's class is exactly the same class. Against anything else it returns `NotImplemented`, so Python falls back and the comparison ends up `False`. Two structurally identical dataclasses of *different* classes are therefore never equal, which is usually what you want for value types. Only those three are generated by default. Ordering methods, immutability and keyword-only construction are separate opt-ins. ## Annotations are not validation The annotation's value is metadata. `Employee("Ada", "many")` constructs happily and stores the string in `hours`; nothing checks it. A static type checker flags it, the interpreter does not. If a field needs a real invariant, you have to write that check yourself. Candidates who claim "dataclasses give you runtime type checking" are stating the single most common misconception about them. ## Order matters, and it is the annotation order Field order is the order the annotations appear in the class body, and that order becomes the positional signature of `__init__` and the field order in `__repr__` and `__eq__`. Reordering two annotations is therefore a breaking change to every positional call site — the same hazard as reordering function parameters. Inherited fields come first, in base-class order, before the ones the subclass adds. ## Version notes `dataclasses` has been in the standard library since Python 3.7. Python 3.14 changed *when* annotations are evaluated — PEP 649 made them lazy, evaluated on demand rather than at class-body execution — but `@dataclass` still consults the class's annotations while the decorator is running, so which names are fields, and in what order, is unchanged. One practical effect of the 3.14 model is that forward references in annotations are far less likely to need quoting. ## When this is the wrong tool A dataclass instance is a mutable object with named attributes. It is not iterable, not indexable and not unpackable like a tuple-shaped record, and it is not a serialization or validation framework. Reach for it when you want a small, readable, comparable bundle of named values with a useful `repr` — and write the class by hand when the construction logic is genuinely interesting.