functools in practice: lru_cache, cached_property, partial and singledispatch

What it is

functools bundles higher-order helpers. @lru_cache(maxsize=128) memoises a function by its arguments, which must be hashable; @cache is the unbounded form; cache_info() returns hits, misses, maxsize and current size, cache_clear() empties the cache and __wrapped__ reaches the original function. @cached_property computes an attribute once per instance and stores it in the instance dictionary. partial(f, *args, **kw) freezes arguments and returns a callable exposing .func, .args and .keywords. @singledispatch turns a function into a generic function dispatching on the class of its first argument; register accepts a type annotation and, since 3.11, a Union; @singledispatchmethod dispatches on the first argument after self. @wraps copies name, docstring and other metadata onto a decorator's wrapper.

Why it matters

Each replaces something usually written by hand (a module-level cache dict, a lambda adapter, an isinstance chain) with a standard tool whose behaviour under introspection, threads and cache limits is documented.

How to apply

• Cache only pure functions whose result does not depend on time or external state; bound maxsize in long-running processes and read cache_info() in a test to confirm the cache is actually hit.
• Do not put lru_cache on instance methods. The Python FAQ explains that it creates a reference to the instance, so instances stay alive until they age out of the cache; use cached_property for argument-free per-instance values, which the FAQ notes keeps results only as long as the instance lives.
• Use partial for callback adaptation; unlike a lambda it exposes .func, .args and .keywords, so logs and tests can see what was bound.
• With singledispatch, register implementations from the modules that own the types (a serialiser learns about a new type without editing the central function); the fallback implementation should raise TypeError or NotImplementedError explicitly.
• Always apply @wraps(func) in hand-written decorators so help(), tracebacks and __wrapped__ work.

Pitfalls

The documentation warns that distinct argument patterns are distinct keys: f(a=1, b=2) and f(b=2, a=1) may have separate cache entries. cached_property needs an instance __dict__, so it does not work on __slots__ classes; the documentation suggests stacking @property over @lru_cache there. Under threads, the cached function may run more than once for the same arguments before the first call completes. singledispatch annotations must name classes (or a Union of classes); dispatch ignores the other arguments entirely.