python-value-objects

Python value objects

A value object is a small, immutable bundle of fields that's equal to another instance with the same values. Money(10, "USD") == Money(10, "USD") is true. It has no identity — there's no id field, no "this is the canonical instance" semantics. You make new ones; you don't mutate them.

Domain code is much easier to reason about when the primitives are value objects: invariants live in one place, equality is meaningful, and "did this change?" is answered by == / !=.

This skill encodes the canonical shape: frozen dataclass with slots, kw_only fields, invariants in __post_init__, behavior as methods on the class.

When to use this skill

Apply when defining:

• Domain primitives — Money, EmailAddress, PhoneNumber, Address, Coordinates
• Configuration values that should be tamper-proof
• Event payloads (events are facts; facts don't change)
• Result types from pure computations

Don't apply to:

• Anything with an id and a lifecycle (use python-aggregate-and-repo)
• API-shaped DTOs that need Pydantic validation (use python-service-and-schema-cohesion)
• Mutable holders of state (consider whether you actually need a class at all)

The rules

1. @dataclass(frozen=True, slots=True, kw_only=True) — always all three

from dataclasses import dataclass
from decimal import Decimal


@dataclass(frozen=True, slots=True, kw_only=True)
class Money:
    amount: Decimal
    currency: str

Why each flag:

• frozen=True — instances can't be mutated after construction. The whole point of a value object.
• slots=True — no __dict__; significantly smaller in memory, faster attribute access, catches typos at runtime (assigning to an unknown attribute raises). Modern Python (3.10+) supports this for dataclasses natively.
• kw_only=True — every field is keyword-only at the call site. Money(10, "USD") is rejected; Money(amount=10, currency="USD") is required. This makes call sites self-documenting and lets you reorder fields without breaking callers.