functools @lru_cache — Cross-User Cache Leak

Every Python developer hits a wall where their functions start to feel repetitive, slow, or just clunky. You write the same boilerplate wrapper around a function to add logging. You call the same expensive database query 50 times with the same arguments. You create a dozen tiny one-liner lambdas that all do slightly different versions of the same thing. These aren't signs you're a bad programmer — they're signs you haven't met functools yet.

The functools module ships inside Python's standard library and exists for one reason: higher-order functions. A higher-order function is just a function that either takes another function as input or returns one as output. functools packages up the most useful patterns for working with functions — caching, partial application, reduction, and decoration — so you don't have to reinvent them every project. It's the toolkit that separates code that just works from code that's elegant, fast, and maintainable.

By the end of this article you'll know exactly what lru_cache, partial, reduce, wraps, and total_ordering do, when each one earns its keep, and the subtle traps that catch even experienced developers off guard. You'll walk away with patterns you can drop into real projects today — not toy examples that you'll never use again.

What functools @lru_cache Actually Does — And Where It Breaks

functools is a standard Python module providing higher-order functions and operations on callable objects. Its @lru_cache decorator memoizes function results based on arguments, using an LRU (least recently used) eviction policy. The cache is a dictionary keyed by the arguments, with a bounded size (default 128). When the cache fills, the least recently used entry is discarded. This is O(1) for hit/miss lookup, but the memory cost is proportional to the number of distinct argument tuples seen.

In practice, the cache lives on the function object itself — it's a mutable attribute shared across all callers. This means if you decorate a function in a module, every request, thread, or user in the same process shares the same cache. The default maxsize=128 is small, but unbounded (maxsize=None) can silently consume all available memory. The cache is not thread-safe for writes without a lock, though reads are safe.

Use @lru_cache for pure, deterministic functions with expensive computation and a limited argument space — think recursive Fibonacci, parsing fixed schemas, or memoizing database query results for a single user session. Never use it for functions that depend on mutable state, have side effects, or are called with user-specific arguments in a multi-tenant service. The cache is process-local and does not expire based on time.

lru_cache — Stop Recomputing Things You've Already Figured Out

LRU stands for 'Least Recently Used'. The idea is simple: the first time you call a function with a given set of arguments, Python runs the function normally and stores the result in a small memory cache. The second time you call it with the exact same arguments, Python skips the function body entirely and hands you the cached answer instantly.

This is called memoization, and it's a game-changer for any function that's expensive to run — API calls, recursive algorithms, database lookups, mathematical computations. The 'LRU' part means the cache has a maximum size (default 128 entries). When it's full, the result that was accessed least recently gets evicted to make room. That's your memory safety net.

The decorator syntax @lru_cache means zero boilerplate. You don't touch the function's logic at all — you just stick the decorator on top. One critical rule though: every argument you pass must be hashable. Lists and dicts can't be cached because they're mutable — Python has no reliable way to use them as a cache key. If you need to cache a function that takes a list, convert it to a tuple first.

import functools
import time

# Without caching this naive recursive fibonacci is catastrophically slow.
# fib(40) makes over 300 million recursive calls.
@functools.lru_cache(maxsize=128)  # Cache up to 128 unique argument combinations
def fibonacci(n):
    """Return the nth Fibonacci number using memoized recursion."""
    if n < 2:
        return n
    # On the second call with the same n, this line never executes — cache takes over
    return fibonacci(n - 1) + fibonacci(n - 2)

# --- Demonstrating the speed difference ---
start = time.perf_counter()
result = fibonacci(50)  # Would take minutes without caching
elapsed = time.perf_counter() - start

print(f"fibonacci(50) = {result}")
print(f"Computed in {elapsed:.6f} seconds")

# lru_cache gives you a built-in stats tool — use it to verify caching is working
cache_info = fibonacci.cache_info()
print(f"Cache hits: {cache_info.hits}")    # How many times cache answered instead of the function
print(f"Cache misses: {cache_info.misses}") # How many times the function actually ran
print(f"Cache size: {cache_info.currsize}") # How many results are stored right now

# Call again with a cached value to see hits go up
_ = fibonacci(50)
print(f"\nAfter second call — Cache hits: {fibonacci.cache_info().hits}")

partial — Pre-Load Arguments So You Don't Repeat Yourself

Here's a scenario: you have a general-purpose function that takes five arguments, but in 90% of your codebase you always pass the same values for three of them. You end up writing the same three arguments over and over, which is noisy, error-prone, and exhausting to change later.

functools.partial solves this by letting you create a new function with some arguments already baked in. The original function stays untouched. You're just creating a specialised version of it with a shorter signature. Think of it like a stamp — you carve the repeated parts into the stamp, then only deal with the parts that change.

This is especially powerful when working with callbacks, event handlers, or any API that expects a function with a specific signature. You can adapt a general function to fit an exact signature by locking in the arguments it already knows. It's cleaner than a lambda, more self-documenting, and plays better with tools like map() and filter() because partial objects are proper callables with introspectable attributes.

import functools

# A general-purpose logging function with many configurable parameters
def log_message(level, timestamp_format, application_name, message):
    """Write a formatted log line."""
    import datetime
    timestamp = datetime.datetime.now().strftime(timestamp_format)
    print(f"[{timestamp}] [{level}] [{application_name}] {message}")

# In our payments service we always use the same level, format, and app name.
# Instead of passing all four args every single time, we create a specialised version.
payments_logger = functools.partial(
    log_message,
    level="ERROR",                # Locked in — always ERROR for this logger
    timestamp_format="%H:%M:%S",  # Locked in — always this format
    application_name="PaymentsService"  # Locked in
)

# Now we only supply the one argument that actually changes: the message
payments_logger(message="Card charge failed — insufficient funds")
payments_logger(message="Refund processing timeout after 30s")

print()

# --- Another real-world use: adapting functions for map() ---
def apply_discount(price, discount_rate):
    """Return price after applying a percentage discount."""
    return round(price * (1 - discount_rate), 2)

# Black Friday — everything gets a 30% discount
# We lock in the discount_rate so map() only needs to supply price
black_friday_discount = functools.partial(apply_discount, discount_rate=0.30)

original_prices = [99.99, 149.99, 29.99, 199.99]
discounted_prices = list(map(black_friday_discount, original_prices))

print("Original prices: ", original_prices)
print("After 30% off:   ", discounted_prices)

# You can inspect what was locked in — great for debugging
print(f"\nLocked-in keywords: {black_friday_discount.keywords}")
print(f"Underlying function: {black_friday_discount.func.__name__}")

wraps and reduce — The Two Tools You'll Reach for More Than You Expect

functools.wraps is small but critical. Whenever you write a decorator, you wrap one function inside another. Without wraps, the inner wrapper function steals the identity of the original — its name, docstring, and type hints all vanish. This breaks documentation generators, debuggers, logging tools, and anything that introspects function metadata. One line — @functools.wraps(original_function) — copies all that metadata onto your wrapper so the original function's identity is preserved.

functools.reduce is a different beast. It takes a function and an iterable, then applies the function cumulatively: first to elements 1 and 2, then to that result and element 3, and so on until one value remains. It was built-in in Python 2, but Python 3 moved it to functools to discourage overuse — because a for-loop is often clearer. That said, reduce shines when you need to collapse a sequence using a non-trivial combiner function, especially one you've already defined. sum(), max(), and min() cover the obvious cases — reach for reduce when none of those fit.

import functools
import operator

# ── PART 1: functools.wraps ──────────────────────────────────────────────────

def execution_timer(func):
    """A decorator that measures how long a function takes to run."""
    @functools.wraps(func)  # WITHOUT this, wrapper.__name__ would be 'wrapper', not the real name
    def wrapper(*args, **kwargs):
        import time
        start = time.perf_counter()
        result = func(*args, **kwargs)  # Call the original function
        elapsed = time.perf_counter() - start
        print(f"  ⏱  {func.__name__} completed in {elapsed:.4f}s")
        return result
    return wrapper

@execution_timer
def fetch_user_profile(user_id):
    """Simulate fetching a user profile from a database."""
    import time
    time.sleep(0.05)  # Simulated DB latency
    return {"id": user_id, "name": "Alex Rivera", "plan": "premium"}

profile = fetch_user_profile(user_id=42)

# Because we used @wraps, the function's true identity is intact
print(f"Function name:    {fetch_user_profile.__name__}")  # 'fetch_user_profile', not 'wrapper'
print(f"Docstring:        {fetch_user_profile.__doc__}")
print()

# ── PART 2: functools.reduce ─────────────────────────────────────────────────

# Real-world scenario: merge a list of permission dictionaries into one
# Each dict represents permissions granted by a different role
role_permissions = [
    {"read": True,  "write": False, "delete": False},
    {"read": True,  "write": True,  "delete": False},
    {"read": True,  "write": True,  "delete": True },
]

def merge_permissions(accumulated, new_role):
    """Union two permission dicts — True wins over False (most permissive merge)."""
    return {key: accumulated[key] or new_role[key] for key in accumulated}

# reduce applies merge_permissions left-to-right across the list
final_permissions = functools.reduce(merge_permissions, role_permissions)
print("Merged permissions:", final_permissions)

# Classic use: compute a product of a list (no built-in like sum() exists for this)
monthly_growth_rates = [1.05, 1.03, 1.07, 1.02]  # 5%, 3%, 7%, 2% monthly growth
cumulative_growth = functools.reduce(operator.mul, monthly_growth_rates, 1.0)
print(f"Cumulative growth over 4 months: {cumulative_growth:.4f}x")  # ~1.1837x

total_ordering — Write Two Methods, Get All Six Comparisons Free

If you've ever written a Python class that needs to support sorting — think products sorted by price, tasks sorted by priority, events sorted by date — you've probably realised Python wants you to implement up to six comparison methods: __lt__, __le__, __gt__, __ge__, __eq__, and __ne__. Most of that code is painfully repetitive because they're all logically related. If you can say when A < B, Python can mathematically derive the rest.

functools.total_ordering is the decorator that does exactly this. You implement __eq__ and just one of __lt__, __le__, __gt__, or __ge__. The decorator fills in the remaining four for you, inferring them logically. This is genuinely useful when building data classes that don't use Python's dataclass(order=True) shorthand — for example, when your comparison logic is non-trivial or based on computed properties rather than direct field values.

The performance cost is tiny for most use cases, but be aware: the generated methods are slightly slower than hand-written ones because they go through an extra layer of indirection. If you're sorting millions of objects in a tight loop, profile first.

import functools

@functools.total_ordering  # Give us all comparison operators from just two methods
class SupportTicket:
    """
    A customer support ticket. Tickets are compared by priority first,
    then by creation time if priorities are equal.
    Lower priority number = higher urgency (1 is most critical).
    """
    PRIORITY_LABELS = {1: "Critical", 2: "High", 3: "Medium", 4: "Low"}

    def __init__(self, ticket_id, priority, created_at):
        self.ticket_id = ticket_id
        self.priority = priority    # 1 = most urgent
        self.created_at = created_at

    def __repr__(self):
        label = self.PRIORITY_LABELS[self.priority]
        return f"Ticket({self.ticket_id}, {label})"

    def __eq__(self, other):
        if not isinstance(other, SupportTicket):
            return NotImplemented  # Let Python handle comparison with other types gracefully
        return (self.priority, self.created_at) == (other.priority, other.created_at)

    def __lt__(self, other):
        if not isinstance(other, SupportTicket):
            return NotImplemented
        # Lower priority number = more urgent = comes first in sorted order
        return (self.priority, self.created_at) < (other.priority, other.created_at)

    # @total_ordering generates __le__, __gt__, __ge__ automatically from __eq__ and __lt__

import datetime

tickets = [
    SupportTicket("TKT-004", priority=3, created_at=datetime.datetime(2024, 6, 1, 10, 0)),
    SupportTicket("TKT-001", priority=1, created_at=datetime.datetime(2024, 6, 1,  9, 0)),
    SupportTicket("TKT-007", priority=2, created_at=datetime.datetime(2024, 6, 1, 11, 0)),
    SupportTicket("TKT-003", priority=1, created_at=datetime.datetime(2024, 6, 1,  8, 0)),
]

# sorted() works because total_ordering gave us all the operators we needed
priority_queue = sorted(tickets)
print("Tickets in priority order:")
for ticket in priority_queue:
    print(f"  {ticket}")

# The generated operators work correctly
print(f"\nTKT-001 > TKT-007?  {tickets[1] > tickets[2]}")  # True — priority 1 beats priority 2
print(f"TKT-004 >= TKT-007? {tickets[0] >= tickets[2]}")  # False — priority 3 is less urgent

cached_property — Lazy Attribute Caching for Expensive Computations

Sometimes you have a class attribute that's expensive to compute and only needs to be calculated once per instance. Think of a complex regex compilation, a database query, or a large calculation based on instance data. You don't want to recompute it every time it's accessed, but you also don't want to precompute it in __init__ if it might not be used.

functools.cached_property is designed for exactly this. It's a decorator that turns a method into a property whose value is computed once on first access and then cached for the lifetime of the instance. Unlike lru_cache, it's tied to the instance and automatically clears when the instance is garbage collected.

Use this for expensive, read-only attributes that are deterministic given the instance's state. It's especially valuable in data science code where you have derived columns, or in ORM models where you join related data lazily.

import functools
import re
import time

class DataPipeline:
    def __init__(self, raw_data: list):
        self.raw_data = raw_data

    @functools.cached_property
    def cleaned_data(self):
        """Expensive cleaning operation: only computed when first accessed."""
        print("  [CLEANING] Running expensive data cleaning...")
        time.sleep(0.5)  # Simulate heavy processing
        # Remove None values, strip whitespace, lowercase
        return [str(item).strip().lower() for item in self.raw_data if item is not None]

    @functools.cached_property
    def token_pattern(self):
        """Compile a regex pattern once and cache it."""
        return re.compile(r'\w+')

    def search(self, term):
        """Use cached pattern to search in cleaned data."""
        return [item for item in self.cleaned_data if self.token_pattern.search(term)]

pipeline = DataPipeline(['Alice', None, 'Bob', 'CHARLIE', '  dave  '])

# First access triggers cleaning
print("First access of cleaned_data:")
result = pipeline.cleaned_data
print(f"  Result: {result}\n")

# Second access uses cache (no "CLEANING" output)
print("Second access of cleaned_data:")
result2 = pipeline.cleaned_data
print(f"  Result: {result2}\n")

# The pattern is also cached
print("Searching for 'alice'...")
print(f"  Found: {pipeline.search('alice')}")

# cached_property can be reset by deleting the attribute
print("\nDeleting cached_property to force recompute...")
del pipeline.cleaned_data
print("After delete, accessing again:")
result3 = pipeline.cleaned_data
print(f"  Result: {result3}")

Why functools Exists — Stop Writing Plumbing, Start Shipping Logic

Every production codebase I've triaged has the same smell: ten different hand-rolled caching schemes, comparison methods copy-pasted across six models, and partial function applications done with lambdas that are impossible to debug at 3 AM. The functools module exists to kill that pattern waste.

It's a collection of higher-order functions — callables that take or return other callables. That sounds academic, but in practice it means you write the core logic once and let functools handle the boilerplate. Every team I've seen that adopts it cuts incidental complexity by a measurable chunk.

The why is simple: Python's dynamic nature means you spend a lot of time writing repetitive function wrappers. functools gives you battle-tested versions of those patterns so you don't have to debug your own half-baked dictionary cache during an outage. It's not optional reading — it's the difference between a codebase that scales and one that requires a full rewrite every six months.

// io.thecodeforge — python tutorial

# Before: custom caching that broke under load
cache = {}
def get_user_profile(user_id):
    if user_id not in cache:
        cache[user_id] = database.query(...)
    return cache[user_id]

# After: one decorator, zero bugs
from functools import lru_cache

@lru_cache(maxsize=256)
def get_user_profile(user_id):
    return database.query(...)

singledispatch — When isinstance Checks Become Technical Debt

Every codebase starts with an if-else chain checking type. Then the types multiply. Then the chain becomes a switch statement across modules. Then someone new joins and adds a branch that breaks the edge case you forgot. singledispatch is the surgical fix.

It lets you define a generic function — a single dispatch — and then register specialized implementations for specific types. The dispatch happens at runtime based on the first argument's type. No isinstance, no type-coercion hacks, no accidental fallthrough.

I've used this to clean up serialization pipelines, API response formatters, and payment gateway adapters. The pattern is always the same: one entry point, N type-specific handlers, and you add a new type by writing one function decorator, not touching the dispatch logic. That's the kind of extensibility that survives team turnover.

// io.thecodeforge — python tutorial

from functools import singledispatch
from dataclasses import dataclass

@dataclass
class Invoice:
    id: int
    total: float

@dataclass
class CreditNote:
    id: int
    refund: float

@singledispatch
def export_to_csv(document):
    raise NotImplementedError(f"Type {type(document)} not supported")

@export_to_csv.register(Invoice)
def _(doc: Invoice):
    return f"{doc.id},{doc.total}"

@export_to_csv.register(CreditNote)
def _(doc: CreditNote):
    return f"{doc.id},{doc.refund}"

# Usage — no if-else in sight
print(export_to_csv(Invoice(42, 150.0)))
print(export_to_csv(CreditNote(7, -50.0)))

cmp_to_key — Why Your Sort Customisation Is Probably Broken

Python 3 removed the cmp argument from sort() and sorted(). Good riddance — writing comparison functions that return -1, 0, or 1 was error-prone and slow. But sometimes you inherit a C extension or a legacy library that expects an old-style comparator. That's when cmp_to_key saves your sprint.

It converts a comparison function into a key function that sorted() can use. The implementation is small: it wraps each element into an object that uses your comparator for __lt__, __gt__, etc. But the real value is compatibility — you don't rewrite the comparator, you just slap cmp_to_key on it and move on.

That said, don't reach for this by default. Write a proper key function (a lambda returning a tuple, a custom class with __lt__, or operator.attrgetter) first. cmp_to_key is a bridge, not a destination. I've only needed it on two production systems in the last five years, and both times it was for integrating with a third-party library that was stuck in Python 2 patterns.

// io.thecodeforge — python tutorial

from functools import cmp_to_key

# Old-style comparator from a library you can't modify
def priority_comparator(task_a, task_b):
    if task_a['priority'] < task_b['priority']:
        return -1
    elif task_a['priority'] > task_b['priority']:
        return 1
    else:
        return 0

tasks = [
    {'id': 'deploy', 'priority': 2},
    {'id': 'rollback', 'priority': 1},
    {'id': 'test', 'priority': 3}
]

# Convert and sort
sorted_tasks = sorted(tasks, key=cmp_to_key(priority_comparator))
for t in sorted_tasks:
    print(f"{t['id']}: {t['priority']}")

update_wrapper — Stop Copying Metadata By Hand (Or Breaking Your Decorators)

You wrote a decorator. Clean. Minimal. Then someone runs help(your_decorated_function) and gets the wrapper's signature instead of the original function's. Or inspect.getsource() fails. Or any self-respecting debugging tool lies to you.

That's update_wrapper — explicitly or via @functools.wraps, which calls update_wrapper under the hood. It copies __name__, __qualname__, __doc__, __module__, __dict__, and the all-important __wrapped__ from the original function to the wrapper.

Why the __wrapped__ attribute? It lets inspect.unwrap() drill through layers of decorators to find the real function. Production tooling depends on this. Forgetting it is junior-hour nonsense.

Use @functools.wraps on every decorator you write. Not optional. Treat it like a lint rule that fires when it's absent.

// io.thecodeforge — python tutorial

import functools
from datetime import datetime


def log_call(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = datetime.now()
        result = func(*args, **kwargs)
        elapsed = (datetime.now() - start).total_seconds()
        print(f"{func.__name__} took {elapsed:.3f}s")
        return result
    return wrapper


@log_call
def compute_payload(product_id: str) -> dict:
    """Fetch product metadata from cache or source."""
    time.sleep(0.2)  # simulate work
    return {"id": product_id, "status": "active"}


print(f"Function name: {compute_payload.__name__}")
print(f"Docstring: {compute_payload.__doc__}")
help(compute_payload)

Key Features — The One-Page Cheat Sheet Every Python Dev Should Tape To Their Monitor

The functools module has an identity. Every function solves one precise production problem. Stop reaching for hand-written plumbing.

partial — Lock arguments upfront. Use it when you call the same function with the same argument 50 times. Saves keystrokes, but more importantly, removes noise.

lru_cache / cache — Pure function? Add one decorator, get memoization for free. Works on I/O too, but watch the cache invalidation trap. cache is unbounded; lru_cache evicts old entries under memory pressure.

cached_property — For objects where an attribute is expensive to compute but never changes per instance. Saves recomputation on every access. Descriptor protocol, runs once, then lives in __dict__.

singledispatch — Type-based dispatch without the if-elif-else tree. Your isinstance() switch statements become maintainable function registrations.

// io.thecodeforge — python tutorial

from functools import partial, lru_cache, cached_property, wraps, singledispatch
import time

# partial - pre-configure arguments
def connect(host, port, timeout, retries):
    return f"Connecting to {host}:{port} (timeout={timeout}, retries={retries})"


connect_local = partial(connect, "127.0.0.1", 8080, timeout=5)
print(connect_local(retries=2))


# lru_cache - avoid redundant computation
@lru_cache(maxsize=128)
def get_shipping_cost(weight_kg: float, zone: str) -> float:
    print(f"  Computing cost for {zone} zone...")
    time.sleep(0.2)  # expensive
    return weight_kg * {"domestic": 3.0, "international": 12.0}[zone]


print(f"\nShipping cost: ${get_shipping_cost(2.5, 'domestic')}")
print(f"Shipping cost (cached): ${get_shipping_cost(2.5, 'domestic')}")


# key features callout
print(f"\nCache info: {get_shipping_cost.cache_info()}")

// io.thecodeforge — python tutorial

from functools import singledispatch
import json

@singledispatch
def serialize(obj):
    return str(obj)

@serialize.register(int)
def _(obj):
    return json.dumps({"int": obj})

@serialize.register(list)
def _(obj):
    return json.dumps([serialize(x) for x in obj])

@serialize.register(dict)
def _(obj):
    return json.dumps({k: serialize(v) for k, v in obj.items()})

print(serialize(42))      # {"int": 42}
print(serialize([1,2,3])) # [{"int":1},{"int":2},{"int":3}]

// io.thecodeforge — python tutorial

from functools import partial

def log(level, message, timestamp):
    print(f"[{timestamp}] {level}: {message}")

# Pre-load timestamp and level
import time
info_log = partial(log, "INFO", time.ctime())
error_log = partial(log, "ERROR", time.ctime())

# Use later without repeating args
info_log("System running")   # [Mon...] INFO: System running
error_log("Disk full")      # [Mon...] ERROR: Disk full

print(info_log.func)       # <function log at 0x...>
print(info_log.args)       # ('INFO', 'Mon...')

from functools import cache, lru_cache

@cache
def factorial(n):
    return n * factorial(n-1) if n else 1

@lru_cache(maxsize=32)
def get_data(user_id):
    # Simulate expensive API call
    return {"id": user_id, "data": "..."}

from functools import total_ordering

@total_ordering
class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

    def __eq__(self, other):
        return self.age == other.age

    def __lt__(self, other):
        return self.age < other.age

# Now all comparisons work:
p1 = Person("Alice", 30)
p2 = Person("Bob", 25)
print(p1 > p2)  # True (uses __gt__ generated from __lt__ and __eq__)

from functools import reduce
from itertools import accumulate

numbers = [1, 2, 3, 4, 5]

# reduce: single product
product = reduce(lambda x, y: x * y, numbers)
print(product)  # 120

# accumulate: running product
running_product = list(accumulate(numbers, lambda x, y: x * y))
print(running_product)  # [1, 2, 6, 24, 120]