functools.cache vs lru_cache(None): Localhost Lab

Intro — what this post promises

Memoize with functools.cache, lru_cache(maxsize=None), and a manual dict. This lab reports warm calls/s on Linux localhost.

It is not lru-cache hit/miss sizing (lab 52). Focus: unbounded cache vs the cache() alias vs hand-rolled dict.

Related links:

• lru cache hit miss localhost lab
• graphlib topo vs manual localhost lab
• tomllib vs json localhost lab
• path glob vs fnmatch localhost lab
• heapq merge vs sorted localhost lab
• islice vs list slice localhost lab
• dataclass replace vs manual localhost lab
• zoneinfo vs utc offset localhost lab

Lab honesty (1 Oct 2026 IST): Python 3.13.5. Affiliates: 0. Warm paths after fill.

Verdict up front: poly warm (5000 keys) — cache ~23517348 calls/s ≈ lru_cache(None) ~23540822 > manual ~14943394; single-key hits — lru ~28187316, cache ~25639379, manual ~11053470.

Arms

Lab topology

fib N=30 · poly 5000 args · hit inner 200k · 7 rounds · p50 warm
metric: calls/s = work_units / p50_s

Script: lab-evidence/115-functools-cache-vs-lru/results/run_lab.py.

Lead table — warm poly (5000 args, p50)

Hit micro & fib warm

cache and lru_cache(None) track each other — expected, since cache is documented as that unbounded wrapper.

Alias clarity

In CPython, functools.cache is implemented as lru_cache(maxsize=None). Treat them as one mechanism with two spellings — pick cache for readability unless you already standardize on lru_cache across the codebase.

Cold vs warm

Cold fib fills ~N entries quickly; warm calls are essentially a single hash lookup returning the root. Poly cold must insert 5000 keys once — after that, wrappers stay ahead of a pure-Python if x in d loop on this box.

Reading it

• Prefer @cache for unbounded pure memo (clearer than maxsize=None).
• Need eviction → sized lru_cache (lab 52 for hit/miss sizing).
• Manual dict only when you need custom keys/eviction/metrics.
• Typed/unhashable args still fail — wrappers need hashables.

When manual dict still wins

Custom composite keys, soft references, metrics counters, or per-tenant partitions often force an explicit dict (or WeakValueDictionary — see the weakref cache lab). For plain hashable args and unbounded memo, prefer @cache and skip maintaining your own if k in d boilerplate.

Threading caveat

lru_cache / cache are generally fine for concurrent reads of already-populated entries, but fill storms and cache_clear need care in multi-threaded servers. This lab is single-threaded warm lookups only — do not extrapolate to lock-free claims.

Bounded sibling

If RSS growth is the fear, switch to lru_cache(maxsize=…) and tune with lab 52’s hit/miss methodology. Unbounded wrappers here intentionally match “remember everything” workloads, not the eviction design space.

Pitfalls

• Unbounded growth on huge key spaces (memory leak).
• Caching impure functions (time, I/O, globals).
• Comparing to lab 52’s bounded hit/miss story without noting maxsize.
• Clearing caches in tests but not in long-running workers.

Reproduce

python3 lab-evidence/115-functools-cache-vs-lru/results/run_lab.py

Evidence: summary.json, summary.txt.

Limits

One Linux box. Hashable int keys only. Not threaded cache contention. Not typed=True variants.

Takeaway

Warm poly lookups: cache ≈ lru_cache(None) ~23517348 calls/s beat manual ~14943394. Use @cache for unbounded memo; use sized lru_cache when you need eviction (see lab 52).