Typing stubs for cachetools

6.2.0.20260317 · active · verified Sun Mar 29

types-cachetools provides static type annotations for the cachetools library, enabling type checkers like MyPy and Pyright to validate code that utilizes caching mechanisms. The current version, 6.2.0.20260317, aims to provide accurate annotations for cachetools versions 6.2.*. It is part of the typeshed project, which collects high-quality type stubs for various Python packages.

Warnings

breaking Breaking change in `cachetools` v5.0.0: Deprecated submodules like `cachetools.ttl` were removed. Imports must now be directly from the top-level `cachetools` package (e.g., `from cachetools import TTLCache`).
Fix: Update import statements: change `from cachetools.submodule import Symbol` to `from cachetools import Symbol`.
breaking Breaking change in `cachetools` v5.0.0: The `key` function passed to the `@cachedmethod` decorator now receives `self` as its first positional argument. Custom `key` functions must be updated to accept this argument.
Fix: Adjust custom `key` functions for `@cachedmethod` to accept `self` (e.g., `def my_key_func(self, *args, **kwargs): ...`). The default key function correctly ignores `self`.
gotcha Type checking `TTLCache` with `datetime.now` as `timer` and `datetime.timedelta` for `ttl` might lead to MyPy errors because `types-cachetools` (historically) often expected `float` for `ttl` if the `timer` returns a `float` (like `time.monotonic`). While `cachetools` supports `datetime.datetime` for `timer`, the stubs might not perfectly align without explicit casting or type ignores.
Fix: Consider using `time.monotonic` for `timer` and `float` for `ttl` for simpler typing. If using `datetime.now`, ensure your type checker configuration is robust or use `typing.cast` / `# type: ignore` as a last resort until stubs are updated to fully support `datetime` types for `TTLCache`'s timer/ttl arguments.
breaking Breaking change in `cachetools` v6.0.0: The `MRUCache` class and its corresponding `@func.mru_cache` decorator were removed.
Fix: Migrate away from `MRUCache` to an alternative caching strategy like `LRUCache` or `FIFOCache`.
breaking Breaking change in `cachetools` v7.0.0: Dropped support for passing `info` as a fourth positional parameter to the `@cached` decorator. The `info` argument should now be accessed as `cache.info()` directly.
Fix: Remove the `info` positional parameter from `@cached` decorator calls and retrieve cache statistics via `cache.info()`.
breaking Breaking change in `cachetools` v7.0.0: Dropped support for `cache(self)` returning `None` with `@cachedmethod` to suppress caching. Cache suppression should be handled through other means or by modifying the cache itself.
Fix: Review and refactor code that relies on `cache(self)` returning `None` in `@cachedmethod` to disable caching. Implement explicit logic to manage cache entries instead.
gotcha The `types-cachetools` version 6.2.0.20260317 explicitly states it targets `cachetools==6.2.*`. However, the current `cachetools` release is 7.0.5. Using `types-cachetools` 6.2.x with `cachetools` 7.x may lead to type checking inconsistencies, missing annotations for new `cachetools` 7.x features, or incorrect types for changed APIs.
Fix: Be aware of potential type mismatches. If encountering type errors, temporarily pin `cachetools` to `~=6.2.0` or wait for `types-cachetools` to release stubs compatible with `cachetools` 7.x. Alternatively, use `# type: ignore` sparingly for known incompatibilities.

Install

pip install types-cachetools Install types-cachetools

Imports

LRUCache
```
from cachetools import LRUCache
```
TTLCache
```
from cachetools import TTLCache
```
cached
```
from cachetools import cached
```
cachedmethod
```
from cachetools import cachedmethod
```
ttl_cache
```
from cachetools.func import ttl_cache
```
While older versions of cachetools might have exposed func decorators directly from the top-level package, the recommended and type-safe way to import them is from the cachetools.func submodule.

Quickstart

This quickstart demonstrates basic usage of `cachetools` decorators like `@cached` with `LRUCache` and `TTLCache`. With `types-cachetools` installed, type checkers will provide static analysis for these caching patterns, helping to ensure correct usage of cache parameters and function signatures.

from cachetools import cached, LRUCache, TTLCache
import time

# Example 1: LRUCache decorator
@cached(cache=LRUCache(maxsize=2))
def expensive_function(arg):
    print(f"Calculating expensive_function({arg})")
    time.sleep(0.1) # Simulate work
    return arg * 2

print("--- LRUCache Example ---")
print(expensive_function(1)) # Calculates
print(expensive_function(2)) # Calculates
print(expensive_function(1)) # Cache hit
print(expensive_function(3)) # Calculates, evicts 2
print(expensive_function(2)) # Calculates again

# Example 2: TTLCache decorator
@cached(cache=TTLCache(maxsize=1, ttl=0.5))
def time_sensitive_data(key):
    print(f"Fetching time_sensitive_data({key})")
    return f"Data for {key} @ {time.time():.2f}"

print("\n--- TTLCache Example ---")
print(time_sensitive_data("report")) # Calculates
print(time_sensitive_data("report")) # Cache hit
time.sleep(0.6) # Wait for cache to expire
print(time_sensitive_data("report")) # Calculates again

view raw JSON →