writing-dataclasses

Use @frozen from posthog.dataclasses, which applies frozen=True, kw_only=True, and slots=True by default. Construct instances with keyword arguments only, and override individual flags like @frozen(slots=False) only when needed, such as for functools.cached_property.

Use a dataclass when two or more returned elements share a type, when a tuple has roughly 3+ elements, or when a fixed set of values crosses a function boundary. Keep dicts for genuinely dynamic key sets and small tuples of clearly different types.

The blocking ratchet in posthog/test/repo_invariants/test_dataclass_defaults.py rejects new bare @dataclass decorators without an explicit frozen= choice. Adding frozen=True or frozen=False passes; the ratchet requires a stated choice, not immutability.

Mark secret fields with field(repr=False) so they cannot leak through repr() into tracebacks and logs. Also avoid calling asdict() on such dataclasses in log output, since that bypasses the repr protection.

Accept the dataclass when the function's parameters mirror fields the caller already holds, following Fowler's Preserve Whole Object. Exceptions include invariant narrowing, Temporal or celery wire signatures, and facade contracts that double as HTTP request bodies.

No. The rules explicitly exclude pydantic models used as HogQL/query schema, DRF serializers, and Django models. They target internal value and result objects, plus facade contract DTOs which typically use pydantic.dataclasses.dataclass(frozen=True).