Fcache: File-Based Cache

0.6.0 · active · verified Sat Apr 11

Fcache is a Python library that provides a dictionary-like, file-based cache module. It is designed to be simple to use, includes an optional write buffer, and is compatible with Python's `shelve` module. The current version is 0.6.0, and releases occur on an as-needed basis, with the last major update in late 2024.

Warnings

gotcha Failing to call `FileCache.close()` can lead to data loss. Buffered writes to the file system may not be flushed, especially upon unexpected program termination.
Fix: Always call `.close()` on your `FileCache` instance when it's no longer needed, or use it within a `with` statement if context manager support is available (check documentation for future versions).
gotcha File-based caches, if not explicitly managed, can consume significant disk space over time. `fcache` does not automatically implement eviction policies like LRU or TTL out-of-the-box.
Fix: Periodically clear stale or unnecessary entries using `del mycache[key]` or `mycache.clear()` for the entire cache. Monitor disk usage of your cache directory.
breaking The `FileCache.delete()` method permanently removes the cache directory and all its contents from the file system. This operation is irreversible.
Fix: Use `FileCache.delete()` with extreme caution and ensure it's the intended action to completely destroy the cache. Consider backups if the cached data is critical.
gotcha While `fcache` leverages `shelve` for persistence, concurrent access from multiple processes or threads without proper synchronization mechanisms (not provided by `fcache` itself for all operations) could potentially lead to data corruption or race conditions, especially on write operations.
Fix: For highly concurrent or multi-process environments, implement external locking or ensure that only one process/thread modifies a specific cache instance at a time. Consult `shelve` documentation for its concurrency guarantees.

Install

pip install fcache Install stable version

Imports

FileCache
```
from fcache.cache import FileCache
```
The primary class `FileCache` resides within the `fcache.cache` submodule, not directly under `fcache`.

Quickstart

This quickstart demonstrates how to initialize a `FileCache`, store and retrieve data, check for key existence, update values, and properly close the cache to ensure data persistence. Re-opening verifies that the data is saved to disk.

from fcache.cache import FileCache

# Create a cache named 'myapp' in a default location
mycache = FileCache('myapp')

# Store data
mycache['greeting'] = 'Hello, Fcache!'
mycache['number'] = 123

# Retrieve data
print(f"Retrieved greeting: {mycache['greeting']}")
print(f"Retrieved number: {mycache['number']}")

# Check if a key exists
print(f"'greeting' in cache: {'greeting' in mycache}")

# Update data
mycache['greeting'] = 'Hola, Fcache!'
print(f"Updated greeting: {mycache['greeting']}")

# Close the cache to ensure data is flushed (important!)
mycache.close()

# Re-open and verify persistence
another_cache_instance = FileCache('myapp')
print(f"Re-opened greeting: {another_cache_instance['greeting']}")
another_cache_instance.close()

view raw JSON →