shelved-cache

What it is and what it does

shelved-cache adds disk persistence to cachetools cache objects, allowing you to wrap any cachetools cache (LRU, TTL, etc.) so that cached entries are automatically written to a file and survive program restarts. You create a PersistentCache instance around a cachetools cache class, then use it exactly like the underlying cache—reading and writing entries works the same way, but data persists to disk via Python's shelve module.

The package also provides async-aware decorators (cachedasyncmethod, cachedfunction) that work with both synchronous and asynchronous functions, and a utility function (autotuple_hashkey) to make list arguments hashable for caching. It's a thin layer on top of cachetools, designed for applications that need simple file-backed caching without external dependencies like Redis.

Use it for:

• Cache expensive function results across program runs without setting up a database or external cache service.
• Decorate async methods with persistent caching using the async decorator support.
• Build a simple memoization layer for CLI tools or batch scripts that benefit from remembering past computations.
• Persist LRU or TTL cache state to disk for recovery after crashes or restarts.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Wraps cachetools cache implementations with disk persistence, allowing cached data to survive across program restarts while maintaining the same cache interface.

Yes, if you need simple disk-backed caching and don't want external dependencies. The low install friction, permissive license, and straightforward API make it a reasonable choice for small to medium projects. However, be aware that the package is aging (last release 242 days ago) and has a known issue on Windows with Python 3.13+; verify that issue doesn't affect your platform before committing to it for production use.

Install

shelved-cache on PyPI

pip install shelved-cache

uv add shelved-cache

poetry add shelved-cache

Installing shelved-cache

Before you install

Low friction install with a single runtime dependency (cachetools). Maintenance status is aging—last release was 242 days ago—but the repository remains active and the package supports current Python versions through 3.14.

License in practice

MIT license is permissive; you can use this package freely in commercial and private projects with minimal restrictions.

Quickstart

pip install shelved-cache

from shelved_cache import PersistentCache
from cachetools import LRUCache

pc = PersistentCache(LRUCache, filename='mycache', maxsize=2)
pc["key"] = 42
print(pc["key"])  # 42
pc.close()

Requires Python 3.10 or later. Known permission errors reported on Windows with Python 3.13 and above.

Verify before relying

• Whether the Windows permission issue on Python 3.13+ affects your use case or has been resolved in practice.
• Performance characteristics when cache files grow large or are accessed frequently across multiple processes.

Package facts

Evidence: shelved_cache-0.5.0-py3-none-any.whl

Tags

More Database packages