Leveraging functools.lru_cache for Smarter Python Performance

Introduction

Every Python developer has encountered a function that does the same heavy lifting over and over again. Whether it's parsing a CSV, computing a Fibonacci sequence, or generating a cryptographic hash, the cost quickly adds up when the same inputs appear multiple times in a single run. The obvious solution is to store the result after the first computation and reuse it. The standard library already gives us a tiny, battle‑tested decorator that does exactly that: functools.lru_cache.

When Repeated Work Becomes a Bottleneck

In a recent data‑ingestion service I built, we needed to transform thousands of numeric IDs into human‑readable labels. The transformation required a database lookup for each ID, and the same IDs appeared in many rows. Without caching, the service spent more than 80 % of its CPU time re‑querying the same values. The fix was simple: memoize the lookup function. The result was a 15× speed‑up and a noticeable drop in database load.

The pattern is generic. Any pure function that is expensive and deterministic can benefit from memoization. The only prerequisite is that the function’s arguments are hashable, because the cache relies on a dictionary keyed by those arguments.

Meet functools.lru_cache

functools.lru_cache is a decorator that replaces the original function with a wrapper maintaining an internal least‑recently‑used (LRU) cache. When the wrapped function is called, Python first checks the cache; a hit returns the stored result instantly. A miss triggers the original function, stores its return value, and evicts the least‑recently‑used entry when the cache reaches its size limit.

The decorator is zero‑maintenance: you don't need to manually manage a dictionary or implement eviction logic. It also works transparently with class methods, static methods, and even generators (though you need to be careful about mutable yields).

import functools

@functools.lru_cache(maxsize=128)
def expensive_computation(x: int, y: int) -> int:
    """Simulate a heavy calculation.
    In a real scenario this could be a database query,
    a network request, or a CPU‑intensive algorithm.
    """
    # Replace with actual work
    return sum(range(x * y))

# First call computes and caches the result
print(expensive_computation(5, 3))  # 15
# Subsequent call hits the cache instantly
print(expensive_computation(5, 3))  # 15
print(expensive_computation.cache_info())  # shows hits, misses, etc.

The cache_info returns a namedtuple with statistics: hits, misses, maxsize, and currsize. These metrics are invaluable for profiling and tuning performance.

import functools

@functools.lru_cache(maxsize=None)
def factorial(n: int) -> int:
    """Return n! using simple recursion.
    The cache ensures each distinct n is computed only once.
    """
    if n < 2:
        return 1
    return n * factorial(n - 1)

# Usage
for i in range(1, 11):
    print(f"{i}! = {factorial(i)}")

# Inspect cache stats
print(factorial.cache_info())

import functools

class DateFormatter:
    @functools.lru_cache(maxsize=256)
    def format_date(self, date_str: str, locale: str) -> str:
        # Simulate an expensive formatting operation
        # In reality this might call an external library
        return f"{locale}:{date_str}"

fmt = DateFormatter()
print(fmt.format_date("2023-09-15", "en"))
print(fmt.format_date("2023-09-15", "en"))  # cache hit

import functools

@functools.lru_cache(maxsize=64)
def compute_pair(a: int, b: int) -> int:
    return a * a + b * b

# Create a cached function that always uses a = 5
square_sum_of_b = functools.partial(compute_pair, 5)
print(square_sum_of_b(10))  # 325
print(square_sum_of_b(10))  # cache hit

factorial.cache_clear()
print(factorial.cache_info())  # misses reset