# light-cache
A Python package for using disk-based or object-bashed caching, perfect for simple scripts or Jupyter Notebooks.
## Features
✨ **Flexible Storage Options**
- Multiple cache storage modes (Memory, Disk, or Hybrid)
- Support for multiple independent cache stores
- Configurable cache directory location
⚡ **Performance**
- In-memory caching for fast access
- Disk persistence for data durability
- Hybrid mode for optimal performance and reliability
⚙️ **Advanced Cache Control**
- Automatic cache expiration
- Manual cache item removal
- Configurable default values for cache misses
- Non-expiring cache items support
🛠️ **Developer Friendly**
- Simple, intuitive API
- Perfect for scripts and Jupyter notebooks
- No external dependencies
- Lightweight alternative to Redis for simple use cases
## Install
Use pip to install:
```shell
pip install light-cache
```
## Usage
To get started, you need to set up a cache store:
```python
from light_cache import CacheStore
cache = CacheStore(persist_cache=True, keep_cache_in_memory=True)
```
There are three main modes for this cache:
1. **Disk cache**: Setting `persist_cache` to True and `keep_cache_in_memory` to False, the cache will read and write to a local cache file on each get/put operation. If you have many instances of a script running and need to keep the cache in sync, this is likely the right option.
2. **Memory cache**: Setting `persist_cache` to False and `keep_cache_in_memory` to True, keeps the cache in memory during the execution of the script or while the notebook is running. The cache will not persist between sessions. If you do not need the cache to exist after the session ends and have many computationally intensive functions during the execution, this is likely the right option.
3. **Hybrid** (default and recommended): Setting both to True will allow the cache to stay in memory during execution but save changes to a file to persist between sessions. For most use-cases of working in a notebook or creating small scripts that do not require full Redis or similar cache, this is likely the right option.
### Using multiple stores
You can set up different cache stores for different information. For example, if you need one store for just movies and another for podcasts, you could:
```python
from light_cache import CacheStore
movie_cache = CacheStore(store='movies')
podcast_cache = CacheStore(store='podcasts')
```
### Setting and retrieving values
The main methods are `get()`, `put()`, `has()`, and `forget()`.
```python
from light_cache import CacheStore
cache = CacheStore()
cache.put('some-key', 'some-value')
my_value = cache.get('some-key')
# `get()` returns None if cache doesn't exist. This can be changed using the `default` parameter
my_value = cache.get('some-nonexistent-key', default=0)
if cache.has('some-key'):
# do something
# `pull()` will retrieve a cached item and delete it from the cache if it exists
my_value = cache.pull('some-key')
# Expiration is in seconds (defaults to 5 minutes)
cache.put('new-key', 'new-value', expires=1200)
# Set to None for items that should not expire
cache.put('never-expire-key', 'never-expire-value', expires=None)
# Items that do not expire will remain in cache until the item is removed using `forget()`
cache.forget('never-expire-key')
```
### Change location of the cache directory
When using disk-based cache, the files are stored in `.cache/` but this can be changed:
```python
from light_cache import CacheStore
cache = CacheStore(cache_directory='src/app/cache')
```
## Contributing
Community made feature requests, patches, bug reports, and contributions are always welcome.
Please review [our contributing guidelines](https://github.com/fpcorso/light-cache/blob/main/CONTRIBUTING.md) if you decide to make a contribution.
### Setting up development environment
This project uses [Poetry](https://python-poetry.org/docs/) for managing dependencies and environments.
#### Tests
This project uses [pytest](https://docs.pytest.org/en/stable/) for its tests.
To run tests locally, use:
```shell
poetry run pytest
```
#### Formatter
This project uses [black](https://black.readthedocs.io/en/stable/index.html) for formatting. To run the formatter, use:
```shell
poetry run black .
```
## License
This project is licensed under the MIT License. See [LICENSE](https://github.com/fpcorso/light-cache/blob/main/LICENSE) for more details.
Raw data
{
"_id": null,
"home_page": "https://github.com/fpcorso/light-cache",
"name": "light-cache",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cache",
"author": "Frank Corso",
"author_email": "frank@frankcorso.me",
"download_url": "https://files.pythonhosted.org/packages/ba/73/88114305cb4a67ef026fc5147d493117c481654ee9a780994a9c55ef5a87/light_cache-0.2.1.tar.gz",
"platform": null,
"description": "# light-cache\n\nA Python package for using disk-based or object-bashed caching, perfect for simple scripts or Jupyter Notebooks.\n\n## Features\n\n\u2728 **Flexible Storage Options**\n- Multiple cache storage modes (Memory, Disk, or Hybrid)\n- Support for multiple independent cache stores\n- Configurable cache directory location\n\n\u26a1 **Performance**\n- In-memory caching for fast access\n- Disk persistence for data durability\n- Hybrid mode for optimal performance and reliability\n\n\u2699\ufe0f **Advanced Cache Control**\n- Automatic cache expiration\n- Manual cache item removal\n- Configurable default values for cache misses\n- Non-expiring cache items support\n\n\ud83d\udee0\ufe0f **Developer Friendly**\n- Simple, intuitive API\n- Perfect for scripts and Jupyter notebooks\n- No external dependencies\n- Lightweight alternative to Redis for simple use cases\n\n\n## Install\n\nUse pip to install:\n\n```shell\npip install light-cache\n```\n\n## Usage\n\nTo get started, you need to set up a cache store:\n\n```python\nfrom light_cache import CacheStore\n\ncache = CacheStore(persist_cache=True, keep_cache_in_memory=True)\n```\n\nThere are three main modes for this cache:\n\n1. **Disk cache**: Setting `persist_cache` to True and `keep_cache_in_memory` to False, the cache will read and write to a local cache file on each get/put operation. If you have many instances of a script running and need to keep the cache in sync, this is likely the right option.\n2. **Memory cache**: Setting `persist_cache` to False and `keep_cache_in_memory` to True, keeps the cache in memory during the execution of the script or while the notebook is running. The cache will not persist between sessions. If you do not need the cache to exist after the session ends and have many computationally intensive functions during the execution, this is likely the right option.\n3. **Hybrid** (default and recommended): Setting both to True will allow the cache to stay in memory during execution but save changes to a file to persist between sessions. For most use-cases of working in a notebook or creating small scripts that do not require full Redis or similar cache, this is likely the right option.\n\n### Using multiple stores\n\nYou can set up different cache stores for different information. For example, if you need one store for just movies and another for podcasts, you could:\n\n```python\nfrom light_cache import CacheStore\n\nmovie_cache = CacheStore(store='movies')\npodcast_cache = CacheStore(store='podcasts')\n```\n\n### Setting and retrieving values\n\nThe main methods are `get()`, `put()`, `has()`, and `forget()`.\n\n```python\nfrom light_cache import CacheStore\n\ncache = CacheStore()\n\ncache.put('some-key', 'some-value')\nmy_value = cache.get('some-key')\n\n# `get()` returns None if cache doesn't exist. This can be changed using the `default` parameter\nmy_value = cache.get('some-nonexistent-key', default=0)\n\nif cache.has('some-key'):\n # do something\n\n# `pull()` will retrieve a cached item and delete it from the cache if it exists\nmy_value = cache.pull('some-key')\n\n# Expiration is in seconds (defaults to 5 minutes)\ncache.put('new-key', 'new-value', expires=1200)\n\n# Set to None for items that should not expire\ncache.put('never-expire-key', 'never-expire-value', expires=None)\n\n# Items that do not expire will remain in cache until the item is removed using `forget()`\ncache.forget('never-expire-key')\n```\n\n### Change location of the cache directory\n\nWhen using disk-based cache, the files are stored in `.cache/` but this can be changed:\n\n```python\nfrom light_cache import CacheStore\n\ncache = CacheStore(cache_directory='src/app/cache')\n```\n\n## Contributing\n\nCommunity made feature requests, patches, bug reports, and contributions are always welcome.\n\nPlease review [our contributing guidelines](https://github.com/fpcorso/light-cache/blob/main/CONTRIBUTING.md) if you decide to make a contribution.\n\n### Setting up development environment\n\nThis project uses [Poetry](https://python-poetry.org/docs/) for managing dependencies and environments.\n\n#### Tests \n\nThis project uses [pytest](https://docs.pytest.org/en/stable/) for its tests.\n\nTo run tests locally, use:\n\n```shell\npoetry run pytest\n```\n\n#### Formatter\n\nThis project uses [black](https://black.readthedocs.io/en/stable/index.html) for formatting. To run the formatter, use:\n\n```shell\npoetry run black .\n```\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](https://github.com/fpcorso/light-cache/blob/main/LICENSE) for more details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple, lightweight caching library for disk-based or object-based caching",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/fpcorso/light-cache",
"Repository": "https://github.com/fpcorso/light-cache"
},
"split_keywords": [
"cache"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "82c85a00f697df8be4b6629f1d996833371e6a32ac2531fd0fec23879c388a86",
"md5": "794d960c802d10c3ad10f3b72e5d1046",
"sha256": "741bff23e7d6373b31bd0c6b2c16b09b98e2226a6ced7f22d12d355f79e5e449"
},
"downloads": -1,
"filename": "light_cache-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "794d960c802d10c3ad10f3b72e5d1046",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7801,
"upload_time": "2025-07-14T22:08:14",
"upload_time_iso_8601": "2025-07-14T22:08:14.148360Z",
"url": "https://files.pythonhosted.org/packages/82/c8/5a00f697df8be4b6629f1d996833371e6a32ac2531fd0fec23879c388a86/light_cache-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ba7388114305cb4a67ef026fc5147d493117c481654ee9a780994a9c55ef5a87",
"md5": "010c001f11e218ff5812f60d80cfcb55",
"sha256": "a90592ea0d24769be3085858e18b576f2bcd23099cf9d4aebbd4f11ad6c1c04a"
},
"downloads": -1,
"filename": "light_cache-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "010c001f11e218ff5812f60d80cfcb55",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 6683,
"upload_time": "2025-07-14T22:08:15",
"upload_time_iso_8601": "2025-07-14T22:08:15.258114Z",
"url": "https://files.pythonhosted.org/packages/ba/73/88114305cb4a67ef026fc5147d493117c481654ee9a780994a9c55ef5a87/light_cache-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 22:08:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fpcorso",
"github_project": "light-cache",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "light-cache"
}
JSON
