The decorator scans the class body for type-annotated names and turns them into fields. The synthesized __init__ takes the fields in declaration order (positional or keyword), __repr__ prints the class name with all field values, and __eq__ compares by field values, not identity. Two instances with the same field values are equal even though they are different objects. By default fields are still mutable (p1.x = 10 works); frozen=True makes them read-only, covered in the frozen-slots entry.

Fields without defaults must come before fields with defaults, same as a regular function signature. For mutable default values (list, dict, set), Python's class-attribute model would share one object across all instances, so dataclasses raise an error if you try to write tags: list[str] = []. The fix is field(default_factory=list): a zero-arg callable runs per instance and produces a fresh value. Use default_factory=dict for empty dicts, default_factory=lambda: 'pending' for any computed default.

Decorator arguments toggle individual generated methods. order=True synthesizes <, <=, >, >= based on tuple comparison of fields in declaration order, which makes list.sort() and min/max Just Work. repr=False (or eq=False, init=False) suppresses one method when you want to write your own; the example uses it to redact a secret from repr. Other useful flags: kw_only=True to force keyword arguments, slots=True to skip __dict__ (covered in the frozen-slots entry).