Why does functools.lru_cache raise TypeError when a list is passed as an argument?

## Why hashability is not negotiable A memoization cache has to answer "have I seen this call before?" in less time than recomputing the result. The only data structure in Python that answers that in constant time is the dictionary, and dictionary keys must be hashable. So the requirement is not a design choice the decorator made; it falls straight out of the mechanism. The wrapper builds one key object from the whole call — the positional arguments, a marker, then the keyword arguments as name/value pairs — and hashes it. Hashing a tuple hashes each element, so one unhashable argument anywhere in the call poisons the whole key. Mutable built-in containers (`list`, `dict`, `set`, `bytearray`) define no `__hash__`, and a class that defines `__eq__` without `__hash__` also becomes unhashable. The failure surfaces as `TypeError: unhashable type: 'list'` raised from the wrapper, so the traceback points at the decorated call site and not at anything inside the function body — which is a useful tell when you are reading someone else's stack trace. ## Fixing it The honest fix is usually to change the parameter type. If the function conceptually takes a sequence of values, take a `tuple`; if it takes a set of flags, take a `frozenset`; if it takes options, take individual keyword parameters rather than an options `dict`. Callers converting at the boundary is cheap and makes the immutability contract explicit. When you cannot change the public signature, split the function: an uncached outer function normalises the arguments into hashable form, and a cached inner function does the work. ```python import functools @functools.lru_cache(maxsize=512) def _score(values): # values is a tuple return sum(values) / len(values) def score(values): # public API still accepts a list return _score(tuple(values)) ``` The cost is real and worth stating: the normalisation runs on every call, hit or miss, so the conversion must be much cheaper than the work being cached. Converting a million-element list to a tuple on every call to save a cheap computation is a net loss. A third option people reach for — wrapping the mutable argument in a class with a custom `__hash__` — is a trap unless the object really is immutable in practice. If the object mutates after being used as a key, the cache will return an answer computed for a state the object no longer has, which is far worse than the `TypeError` you were avoiding. ## Two surprises in how the key is built **Calling convention is part of the key.** The key is built from how the call was *written*, not from the bound parameters. `scale(3)` and `scale(3, factor=2)` are two entries even when the default makes them identical, and `k(a=1, b=2)` and `k(b=2, a=1)` are two entries because keyword arguments enter the key in the order they were passed. A caller that varies its style therefore halves the hit rate for free. If a hot path is inconsistent about this, normalise at the boundary the same way you would for hashability. **typed=False collapses equal-but-differently-typed values.** By default the key compares by equality, so in a two-argument call `g(1, 2)` and `g(1.0, 2.0)` share one entry — the second is a hit and gets an `int`-derived result. That is usually what you want; when the function's output actually differs by type, pass `typed=True` and the arguments' types become part of the key. ## The related trap: mutable *results* Hashability constrains what goes in. Nothing constrains what comes out, and the cache stores the returned object itself. If the cached function returns a list, the first caller and every later hit share one list; an `append` by any of them is visible to all of them, and the corruption looks like a cache that is "returning wrong answers". Return immutable results from cached functions, and if the caller genuinely needs a mutable copy, let the caller copy it. ## What this tells an interviewer The `TypeError` itself is a five-second answer. The interesting half is what you do next: recognising that the requirement is structural rather than arbitrary, choosing between changing the signature and splitting the function, weighing the normalisation cost against the cached work, and knowing that the same key machinery quietly rewards callers who are consistent about positional versus keyword style.