Migration table: dataclass behaviour from 3.10 to 3.15

Before 3.11 the check was a type test against (list, dict, set). After 3.11 it is type(default).__hash__ is None. So a class that is mutable but defines __hash__ is now accepted as a default and shared across every instance:

class Bag:
    def __init__(self) -> None:
        self.items: list[str] = []
    def __hash__(self) -> int:
        return 0

@dataclass
class Leaky:
    bag: Bag = Bag()      # accepted. one Bag, for the life of the process.

No ValueError, no mypy error, no ruff error — RUF008 matches syntax, and this looks like an ordinary object default.

The change happened anyway because the old rule was narrower in a worse way: it missed bytearray, array.array, collections.deque, Counter, and every mutable user-defined class, while a hashability test catches all of those. Trading a set of common misses for one uncommon miss was the right call. It is still a proxy, and knowing which proxy is in use is how you know where it leaks.

Because mypy has a plugin for one of them and not the other.

dataclasses.replace is special-cased: the checker validates the keyword names against the field list and the types against the field types, and it does so even through generic parameterisation.

copy.replace is stubbed **changes: Any. There is no plugin. So:

dataclasses.replace(user, age="four")     # error: incompatible type "str"; expected "int"
dataclasses.replace(user, nonexistent=1)  # error: unexpected keyword argument
copy.replace(user, age="four")            # no error
copy.replace(user, nonexistent=1)         # no error

On a codebase where replace() sits on every write path — which is what a frozen-dataclass codebase looks like — that is the difference between a typo’d field name being a compile error and being a silent data-integrity bug.

Use copy.replace for the cases only it can serve: non-dataclass types implementing __replace__, and generic code that must work across both. Use dataclasses.replace everywhere else, until the gap closes.

Because it makes the failure appear when you move backwards or sideways, not forwards.

@dataclass(slots=True)
class Audited(Base):
    def save(self) -> None:
        super().save()      # 3.14: fine.  3.13 and 3.12: TypeError at call time.

Zero-arg super() compiles to a closure over an implicit __class__ cell. @dataclass(slots=True) builds a new class object, and on 3.12/3.13 that cell still pointed at the original — which is no longer in the MRO, so super() raised.

The developer on 3.14 writes it, tests it, ships it. CI runs 3.13, or a customer runs 3.12, or the container base image is older than the laptop — and it raises. And it raises at call time, not import time, so it only shows up on the code path that calls the method.

Nothing warns you. mypy does not model it. Ruff does not flag it. The only defences are (a) run your test suite on your lowest supported version in CI, not just your highest, and (b) if you support < 3.14, spell it super(Audited, self).save() in any slotted dataclass.

And note the symmetry: 3.14 added the same failure for NamedTuple methods. So on 3.14 you must not use zero-arg super() in a NamedTuple, and on < 3.14 you must not use it in a slotted dataclass. The safe habit across all versions is to avoid zero-arg super() in generated record types entirely.

Unconditional (available since 3.10/3.11, unchanged since): slots=True, kw_only=True, KW_ONLY, weakref_slot=True, match_args. These are the ones worth adopting as house style.

Unconditional but with a policy attached: slots=True — plus a rule banning zero-arg super() in any slotted class, because you support < 3.14.

Guarded or avoided: copy.replace/__replace__ (3.13+), field(doc=) (3.14+), make_dataclass(decorator=) (3.14+), dataclass_transform(frozen_default=) (3.12+, so fine here). If you need any of these on 3.11, you need a fallback branch — and for copy.replace specifically the fallback is just dataclasses.replace, which is better typed anyway.

Behaviour differences to write tests for, not guards: the 3.13 __eq__ change (only observable with NaN, so either forbid float fields in ordered dataclasses or test both branches), and Field.type (write the three-branch resolver once and test it on every supported version).

Fix now, before it bites: every isinstance(x, dataclasses._MISSING_TYPE) in the codebase, ahead of 3.15.