# persist-cache
<a href="https://pypi.org/project/persist-cache/" alt="PyPI Version"><img src="https://img.shields.io/pypi/v/persist-cache"></a> <a href="https://github.com/umarbutler/persist-cache/actions/workflows/ci.yml" alt="Build Status"><img src="https://img.shields.io/github/actions/workflow/status/umarbutler/persist-cache/ci.yml?branch=main"></a> <a href="https://app.codecov.io/gh/umarbutler/persist-cache" alt="Code Coverage"><img src="https://img.shields.io/codecov/c/github/umarbutler/persist-cache"></a> <!-- <a href="https://pypistats.org/packages/persist-cache" alt="Downloads"><img src="https://img.shields.io/pypi/dm/persist-cache"></a> -->
`persist-cache` is an *easy-to-use* Python library for lightning-fast persistent function caching. It is capable of caching both synchronous and asynchronous functions as well as methods, and is also process-safe and thread-safe.
## Features 🎯
- **⚡ Lightning-fast**: a function call can be cached in as little as 145 microseconds and be returned back in as few as 95 microseconds.
- **💽 Persistent**: cached returns persist across sessions and are stored locally.
- **⌛ Stale-free**: cached returns may be given a shelf life, after which they will be automatically flushed out.
- **🦺 Process- and thread-safe**: interprocess file locks prevent processes and threads from writing over each other.
- **⏱️ Async-compatible**: asynchronous functions can be cached with the same decorator as synchronous ones, generators included.
- **👨🏫 Class-compatible**: methods can be cached with the same decorator as functions (although the `self` argument is always ignored).
## Installation 🧑🔧
`persist-cache` may be installed with `pip`:
```bash
pip install persist-cache
```
## Usage 👩💻
The code snippet below demonstrates how both synchronous and asynchronous functions as well as methods may be cached with `persist-cache`:
```python
from persist_cache import cache
@cache
def my_function(): ...
@cache
async def my_function(): ...
class MyClass:
@cache
def my_method(self): ...
@cache
async def my_method(self): ...
```
It is also possible to name caches and specify their shelf life:
```python
from datetime import timedelta
@cache(name='my_shared_cache', expiry=timedelta(months=1))
def my_function(): ...
@cache(name='my_shared_cache', expiry=60 * 60 * 24 * 30)
def my_other_function(): ...
```
Once created, cached functions may be managed as follows:
```python
# Change cached returns to expire after an hour.
my_function.set_expiry(60 * 60)
# Flush out any expired cached returns.
my_function.flush_cache() or persist_cache.flush(my_function, 60 * 60) or persist_cache.flush('my_shared_cache', 60 * 60)
# Clear out all cached returns.
my_function.clear_cache() or persist_cache.clear(my_function) or persist_cache.clear('my_shared_cache')
# Delete the cache.
my_function.delete_cache() or persist_cache.delete(my_function) or persist_cache.delete('my_shared_cache')
```
## API 🧩
### `cache()`
```python
def cache(
name: str | Callable | None = None,
dir: str | None = None,
expiry: int | float | timedelta | None = None,
) -> None
```
`cache()` persistently and locally cache the returns of a function.
The function to be cached must accept and return [dillable](https://dill.readthedocs.io/en/latest/) objects only (with the exception of methods' `self` argument, which is always ignored). Additionally, for consistent caching across subsequent sessions, arguments and returns should also be hashable.
`name` represents the name of the cache (or, if `cache()` is being called as an argument-less decorator (ie, as `@cache` instead of `@cache(...)`), the function to be cached). It defaults to the qualified name of the function. If `dir` is set, `name` will be ignored.
`dir` represents the directory in which the cache should be stored. It defaults to a subdirectory named after the hash of the cache's name in a parent folder named '.persist_cache' in the current working directory.
`expiry` represents how long, in seconds or as a `timedelta`, function calls should persist in the cache. It defaults to `None`.
If `cache()` is called with arguments, a decorator that wraps the function to be cached will be returned, otherwise, the wrapped function itself will be returned.
After being wrapped, the cached function will have the following methods attached to it:
- `set_expiry(value: int | float | timedelta) -> None`: Sets the expiry of the cache.
- `flush_cache() -> None`: Flushes out any expired cached returns.
- `clear_cache() -> None`: Clears out all cached returns.
- `delete_cache() -> None`: Deletes the cache.
### `flush()`
```python
def flush(
function_or_name: str | Callable,
expiry: int | float | timedelta,
) -> None
```
`flush()` flushes out any expired cached returns from a cache.
`function_or_name` represents the function or the name of the cache to be flushed.
### `clear()`
```python
def clear(function_or_name: str | Callable) -> None
```
`clear()` clears out all cached returns from a cache.
`function_or_name` represents the function or the name of the cache to be cleared.
### `delete()`
```python
def delete(function_or_name: str | Callable) -> None
```
`delete()` deletes a cache.
`function_or_name` represents the function or the name of the cache to be deleted.
## Licence 📜
This library is licensed under the [MIT Licence](https://github.com/umarbutler/persist-cache/blob/main/LICENCE).
Raw data
{
"_id": null,
"home_page": null,
"name": "persist-cache",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "cache, caching, decorator, function, functions, local, memoisation, memoise, memoization, memoize, optimisation, optimise, optimising, optimization, optimize, optimizing, performance, persistent, speed",
"author": null,
"author_email": "Umar Butler <umar@umar.au>",
"download_url": "https://files.pythonhosted.org/packages/4a/1e/aad4e5b573586ddd9fd8d9c8ea4594a96806b5eab66ea1fd8d728e86c964/persist_cache-0.4.3.tar.gz",
"platform": null,
"description": "# persist-cache\n<a href=\"https://pypi.org/project/persist-cache/\" alt=\"PyPI Version\"><img src=\"https://img.shields.io/pypi/v/persist-cache\"></a> <a href=\"https://github.com/umarbutler/persist-cache/actions/workflows/ci.yml\" alt=\"Build Status\"><img src=\"https://img.shields.io/github/actions/workflow/status/umarbutler/persist-cache/ci.yml?branch=main\"></a> <a href=\"https://app.codecov.io/gh/umarbutler/persist-cache\" alt=\"Code Coverage\"><img src=\"https://img.shields.io/codecov/c/github/umarbutler/persist-cache\"></a> <!-- <a href=\"https://pypistats.org/packages/persist-cache\" alt=\"Downloads\"><img src=\"https://img.shields.io/pypi/dm/persist-cache\"></a> -->\n\n`persist-cache` is an *easy-to-use* Python library for lightning-fast persistent function caching. It is capable of caching both synchronous and asynchronous functions as well as methods, and is also process-safe and thread-safe.\n\n## Features \ud83c\udfaf\n- **\u26a1 Lightning-fast**: a function call can be cached in as little as 145 microseconds and be returned back in as few as 95 microseconds.\n- **\ud83d\udcbd Persistent**: cached returns persist across sessions and are stored locally.\n- **\u231b Stale-free**: cached returns may be given a shelf life, after which they will be automatically flushed out.\n- **\ud83e\uddba Process- and thread-safe**: interprocess file locks prevent processes and threads from writing over each other.\n- **\u23f1\ufe0f Async-compatible**: asynchronous functions can be cached with the same decorator as synchronous ones, generators included.\n- **\ud83d\udc68\u200d\ud83c\udfeb Class-compatible**: methods can be cached with the same decorator as functions (although the `self` argument is always ignored).\n\n## Installation \ud83e\uddd1\u200d\ud83d\udd27\n`persist-cache` may be installed with `pip`:\n```bash\npip install persist-cache\n```\n\n## Usage \ud83d\udc69\u200d\ud83d\udcbb\nThe code snippet below demonstrates how both synchronous and asynchronous functions as well as methods may be cached with `persist-cache`:\n```python\nfrom persist_cache import cache\n\n@cache\ndef my_function(): ...\n\n@cache\nasync def my_function(): ...\n\nclass MyClass:\n @cache\n def my_method(self): ...\n\n @cache\n async def my_method(self): ...\n```\n\nIt is also possible to name caches and specify their shelf life:\n```python\nfrom datetime import timedelta\n\n@cache(name='my_shared_cache', expiry=timedelta(months=1))\ndef my_function(): ...\n\n@cache(name='my_shared_cache', expiry=60 * 60 * 24 * 30)\ndef my_other_function(): ...\n```\n\nOnce created, cached functions may be managed as follows:\n```python\n# Change cached returns to expire after an hour.\nmy_function.set_expiry(60 * 60)\n\n# Flush out any expired cached returns.\nmy_function.flush_cache() or persist_cache.flush(my_function, 60 * 60) or persist_cache.flush('my_shared_cache', 60 * 60)\n\n# Clear out all cached returns.\nmy_function.clear_cache() or persist_cache.clear(my_function) or persist_cache.clear('my_shared_cache')\n\n# Delete the cache.\nmy_function.delete_cache() or persist_cache.delete(my_function) or persist_cache.delete('my_shared_cache')\n```\n\n## API \ud83e\udde9\n### `cache()`\n```python\ndef cache(\n name: str | Callable | None = None,\n dir: str | None = None,\n expiry: int | float | timedelta | None = None,\n) -> None\n```\n\n`cache()` persistently and locally cache the returns of a function.\n \nThe function to be cached must accept and return [dillable](https://dill.readthedocs.io/en/latest/) objects only (with the exception of methods' `self` argument, which is always ignored). Additionally, for consistent caching across subsequent sessions, arguments and returns should also be hashable.\n \n`name` represents the name of the cache (or, if `cache()` is being called as an argument-less decorator (ie, as `@cache` instead of `@cache(...)`), the function to be cached). It defaults to the qualified name of the function. If `dir` is set, `name` will be ignored.\n\n`dir` represents the directory in which the cache should be stored. It defaults to a subdirectory named after the hash of the cache's name in a parent folder named '.persist_cache' in the current working directory.\n \n`expiry` represents how long, in seconds or as a `timedelta`, function calls should persist in the cache. It defaults to `None`.\n\nIf `cache()` is called with arguments, a decorator that wraps the function to be cached will be returned, otherwise, the wrapped function itself will be returned.\n\nAfter being wrapped, the cached function will have the following methods attached to it:\n- `set_expiry(value: int | float | timedelta) -> None`: Sets the expiry of the cache.\n- `flush_cache() -> None`: Flushes out any expired cached returns.\n- `clear_cache() -> None`: Clears out all cached returns.\n- `delete_cache() -> None`: Deletes the cache.\n\n### `flush()`\n```python\ndef flush(\n function_or_name: str | Callable,\n expiry: int | float | timedelta,\n) -> None\n```\n\n`flush()` flushes out any expired cached returns from a cache.\n\n`function_or_name` represents the function or the name of the cache to be flushed.\n\n### `clear()`\n```python\ndef clear(function_or_name: str | Callable) -> None\n```\n\n`clear()` clears out all cached returns from a cache.\n\n`function_or_name` represents the function or the name of the cache to be cleared.\n\n### `delete()`\n```python\ndef delete(function_or_name: str | Callable) -> None\n```\n\n`delete()` deletes a cache.\n\n`function_or_name` represents the function or the name of the cache to be deleted.\n\n## Licence \ud83d\udcdc\nThis library is licensed under the [MIT Licence](https://github.com/umarbutler/persist-cache/blob/main/LICENCE).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An easy-to-use Python library for lightning-fast persistent function caching.",
"version": "0.4.3",
"project_urls": {
"Documentation": "https://github.com/umarbutler/persist-cache/blob/main/README.md",
"Homepage": "https://github.com/umarbutler/persist-cache",
"Issues": "https://github.com/umarbutler/persist-cache/issues",
"Source": "https://github.com/umarbutler/persist-cache"
},
"split_keywords": [
"cache",
" caching",
" decorator",
" function",
" functions",
" local",
" memoisation",
" memoise",
" memoization",
" memoize",
" optimisation",
" optimise",
" optimising",
" optimization",
" optimize",
" optimizing",
" performance",
" persistent",
" speed"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a6ccf707b62b1684df2ea9f4d46b87d2d8ca998bf0fb0f002f0531435a47e0e1",
"md5": "2cddcf9ec8b0d2ed2c6e9b061113131a",
"sha256": "e2ab58cfd68f06db5d574cdf116668fb9d9024c5e3f7908af84547e1a6d462c4"
},
"downloads": -1,
"filename": "persist_cache-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2cddcf9ec8b0d2ed2c6e9b061113131a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11987,
"upload_time": "2024-06-19T04:51:19",
"upload_time_iso_8601": "2024-06-19T04:51:19.451367Z",
"url": "https://files.pythonhosted.org/packages/a6/cc/f707b62b1684df2ea9f4d46b87d2d8ca998bf0fb0f002f0531435a47e0e1/persist_cache-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4a1eaad4e5b573586ddd9fd8d9c8ea4594a96806b5eab66ea1fd8d728e86c964",
"md5": "62c97a693d02816f7181d3598a6a5b2f",
"sha256": "16798c27ba1c56adcbd0b763e6baafa51b0ec51163dad3e60602639006d16de1"
},
"downloads": -1,
"filename": "persist_cache-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "62c97a693d02816f7181d3598a6a5b2f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 54134,
"upload_time": "2024-06-19T04:51:25",
"upload_time_iso_8601": "2024-06-19T04:51:25.807676Z",
"url": "https://files.pythonhosted.org/packages/4a/1e/aad4e5b573586ddd9fd8d9c8ea4594a96806b5eab66ea1fd8d728e86c964/persist_cache-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-19 04:51:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "umarbutler",
"github_project": "persist-cache",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "persist-cache"
}
JSON
