Day 25/420: Dataclasses and value objects -- value equality, hashability, and immutability for free

Day 25/420: Dataclasses and value objects

420 Day Python Production Track

Two things bite me whenever I represent a small factual value as a plain class or dict: two equal values don't compare equal, and the value gets mutated under code that was still using it. Today I'll show both with an RGBColor, then fix them with @dataclass(frozen=True).

The two-line bug

class RGBColor:
    def __init__(self, r, g, b):
        self.r = r
        self.g = g
        self.b = b

teal = RGBColor(0, 128, 128)
also_teal = RGBColor(0, 128, 128)

print(teal == also_teal)   # False

Same three channels, and == is False. Python's default __eq__ compares identity -- "is this the same object in memory" -- not contents. Two colors with equal channels are two different objects, so they're not equal. The instant teal lands in a set of "colors already used in this palette," the dedup logic silently fails and you ship duplicates.

It gets worse when the value is mutable and shared:

def darken(color, amount):
    color.r = max(0, color.r - amount)   # mutates in place
    color.g = max(0, color.g - amount)
    color.b = max(0, color.b - amount)
    return color

brand = RGBColor(0, 128, 128)
shadow = darken(brand, 40)
print(brand.r, brand.g, brand.b)   # 0 88 88  -> the brand color moved too

darken looks like it returns a new color. It returns the same object it mutated, so brand -- which the rest of the theme is still referencing -- just changed. A value is a fact you pass around; it should not be editable by whoever happens to hold it.

The fix: one decorator

from dataclasses import dataclass

@dataclass(frozen=True)
class RGBColor:
    r: int
    g: int
    b: int

    def __post_init__(self):
        for name, value in (("r", self.r), ("g", self.g), ("b", self.b)):
            if not 0 <= value <= 255:
                raise ValueError(f"{name} out of range 0-255: {value}")

    def darkened(self, amount):
        clamp = lambda v: max(0, v - amount)
        return RGBColor(clamp(self.r), clamp(self.g), clamp(self.b))


teal = RGBColor(0, 128, 128)
print(teal == RGBColor(0, 128, 128))        # True  -> value equality
print(len({teal, RGBColor(0, 128, 128)}))   # 1     -> hashable, dedups by value

shadow = teal.darkened(40)
print(teal)     # RGBColor(r=0, g=128, b=128)  -> unchanged
print(shadow)   # RGBColor(r=0, g=88, b=88)    -> a new object

frozen=True generates three behaviors:

• Value __eq__. Equal channels compare equal, so the palette set collapses duplicates.
• __hash__. The color can be a set member or dict key. A mutable object can't be -- if it changed, its hash would go stale and the set would lose it.
• Immutability. Assignment is blocked, so a shared value can't be edited under you.

try:
    teal.r = 255
except Exception as exc:
    print(type(exc).__name__)   # FrozenInstanceError

darkened returns a new RGBColor instead of mutating -- the same way str.lower() gives you a new string. Sharing is safe again because nobody can change what they're holding.

Validate in __post_init__

The dataclass writes __init__ for you. To add invariants, implement __post_init__: the generated init assigns the fields, then calls it. The range check above means an out-of-range channel can never be constructed -- not from a test, not from parsed config, not from JSON. One place, every path.

The mutable-default trap

A field default cannot be a mutable object. This raises ValueError at class definition time:

# @dataclass
# class Palette:
#     colors: list = []   # ValueError: mutable default

The dataclass refuses because one list would be shared across every instance. Use field(default_factory=...):

from dataclasses import dataclass, field

@dataclass(frozen=True)
class Palette:
    name: str
    colors: tuple = field(default_factory=tuple)

p = Palette("ocean")
print(p.colors)   # ()  -> fresh per instance, not shared

I use tuple, not list. On a frozen object, frozen=True only blocks reassigning the field; a list default would still let callers mutate its contents in place. A tuple keeps the whole value immutable.

Value object vs entity

The question that decides whether to freeze: if two instances have identical fields, are they the same thing?

• RGBColor, Coordinate, Money, a date range: yes, interchangeable -> value object -> frozen dataclass, compared by value.
• User, Order, Account: no -- two accounts with the same balance are still different accounts -> entity -> stable id, compared by id.

A value object is what; an entity is who. When a thing is fully described by its contents, make it a frozen dataclass and stop hand-writing equality, hashing, and immutability.

What value type in your codebase is still a bare dict that probably shouldn't be?