Leveraging Python's functools for Efficient Function Caching and Composition

Introduction

Have you ever re-run a function that takes seconds or minutes to compute, even though its inputs haven't changed? Or wished you could build complex behavior by composing small, well-tested functions? Python's functools module offers tools that solve both problems: caching to avoid repeated work, and composition utilities to assemble functions cleanly.

In this post you will learn:

• The core tools in functools for caching and composition.
• Practical, real-world code examples (with line-by-line explanations).
• How to combine functools with dataclasses for structured inputs.
• How to test caching and composition using pytest.
• Pitfalls when using caching with multiprocessing, and how to handle them.

Why caching and composition matter

• Caching (or memoization) saves time by storing previous results for repeat inputs.
• Composition builds complex behavior by chaining small functions — promoting testability and clarity.

• A web app that regenerates a slow report on each request.
• A data pipeline composed of many small transformations where you want to cache expensive steps.

Prerequisites and key concepts

• Pure functions: deterministic functions without side effects are ideal for caching.
• Hashable inputs: functions cached by functools.lru_cache rely on input arguments being hashable.
• Decorator basics: you'll wrap functions to add caching or to compose behavior.
• Dataclasses: handy for structured inputs/outputs. Use frozen dataclasses to be hashable.
• Testing and multiprocessing: be aware of process-local caches and how to test caching behavior.

Core tools in functools

• functools.lru_cache: least-recently-used cache decorator. Built-in, widely used.
• functools.cache: an unbounded cache (Python 3.9+). Equivalent to lru_cache(maxsize=None).
• functools.partial: fixes some arguments of a function; useful in composition.
• functools.reduce: combine functions or values iteratively.
• functools.wraps: preserves metadata in decorators.
• functools.singledispatch: generic function dispatch based on the type of the first argument (useful for composition extension).

Example 1 — Memoizing an expensive computation with lru_cache

A canonical example: Fibonacci. We'll use it to demonstrate caching mechanics.

from functools import lru_cache
@lru_cache(maxsize=128)
def fib(n: int) -> int:
    """Compute Fibonacci number (inefficient pure recursion)"""
    if n < 2:
        return n
    return fib(n - 1) + fib(n - 2)

Line-by-line:

• from functools import lru_cache — imports the decorator.
• @lru_cache(maxsize=128) — caches up to 128 distinct calls keyed by args/kwargs.
• def fib(n: int) -> int: — signature; only hashable ints are used.
• Base case and recursion — the naive algorithm becomes efficient because repeated subcalls hit cache.

• fib(35) will compute quickly with caching vs exponential time without caching.
• Access cache stats with fib.cache_info() → returns hits, misses, current size, maxsize.

• Passing unhashable types (e.g., lists) will raise TypeError when trying to cache keyed by them. Use tuples or frozen dataclasses instead.

>>> fib.cache_info()
CacheInfo(hits=67, misses=36, maxsize=128, currsize=36)
>>> fib(10)
55
>>> fib.cache_clear()  # reset cache

Example 2 — Caching with dataclasses as inputs

When inputs are structured, dataclasses make code readable. But remember: default dataclasses are mutable and unhashable. Use frozen dataclasses for cache keys.

from dataclasses import dataclass
from functools import lru_cache
@dataclass(frozen=True)
class Query:
    user_id: int
    start: str  # ISO date
    end: str
@lru_cache(maxsize=256)
def generate_report(query: Query) -> dict:
    """
    Simulate a heavy report generation that depends on a structured Query.
    Since Query is frozen, it's hashable and safe to use with lru_cache.
    """
    # Simulated heavy work
    import time
    time.sleep(0.5)
    return {"user_id": query.user_id, "range": (query.start, query.end)}

Explanation:

• dataclass(frozen=True) makes instances immutable and hashable.
• Passing a Query instance to generate_report works with lru_cache.
• This pattern blends Mastering Python's dataclasses for Structured Data Management with caching.

• If the dataclass references mutable objects (like lists), even if frozen=True you may still have unhashable contents. Prefer immutable types (tuples, strings).

Example 3 — Function composition: building pipelines

Let’s compose small transformations into a pipeline. We'll create a reusable compose utility using functools.reduce.

from functools import reduce, wraps
from typing import Callable, Iterable
def compose(funcs: Callable) -> Callable:
    """Return a function that is the composition of the given functions.
    compose(f, g, h)(x) == f(g(h(x)))
    """
    if not funcs:
        raise ValueError("At least one function must be provided")

    def _compose_two(f, g):
        @wraps(f)
        def inner(args, *kwargs):
            return f(g(args, *kwargs))
        return inner

    return reduce(_compose_two, funcs)

def strip(text: str) -> str:
    return text.strip()
def lower(text: str) -> str:
    return text.lower()
def remove_punctuation(text: str) -> str:
    import re
    return re.sub(r'[^\w\s]', '', text)
clean = compose(remove_punctuation, strip, lower)
print(clean("  Hello, WORLD!  "))  # "hello world"

from functools import lru_cache
@lru_cache(maxsize=1024)
def tokenize(text: str) -> tuple:
    # simulate expensive tokenization
    import time
    time.sleep(0.2)
    return tuple(text.split())
def stem(tokens: tuple) -> list:
    # cheap
    return [t.rstrip('ing') for t in tokens]
def pipeline(text: str) -> list:
    return stem(tokenize(text))

import time
from mymodule import tokenize  # the function above
def test_tokenize_cache(monkeypatch):
    calls = {"count": 0}
    def fake_sleep(sec):
        calls["count"] += 1
        # don't actually sleep during tests
    monkeypatch.setattr("time.sleep", fake_sleep)
    # first call: misses -> calls fake_sleep
    t1 = tokenize("hello world")
    # second call: should be cached, no fake_sleep call
    t2 = tokenize("hello world")
    assert t1 is not None
    assert t1 == t2
    assert calls["count"] == 1  # only first invocation simulated sleeping

from mymodule import tokenize
def test_cache_info_reset():
    tokenize.cache_clear()
    info = tokenize.cache_info()
    assert info.hits == 0

from mymodule import compose, strip, lower
def test_compose_order():
    clean = compose(strip, lower)
    assert clean("  HeLLo ") == "hello"

from multiprocessing import Manager, Pool
from dataclasses import dataclass
@dataclass(frozen=True)
class Key:
    x: int
def expensive_compute(k: Key):
    # This function will be executed in worker processes.
    # Use some shared cache or recompute.
    return k.x  k.x

If shared caching is required in heavy parallel workloads, prefer an external cache (Redis, memcached) or pre-serialize results to files to be memory-mapped.

Performance note:

• Multiprocessing adds IPC cost — measure and choose appropriate parallelism.
• For CPU-bound tasks, multiprocessing helps; for I/O-bound tasks, consider threading or async.

Best practices and performance considerations

• Prefer pure functions for caching.
• Use frozen dataclasses for structured, hashable inputs: combines Mastering Python's dataclasses for Structured Data Management with functools.
• Set sensible maxsize in lru_cache. Unbounded caches may cause memory leaks.
• Use cache_clear() responsibly in long-running processes to free memory.
• For multi-process or distributed systems, use external caches (Redis) for shared state.
• For testing, use pytest and monkeypatch fixtures to simulate external effects and assert caching behavior: aligns with Creating Robust Unit Tests with pytest: Strategies and Best Practices.
• Profile with timeit or cProfile to ensure caching results justify memory costs.
• Preserve function metadata with functools.wraps when writing decorators.

Common pitfalls

• Passing unhashable args (lists, dicts) into cached functions → TypeError.
• Caching functions with side effects leads to subtle bugs (e.g., DB writes become skipped).
• Relying on lru_cache for persistence across process restarts — lru_cache is in-memory only.
• Thinking that lru_cache is thread/process-safe: it's thread-safe for CPython but not a distributed solution.

Advanced tips

• Use functools.partial to create pre-filled functions that can be cached separately.
• Combine functools.singledispatch with caching for type-specific implementations.
• For very large caches with eviction policies, consider cachetools (TTL, LFU).
• When composing many small functions, test components individually — composition is only as reliable as its parts.
• Use typed=True in lru_cache (Python 3.8+) to treat different argument types as different keys:

Real-world pattern: cached computation + multiprocessing workers

A suggested pattern for heavy computations where workers should avoid recomputing:

1. Precompute a results table in the main process (or external store).
2. Serialize to a memory-mapped file or write to Redis.
3. Worker processes read from the shared store (fast) rather than recomputing.

Performance demonstration

Quick benchmark skeleton:

import timeit
setup = """
from mymodule import fib
"""
stmt = "fib(30)"
print(timeit.timeit(stmt, setup=setup, number=10))

Compare cached vs non-cached versions to confirm speedups.

Conclusion

functools gives Python developers a compact, powerful toolkit for:

• Function caching with lru_cache/cache for performance gains.
• Function composition to build clean, testable pipelines.

Try it now:

• Add lru_cache to an expensive function in your project.
• Convert complex input types to frozen dataclasses and cache safely.
• Write a pytest that asserts a cache hit to validate improved performance.

Further reading and references

• functools documentation — https://docs.python.org/3/library/functools.html
• dataclasses documentation — https://docs.python.org/3/library/dataclasses.html
• pytest documentation — https://docs.pytest.org/
• multiprocessing documentation — https://docs.python.org/3/library/multiprocessing.html
• cachetools (third-party) — https://cachetools.readthedocs.io/