cachetools

cachetools provides various memoizing collections and decorators for Python, including variants of the standard library’s @lru_cache function decorator. A cache in this module is a mutable mapping of a fixed maximum size; when full, the cache discards items based on a chosen cache algorithm (LRU, LFU, TTL, FIFO, RR, and more).

The library exposes both cache classes (LRUCache, TTLCache, etc.) that behave as regular dict-like mappings, and @cached/@cachedmethod decorators that wrap functions or methods to transparently memoize their results against any of those cache instances, including thread-safe usage via an explicit lock argument.

What You Get

• Cache classes implementing LRU, LFU, TTL, FIFO, RR, and other eviction algorithms as dict-like mutable mappings
• @cached and @cachedmethod decorators for memoizing plain functions and instance/class methods
• A keys module for building custom cache keys from function arguments (e.g. ignoring specific parameters)
• Thread-safe usage support via an explicit lock argument on the decorators
• A func module offering functools.lru_cache-compatible drop-in decorators backed by cachetools’ cache classes

Common Use Cases

• Memoizing expensive pure-function calls (recursive algorithms, API lookups) with an LRU or TTL bound
• Caching per-instance computed properties or expensive method calls via @cachedmethod
• Rate-limiting external API calls by caching responses for a fixed TTL window
• Replacing ad-hoc dict-based caches with a maintained, size-bounded, thread-safe alternative

Under The Hood

Architecture - The package is organized as a small src/cachetools module: __init__.py (774 lines) defines the cache classes (Cache, LRUCache, LFUCache, TTLCache, FIFOCache, RRCache, etc.) as subclasses of a shared MutableMapping-based base, _cached.py and _cachedmethod.py implement the decorator logic separately for functions vs. methods, and keys.py provides key-generation helpers used by the decorators. Tech Stack - Pure Python with no runtime dependencies, using only the standard library’s collections.abc and time modules; packaged with a standard pyproject.toml/src-layout build. Code Quality - 14 test modules under tests/ cover the individual cache classes and decorators, CI runs via GitHub Actions with Codecov coverage reporting badges shown in the README, and the codebase is stable/mature (mature project per repo-health signals) with infrequent but steady maintenance. API Design - the cache classes are deliberately dict-like (MutableMapping subclasses), so users already familiar with Python dicts can drop them in directly; the @cached(cache=...) decorator mirrors functools.lru_cache’s ergonomics while accepting any cache instance, keeping the public surface small and consistent across eviction strategies.