| Name | locache JSON |
| Version |
4.0.2
JSON |
| download |
| home_page | None |
| Summary | Cache expensive function calls to disk. |
| upload_time | 2024-12-13 14:35:37 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
cache
disk
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# `locache` - a local and persistent cache for Python
<div align="center">
[](https://pypi.org/project/locache/)
[](https://pypistats.org/packages/locache)
[](LICENCE.md)
[](https://github.com/jla-gardner/load-atoms/actions/workflows/tests.yaml)
[](https://codecov.io/gh/jla-gardner/locache)
</div>
`locache` is a single-file, 0-dependency utility package for caching the results of deterministic and pure function calls to disk, exposed via the [`@persist`](#persist) decorator.
These caches are:
- **persistent across separate Python sessions**: run the function once to cache the result to disk, and then hit the cache again and again in different runs/notebooks/scripts/sessions
- **aware of the function's source code**: if the function's source code changes, new values will be cached. If you change the source code back, the old values will still be in the cache (useful for using different versions of a function on e.g. different branches)
- **configurable with `max_entries` and `max_age` parameters**: control how many entries to store, and how long to keep them in the cache for.
## Use-case
Have you ever written something like this?
```python
# result = expensive_function(X, y)
result = np.load("cached_result.npy")
```
This is somewhat dangerous: what if you have changed `expensive_function` and forgotten to update the cache? Or accidentally deleted your cache file? Or you have `result = np.load("cached_result-v3-final.npy")`?
`locache.persist` is an easy way to avoid these issues:
1. wrap `expensive_function` with `@persist`
2. call `expensive_function` as usual
3. `locache` automatically caches the result of `expensive_function` to disk. If the function's source code changes, new values will be cached.
## Installation
`locache` is simple enough that you could have written it yourself. To use it in your project, either:
- copy the [`locache.py`](locache.py) file into your project
- install it with
`pip install locache`
## API
`locache` provides 3 importable functions:
- the `@persist` decorator
- `reset`
- `verbose`
### `@persist` / `@persist(max_entries=-1, max_age=365)`
Wrap a pure function with `@persist` in order to cache its results to disk. The only stipulation is that the function's arguments and return value must be pickle-able.
```python
>>> from locache import persist
>>> @persist
... def my_func(x, num=3):
... print("Hi from foo!")
... return x * num
>>> my_func(1) # function behaviour is unchanged
Hi from foo!
3
>>> my_func(2, num=2)
Hi from foo!
4
>>> my_func(1) # cached results are returned
3
```
By default, `@persist` will store up to unlimited entries. Each of these will be removed 365 days after they are last accessed. These parameters can be changed by passing `max_entries` and `max_age` to `@persist`.
### `reset(func: Callable)`
Reset the cache for a given function.
```python
>>> from locache import reset
>>> @persist
... def squared(x):
... print(f"Squaring {x}")
... return x * x
>>> squared(2) # cache miss
Squaring 2
4
>>> squared(2) # cache hit
4
>>> reset(squared)
>>> squared(2) # cache miss
Squaring 2
4
```
### `verbose(yes: bool = True)`
Turn on verbose, debug logging.
Raw data
{
"_id": null,
"home_page": null,
"name": "locache",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cache, disk",
"author": null,
"author_email": "John Gardner <gardner.john97@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b6/64/9a422ad9a00291fb8930b49e47ba0a56f38bf52792fa843e7e2f17f9cb6e/locache-4.0.2.tar.gz",
"platform": null,
"description": "# `locache` - a local and persistent cache for Python\n\n<div align=\"center\">\n\n[](https://pypi.org/project/locache/)\n[](https://pypistats.org/packages/locache)\n[](LICENCE.md)\n[](https://github.com/jla-gardner/load-atoms/actions/workflows/tests.yaml)\n[](https://codecov.io/gh/jla-gardner/locache)\n</div>\n\n\n`locache` is a single-file, 0-dependency utility package for caching the results of deterministic and pure function calls to disk, exposed via the [`@persist`](#persist) decorator.\n\nThese caches are:\n- **persistent across separate Python sessions**: run the function once to cache the result to disk, and then hit the cache again and again in different runs/notebooks/scripts/sessions\n- **aware of the function's source code**: if the function's source code changes, new values will be cached. If you change the source code back, the old values will still be in the cache (useful for using different versions of a function on e.g. different branches)\n- **configurable with `max_entries` and `max_age` parameters**: control how many entries to store, and how long to keep them in the cache for.\n\n## Use-case\n\nHave you ever written something like this?\n\n```python\n# result = expensive_function(X, y)\nresult = np.load(\"cached_result.npy\")\n```\n\nThis is somewhat dangerous: what if you have changed `expensive_function` and forgotten to update the cache? Or accidentally deleted your cache file? Or you have `result = np.load(\"cached_result-v3-final.npy\")`?\n\n`locache.persist` is an easy way to avoid these issues: \n1. wrap `expensive_function` with `@persist`\n2. call `expensive_function` as usual\n3. `locache` automatically caches the result of `expensive_function` to disk. If the function's source code changes, new values will be cached.\n\n\n## Installation\n\n`locache` is simple enough that you could have written it yourself. To use it in your project, either:\n- copy the [`locache.py`](locache.py) file into your project\n- install it with\n`pip install locache`\n\n## API\n\n`locache` provides 3 importable functions:\n- the `@persist` decorator\n- `reset`\n- `verbose`\n\n### `@persist` / `@persist(max_entries=-1, max_age=365)`\n\nWrap a pure function with `@persist` in order to cache its results to disk. The only stipulation is that the function's arguments and return value must be pickle-able.\n\n```python\n>>> from locache import persist\n\n>>> @persist\n... def my_func(x, num=3):\n... print(\"Hi from foo!\")\n... return x * num\n\n>>> my_func(1) # function behaviour is unchanged \nHi from foo!\n3\n>>> my_func(2, num=2) \nHi from foo!\n4\n>>> my_func(1) # cached results are returned\n3\n```\n\nBy default, `@persist` will store up to unlimited entries. Each of these will be removed 365 days after they are last accessed. These parameters can be changed by passing `max_entries` and `max_age` to `@persist`.\n\n### `reset(func: Callable)`\n\nReset the cache for a given function.\n\n```python\n>>> from locache import reset\n\n>>> @persist\n... def squared(x):\n... print(f\"Squaring {x}\")\n... return x * x\n\n>>> squared(2) # cache miss\nSquaring 2\n4\n>>> squared(2) # cache hit\n4\n>>> reset(squared)\n>>> squared(2) # cache miss\nSquaring 2\n4\n```\n\n\n### `verbose(yes: bool = True)`\n\nTurn on verbose, debug logging.\n",
"bugtrack_url": null,
"license": null,
"summary": "Cache expensive function calls to disk.",
"version": "4.0.2",
"project_urls": {
"Homepage": "https://github.com/jla-gardner/locache"
},
"split_keywords": [
"cache",
" disk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bf8fdab996d563d2fd690fde3080d16763026e09ce11f5b1bad7461832d15ec3",
"md5": "a1eefc339a5557513169a19ab2be2c44",
"sha256": "195a34af8f3d24cf0ce56e5a81ee6bbb6af89da07f9502e0c5ca8ae6e94f9365"
},
"downloads": -1,
"filename": "locache-4.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a1eefc339a5557513169a19ab2be2c44",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6455,
"upload_time": "2024-12-13T14:35:33",
"upload_time_iso_8601": "2024-12-13T14:35:33.906849Z",
"url": "https://files.pythonhosted.org/packages/bf/8f/dab996d563d2fd690fde3080d16763026e09ce11f5b1bad7461832d15ec3/locache-4.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b6649a422ad9a00291fb8930b49e47ba0a56f38bf52792fa843e7e2f17f9cb6e",
"md5": "494243990c4c0ca4ef9b9ce04303f602",
"sha256": "c372ddfe0983094330e7ac4c186b428a0d1cd22e1c539109910ddae5bb588971"
},
"downloads": -1,
"filename": "locache-4.0.2.tar.gz",
"has_sig": false,
"md5_digest": "494243990c4c0ca4ef9b9ce04303f602",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6529,
"upload_time": "2024-12-13T14:35:37",
"upload_time_iso_8601": "2024-12-13T14:35:37.915988Z",
"url": "https://files.pythonhosted.org/packages/b6/64/9a422ad9a00291fb8930b49e47ba0a56f38bf52792fa843e7e2f17f9cb6e/locache-4.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-13 14:35:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jla-gardner",
"github_project": "locache",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "locache"
}
