fcache

library0.6.0pypypi✓ verified 24d ago

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.

database

pip install fcache

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · FCACHE

fcache

databasepythonv0.6.0

Install

1.7s avg

Import

56ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.058s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.054s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FileCache

✓ from fcache.cache import FileCache

✗ import fcache

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

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()

Debug

Known issues

gotchaFailing 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).

affects: All versions

gotchaFile-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.

affects: All versions

breakingThe `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.

affects: All versions

gotchaWhile `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.

affects: All versions

Errors

Common errors & fixes

KeyError: 'some_key'

Attempting to access a key in the FileCache that does not exist.

fix

Check if the key exists before accessing it, or use the `.get()` method with a default value. For example: `value = mycache.get('some_key', default_value)` or `if 'some_key' in mycache: value = mycache['some_key']`

PermissionError: [Errno 13] Permission denied: '/path/to/cache/file'

The Python process does not have the necessary write permissions for the directory where fcache is trying to create or modify cache files.

fix

Ensure the directory specified for the `FileCache` instance has appropriate write permissions for the user running the Python script, or specify a cache directory where write permissions are granted. For example, `mycache = FileCache('myapp', flag='cs', app_cache_dir='/tmp/my_cache_dir')`

ModuleNotFoundError: No module named 'fcache'

The 'fcache' library is either not installed in the Python environment or the import statement is incorrect.

fix

First, install the library using pip: `pip install fcache`. Then, ensure the correct import statement is used: `from fcache.cache import FileCache`

Upgrade

Version history

0.6.0latest on PyPI · released Nov 19, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/tsroten/fcache ↗

packagehttps://pypi.org/project/fcache/ ↗

docshttps://tsroten.github.io/fcache ↗

changeloghttps://tsroten.github.io/fcache/history.html ↗