Pythonpythondecoratorcachingperformanceproduction-ready

TTL Cache Decorator

A time-based cache decorator with configurable TTL, max size, and key generation for expensive function calls.

import time
import hashlib
import functools
from typing import TypeVar, Callable, Any, ParamSpec
from collections import OrderedDict
import threading

P = ParamSpec("P")
R = TypeVar("R")


class TTLCache:
    """Thread-safe LRU cache with time-based expiration."""

    def __init__(self, maxsize: int = 128, ttl: float = 300.0):
        self.maxsize = maxsize
        self.ttl = ttl
        self._cache: OrderedDict[str, tuple[float, Any]] = OrderedDict()
        self._lock = threading.Lock()
        self._hits = 0
        self._misses = 0

    def get(self, key: str) -> tuple[bool, Any]:
        with self._lock:
            if key in self._cache:
                expires_at, value = self._cache[key]
                if time.time() < expires_at:
                    # Move to end (most recently used)
                    self._cache.move_to_end(key)
                    self._hits += 1
                    return True, value
                else:
                    # Expired
                    del self._cache[key]
            self._misses += 1
            return False, None

    def set(self, key: str, value: Any) -> None:
        with self._lock:
            if key in self._cache:
                self._cache.move_to_end(key)
            self._cache[key] = (time.time() + self.ttl, value)
            # Evict oldest if over capacity
            while len(self._cache) > self.maxsize:
                self._cache.popitem(last=False)

    def invalidate(self, key: str) -> None:
        with self._lock:
            self._cache.pop(key, None)

    def clear(self) -> None:
        with self._lock:
            self._cache.clear()

    @property
    def stats(self) -> dict[str, int]:
        total = self._hits + self._misses
        return {
            "hits": self._hits,
            "misses": self._misses,
            "hit_rate": round(self._hits / total * 100, 1) if total > 0 else 0,
            "size": len(self._cache),
        }


def _make_key(args: tuple, kwargs: dict) -> str:
    """Generate a cache key from function arguments."""
    key_parts = [repr(arg) for arg in args]
    key_parts.extend(f"{k}={repr(v)}" for k, v in sorted(kwargs.items()))
    raw_key = ":".join(key_parts)
    return hashlib.md5(raw_key.encode()).hexdigest()


def cached(
    ttl: float = 300.0,
    maxsize: int = 128,
    key_fn: Callable[..., str] | None = None,
) -> Callable[[Callable[P, R]], Callable[P, R]]:
    """Decorator that caches function results with TTL expiration.

    Args:
        ttl: Time-to-live in seconds (default 5 minutes)
        maxsize: Maximum number of cached entries
        key_fn: Optional custom key generation function
    """
    cache = TTLCache(maxsize=maxsize, ttl=ttl)

    def decorator(func: Callable[P, R]) -> Callable[P, R]:
        @functools.wraps(func)
        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
            if key_fn:
                cache_key = key_fn(*args, **kwargs)
            else:
                cache_key = f"{func.__module__}.{func.__qualname__}:{_make_key(args, kwargs)}"

            hit, value = cache.get(cache_key)
            if hit:
                return value

            result = func(*args, **kwargs)
            cache.set(cache_key, result)
            return result

        # Expose cache management
        wrapper.cache = cache  # type: ignore
        wrapper.cache_clear = cache.clear  # type: ignore
        wrapper.cache_stats = lambda: cache.stats  # type: ignore
        return wrapper

    return decorator

title: "TTL Cache Decorator" description: "A time-based cache decorator with configurable TTL, max size, and key generation for expensive function calls." category: "Python" language: "python" tags: ["python", "decorator", "caching", "performance", "production-ready"] createdAt: "2025-02-08" updatedAt: "2025-02-28"

Overview

A production-ready caching decorator that combines LRU eviction with time-based expiration. Unlike functools.lru_cache, it supports TTL for automatic staleness management, thread safety, cache statistics, and manual invalidation.

Code

@cached(ttl=60.0, maxsize=256)
def expensive_query(user_id: str) -> dict:
    return db.fetch_user(user_id)

Notes

  • Thread-safe via threading.Lock for use in multi-threaded WSGI servers
  • LRU eviction prevents unbounded memory growth when maxsize is reached
  • MD5 hashing of args ensures consistent cache key length regardless of input size
  • cache_stats() exposes hit rate for monitoring cache effectiveness
  • For async functions, create an async_cached variant using asyncio.Lock instead