Cachebox

5.2.3 · active · verified Thu Apr 16

Cachebox (v5.2.3) is a high-performance Python caching and memoization library, distinguished by its core implementation in Rust. It offers various thread-safe caching algorithms like LRU, FIFO, LFU, MRU, RR, TTL, and VTTL, designed for significantly faster execution and lower memory footprint compared to pure Python alternatives. The library is actively maintained and receives regular updates.

Common errors

```
NameError: name 'cachedmethod' is not defined
```
cause Attempting to use the `cachedmethod` decorator after it was deprecated in `cachebox` v5.1.0.

fix Update your code to use the `cached` decorator instead. For instance methods, if you need to ignore `self` for key generation, provide a `key_maker` function. Example: `@cached(cachebox.LRUCache(128), key_maker=lambda args, kwargs: args[1:])`.
```
ImportError: cannot import name '...' from 'cachebox' (libcachebox.so: cannot open shared object file: No such file or directory)
```
cause This error can occur on `musl`-based Linux distributions (like Alpine Linux) when `cachebox` v5.2.0 or specific `mimalloc` configurations are used, leading to issues with dynamic linking or memory allocation.

fix Ensure you are using `cachebox` v5.2.1 or newer, which includes a fix for `musl` compatibility related to `mimalloc`. If the issue persists, consider trying a different Python environment or consulting `cachebox`'s GitHub issues for `musl`-specific build instructions.
```
cachebox.OverflowError: The cache has reached the bound.
```
cause This error occurs when using a basic `Cache` (or similar non-evicting cache) that has a `maxsize` defined, and you attempt to insert more items than its capacity. The default `Cache` implementation does not have an eviction policy.

fix Use a cache implementation with an eviction policy (e.g., `LRUCache`, `FIFOCache`, `TTLCache`) if you want the cache to automatically discard old items when `maxsize` is reached. If you intend for the cache to have no size limit, set `maxsize=0` during initialization, or simply use a standard Python `dict`.

Warnings

deprecated The `cachedmethod` decorator was deprecated in `cachebox` v5.1.0. It is recommended to use the `cached` decorator instead, optionally providing a custom `key_maker` function for methods.
Fix: Replace `@cachebox.cachedmethod` with `@cachebox.cached` and implement a `key_maker` if the `self` parameter needs to be ignored for hashing.
breaking Starting with `cachebox` v5.0.2, support for Python 3.8 was dropped. Users on Python 3.8 will not be able to install or use newer versions of `cachebox`.
Fix: Upgrade your Python environment to 3.9 or newer. The library officially supports Python 3.9+.
gotcha Version 5.2.0 introduced `mimalloc` as the default allocator for some platforms, which caused issues on `musl` Linux systems. This was addressed in v5.2.1 with the addition of `local_dynamic_tls` mimalloc feature.
Fix: If experiencing runtime errors or performance degradation on `musl` Linux with `cachebox` v5.2.0, upgrade to v5.2.1 or newer.

Install

pip install cachebox Install stable release

Imports

cached
```
from cachebox import cached
```
LRUCache
```
from cachebox import LRUCache
```
TTLCache
```
from cachebox import TTLCache
```
cachedmethod
wrong:
```
from cachebox import cachedmethod
```
correct:
```
from cachebox import cached
```
`cachedmethod` was deprecated in v5.1.0; use `cached` and pass a custom `key_maker` if needed.

Quickstart

This quickstart demonstrates how to use the `@cached` decorator for memoization with a `LRUCache` and how to interact with a cache instance directly like a dictionary. It also shows how to check if a function is cached.

from cachebox import cached, LRUCache
import time

# Using the cached decorator with an LRU cache
@cached(LRUCache(maxsize=128))
def fetch_expensive_data(item_id: int) -> str:
    """Simulates an expensive data fetch."""
    print(f"Fetching data for item_id: {item_id}...")
    time.sleep(0.1) # Simulate network/computation delay
    return f"Data for {item_id}"

print(fetch_expensive_data(1))
print(fetch_expensive_data(2))
print(fetch_expensive_data(1)) # This will be cached

# Using a cache instance directly
my_cache = LRUCache(maxsize=10)
my_cache["key1"] = "value1"
print(my_cache.get("key1"))

# Check if a function is cached
print(f"Is fetch_expensive_data cached? {cached.is_cached(fetch_expensive_data)}")

view raw JSON →