How does @functools.cached_property differ from @property on repeated attribute access?

## Two decorators, two lifetimes `property` turns a method into an attribute-shaped read: every `obj.total` calls the function. That is the right thing when the value tracks mutable state, and the wrong thing when the value is expensive and settled. `functools.cached_property`, added in 3.8, is the settled case: compute once per instance, then behave like a plain attribute. ```python import functools class Invoice: def __init__(self, lines): self.lines = lines @functools.cached_property def total(self): print("summing") return sum(self.lines) inv = Invoice([10, 20]) inv.total # prints 'summing', returns 30 inv.total # prints nothing, returns 30 inv.__dict__ # {'lines': [10, 20], 'total': 30} ``` ## The mechanism, in one sentence The first access calls your function and writes its result into `inv.__dict__['total']`. Attribute lookup consults the instance dictionary before it consults a class attribute of this kind, so from the second access onward the lookup finds the stored value and stops — the decorator is not consulted, adds no per-access cost, and could not intervene if it wanted to. That single fact explains everything else about it. ## Invalidation is manual There is no dependency tracking, no TTL, and no notification when `self.lines` changes. If the inputs move, the cached number is now a lie. You invalidate by removing the instance attribute: ```python del inv.total # or inv.__dict__.pop('total', None) inv.total # recomputes ``` `del` raises `AttributeError` if the value was never computed, which is why the `pop` form with a default is common in a `reset()` method. If you find yourself invalidating on every mutation, the honest answer is that you wanted a plain `property` — or a method — and the caching was premature. ## Assignment behaves differently from property A `property` with only a getter rejects assignment with `AttributeError`. A `cached_property` accepts it: `inv.total = 999` writes straight into the instance dictionary and every later read returns 999 without ever calling your function. That is occasionally useful for injecting a value in a test, and occasionally a bug when a caller assigns to what they assumed was read-only. If read-only matters, `property` is the correct tool. ## The __slots__ clash The value has to live in the instance dictionary — so the instance must have one. A class that declares `__slots__` and does not list `'__dict__'` has no instance dictionary, and the first access raises `TypeError`, complaining that there is no `__dict__` on the instance in which to cache the attribute: ```python import functools class Row: __slots__ = ("cells",) def __init__(self, cells): self.cells = cells @functools.cached_property def width(self): return len(self.cells) Row("abc").width # TypeError ``` The available moves are: add `'__dict__'` to `__slots__`, which restores the cache but gives back most of the memory saving `__slots__` bought; or cache by hand into a dedicated slot with an explicit sentinel; or drop the caching. It is worth knowing this pairing on sight, because `__slots__` and `cached_property` are both reached for in the same kind of code — many small objects, each with a derived value — and they do not compose. ## Naming and threads The decorator learns the attribute name when the class body is executed. Assigning the same `cached_property` object to a second class attribute, or attaching one to a class after the fact, leaves it without a usable name and raises `TypeError` on access; one decorator instance belongs to one attribute on one class. Until Python 3.11 the implementation held a lock so that concurrent first accesses computed the value once. Python 3.12 removed that lock, because it was shared across all instances of the class and serialised unrelated objects — a real bottleneck under threads. As of 3.12, and so on 3.14, several threads racing on the first access can each run the function; the results are all written to the same key and the last write wins. For a pure computation that is harmless duplicated work, but a `cached_property` whose body opens a connection, allocates a handle, or increments a counter is now a race you own. ## Choosing between them Use `property` when the value derives from state that changes, when the computation is cheap, or when read-only enforcement matters. Use `cached_property` when the instance is effectively immutable for the value's purposes, the computation is expensive enough to be worth remembering, and the instance's own lifetime is the right lifetime for the cached value — because that is exactly how long it will live.