Why does an @functools.lru_cache-decorated function raise TypeError when passed a list?

## The key is a dictionary key The memoizing wrapper is, underneath, a dictionary. To look anything up it must turn the call into a key, and it builds that key out of the arguments themselves. Dictionary keys must be hashable, so the arguments must be hashable. When they are not, hashing the key raises: ```python import functools @functools.lru_cache def total(values): return sum(values) total([1, 2, 3]) # TypeError: unhashable type: 'list' ``` Two details of that failure catch people out. First, it happens on the way *in*: the body never runs, so nothing you wrote is in the traceback and the function looks broken even though the decorator is what refused. Second, it is not a rule about mutability in general but about hashability specifically: `list`, `dict`, `set` and `bytearray` are out; `tuple`, `frozenset`, `str`, `bytes`, numbers, `None` and ordinary objects that inherit the default identity hash are all fine. A tuple *containing* a list is not hashable either, because hashing a tuple hashes its items. ## The key is not normalised The wrapper does not inspect the signature, does not bind defaults, and does not sort keyword arguments. The key is the positional arguments, then a marker, then the keyword arguments in the order the caller wrote them. That has three consequences worth being able to state: ```python import functools @functools.lru_cache def scale(value, factor=2): return value * factor scale(10) scale(10, 2) scale(10, factor=2) print(scale.cache_info()) # three misses, zero hits ``` All three calls mean the same thing and every one of them missed. Callers that write the same call two ways silently halve the hit rate. Swapping the order of two keyword arguments produces yet another key. None of this is a bug — normalising would mean binding the signature on every call, which would cost more than the cache saves — but it is why a cache with a surprisingly low hit rate is often a call-site consistency problem rather than a sizing problem. ## typed, and the 1 versus 1.0 case By default the key relies on ordinary hashing and equality. `hash(1) == hash(1.0)` and `1 == 1.0`, so `f(1)` and `f(1.0)` land on the same entry and the second call gets the first call's result. `True` and `1` collide the same way. If the function's result depends on the *type* — a formatter, a serialiser, anything that branches on `isinstance` — pass `typed=True` and the argument types become part of the key, at the cost of more entries: ```python import functools @functools.lru_cache(typed=True) def kind(x): return type(x).__name__ print(kind(1), kind(1.0)) # int float print(kind.cache_info()) # two misses ``` With `typed=False` that same function would report `int` for both calls — a wrong answer produced by a cache, which is the worst kind. ## Custom objects Your own class is cacheable by default because objects inherit identity-based `__hash__` and `__eq__`: two distinct instances that look identical are two entries. Define `__eq__` without `__hash__` and Python sets `__hash__` to `None`, making instances unhashable and the cache unusable — a common surprise with hand-written value classes. A frozen dataclass, or a class that defines both, keys by value and behaves the way you probably wanted. Note that a value-keyed object stays reachable from the cache for as long as its entry lives. ## Living with unhashable input The standard shape is a thin public function that normalises and a cached inner function that only ever sees hashable arguments: ```python import functools @functools.lru_cache(maxsize=256) def _parse(frozen_options): return dict(frozen_options) def parse(options): return _parse(tuple(sorted(options.items()))) ``` The alternative is to cache on the handful of scalar fields that actually vary, which usually produces a better hit rate anyway. What you must not do is cache on a mutable object and then mutate it: even when it is hashable by identity, the entry now describes a state that no longer exists. ## Concurrency The cache's own bookkeeping is lock-protected, so concurrent calls will not corrupt it. It does *not* promise that the body runs once per key: two threads that miss on the same key at the same time both run the function and both store a result. For a pure function that is wasted work, not a bug — but if you were relying on the cache to deduplicate an expensive side effect, you were relying on something it never offered.