from shelved_cache import PersistentCache
# Shelved Cache
[](https://github.com/mariushelf/shelved_cache/actions/workflows/cicd.yaml)
[](https://codecov.io/gh/mariushelf/shelved_cache)
[](https://pypi.org/project/shelved_cache/)
[](https://pepy.tech/project/shelved-cache)
Persistent cache implementation for Python
[cachetools](https://github.com/tkem/cachetools/).
Behaves like any `Cache` implementation, but entries are persisted to disk.
Original repository: [https://github.com/mariushelf/shelved_cache](https://github.com/mariushelf/shelved_cache)
# Usage example
```python
from shelved_cache import PersistentCache
from cachetools import LRUCache
filename = 'mycache'
# create persistency around an LRUCache
pc = PersistentCache(LRUCache, filename=filename, maxsize=2)
# we can now use the cache like a normal LRUCache.
# But: the cache is persisted to disk.
pc["a"] = 42
pc["b"] = 43
assert pc["a"] == 42
assert pc["b"] == 43
# close the file
pc.close()
# Now in the same script or in another script, we can re-load the cache:
pc2 = PersistentCache(LRUCache, filename=filename, maxsize=2)
assert pc2["a"] == 42
assert pc2["b"] == 43
```
## Use as a decorator
Just like a regular `cachetools.Cache`, the `PersistentCache` can be used with
`cachetools`' `cached` decorator:
```python
import cachetools
from shelved_cache import PersistentCache
from cachetools import LRUCache
filename = 'mycache'
pc = PersistentCache(LRUCache, filename, maxsize=2)
@cachetools.cached(pc)
def square(x):
print("called")
return x * x
assert square(3) == 9
# outputs "called"
assert square(3) == 9
# no output because the cache is used
```
## Note: decorating multiple functions
If you want to decorate multiple functions, you need to use a
new instance of `PersistentCache` for each function.
Make sure that each cache uses a different file name.
```python
import cachetools
from shelved_cache import PersistentCache
from cachetools import LRUCache
@cachetools.cached(PersistentCache(LRUCache, "square.cache", maxsize=100))
def square(x):
return x * x
@cachetools.cached(PersistentCache(LRUCache, "cube.cache", maxsize=100))
def cube(x):
return x * x * x
assert square(2) == 4
assert cube(2) == 8
```
# Features
## persistent cache
See usage examples above.
## Async decorators
The package contains equivalents for `cachetools`' `cached` and `cachedmethod`
decorators which support wrapping async methods. You can find them in the `decorators`
submodule.
They support both synchronous *and* asynchronous functions and methods.
Examples:
```python
from shelved_cache import cachedasyncmethod
from cachetools import LRUCache
class A:
# decorate an async method:
@cachedasyncmethod(lambda self: LRUCache(2))
async def asum(self, a, b):
return a + b
a = A()
assert await a.asum(1, 2) == 3
class S:
@cachedasyncmethod(lambda self: LRUCache(2))
def sum(self, a, b):
return a + b
s = S()
assert s.sum(1, 2) == 3
```
## Support for lists as function arguments
Using the `autotuple_hashkey` function, list arguments are automatically converted
to tuples, so that they support hashing.
Example:
```python
from cachetools import cached, LRUCache
from shelved_cache.keys import autotuple_hashkey
@cached(LRUCache(2), key=autotuple_hashkey)
def sum(values):
return values[0] + values[1]
# fill cache
assert sum([1, 2]) == 3
# access cache
assert sum([1, 2]) == 3
```
# Changelog
## 0.4.0
* drop support for Python 3.7 and 3.8
* add support for Python 3.12 and 3.13
* note: shelved_cache does not seem to work with Python 3.13 on Windows
* note about decorating multiple functions in the README
* improvement in async decorators
## 0.3.1
* fix for Windows users
* add Windows and MacOS to test suite
## 0.3.0
* add support for Python 3.10 and 3.11
* better error message when trying to use the same file for multiple caches
* CI/CD pipeline
* fixes for documentation
## 0.2.1
* improved error handling
# Acknowledgements
* [cachetools](https://github.com/tkem/cachetools/) by Thomas Kemmer
* [asyncache](https://github.com/hephex/asyncache) by hephex
# License
Author: Marius Helf ([helfsmarius@gmail.com](mailto:helfsmarius@gmail.com))
License: MIT -- see [LICENSE](LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/mariushelf/shelved_cache",
"name": "shelved-cache",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.9.0",
"maintainer_email": null,
"keywords": null,
"author": "Marius Helf",
"author_email": "helfsmarius@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/35/f8/f305abd2649539a059147df87fbce38ae2aae15fe982010a8f7162a6fe6b/shelved_cache-0.4.0.tar.gz",
"platform": null,
"description": "from shelved_cache import PersistentCache\n\n# Shelved Cache\n\n[](https://github.com/mariushelf/shelved_cache/actions/workflows/cicd.yaml)\n[](https://codecov.io/gh/mariushelf/shelved_cache)\n[](https://pypi.org/project/shelved_cache/)\n[](https://pepy.tech/project/shelved-cache)\n\nPersistent cache implementation for Python\n[cachetools](https://github.com/tkem/cachetools/).\n\nBehaves like any `Cache` implementation, but entries are persisted to disk.\n\nOriginal repository: [https://github.com/mariushelf/shelved_cache](https://github.com/mariushelf/shelved_cache)\n\n# Usage example\n\n```python\nfrom shelved_cache import PersistentCache\nfrom cachetools import LRUCache\n\nfilename = 'mycache'\n\n# create persistency around an LRUCache\npc = PersistentCache(LRUCache, filename=filename, maxsize=2)\n\n# we can now use the cache like a normal LRUCache.\n# But: the cache is persisted to disk.\npc[\"a\"] = 42\npc[\"b\"] = 43\n\nassert pc[\"a\"] == 42\nassert pc[\"b\"] == 43\n\n# close the file\npc.close()\n\n# Now in the same script or in another script, we can re-load the cache:\npc2 = PersistentCache(LRUCache, filename=filename, maxsize=2)\nassert pc2[\"a\"] == 42\nassert pc2[\"b\"] == 43\n```\n\n## Use as a decorator\n\nJust like a regular `cachetools.Cache`, the `PersistentCache` can be used with\n`cachetools`' `cached` decorator:\n\n```python\nimport cachetools\nfrom shelved_cache import PersistentCache\nfrom cachetools import LRUCache\n\nfilename = 'mycache'\npc = PersistentCache(LRUCache, filename, maxsize=2)\n\n@cachetools.cached(pc)\ndef square(x):\n print(\"called\")\n return x * x\n\nassert square(3) == 9\n# outputs \"called\"\nassert square(3) == 9\n# no output because the cache is used\n```\n\n## Note: decorating multiple functions\n\nIf you want to decorate multiple functions, you need to use a\nnew instance of `PersistentCache` for each function.\nMake sure that each cache uses a different file name.\n\n\n```python\nimport cachetools\nfrom shelved_cache import PersistentCache\nfrom cachetools import LRUCache\n\n@cachetools.cached(PersistentCache(LRUCache, \"square.cache\", maxsize=100))\ndef square(x):\n return x * x\n\n@cachetools.cached(PersistentCache(LRUCache, \"cube.cache\", maxsize=100))\ndef cube(x):\n return x * x * x\n\nassert square(2) == 4\nassert cube(2) == 8\n```\n\n# Features\n\n## persistent cache\n\nSee usage examples above.\n\n## Async decorators\n\nThe package contains equivalents for `cachetools`' `cached` and `cachedmethod`\ndecorators which support wrapping async methods. You can find them in the `decorators`\nsubmodule.\n\nThey support both synchronous *and* asynchronous functions and methods.\n\nExamples:\n```python\nfrom shelved_cache import cachedasyncmethod\nfrom cachetools import LRUCache\n\nclass A:\n # decorate an async method:\n @cachedasyncmethod(lambda self: LRUCache(2))\n async def asum(self, a, b):\n return a + b\n\na = A()\nassert await a.asum(1, 2) == 3\n \nclass S:\n @cachedasyncmethod(lambda self: LRUCache(2))\n def sum(self, a, b):\n return a + b\n\ns = S()\nassert s.sum(1, 2) == 3\n```\n\n\n## Support for lists as function arguments\n\nUsing the `autotuple_hashkey` function, list arguments are automatically converted\nto tuples, so that they support hashing.\n\nExample:\n```python\nfrom cachetools import cached, LRUCache\nfrom shelved_cache.keys import autotuple_hashkey\n\n@cached(LRUCache(2), key=autotuple_hashkey)\ndef sum(values):\n return values[0] + values[1]\n\n# fill cache\nassert sum([1, 2]) == 3\n\n# access cache\nassert sum([1, 2]) == 3\n```\n\n\n# Changelog\n\n## 0.4.0\n* drop support for Python 3.7 and 3.8\n* add support for Python 3.12 and 3.13\n * note: shelved_cache does not seem to work with Python 3.13 on Windows\n* note about decorating multiple functions in the README\n* improvement in async decorators\n\n## 0.3.1\n* fix for Windows users\n* add Windows and MacOS to test suite\n\n## 0.3.0\n\n* add support for Python 3.10 and 3.11\n* better error message when trying to use the same file for multiple caches\n* CI/CD pipeline\n* fixes for documentation\n\n## 0.2.1\n* improved error handling\n\n# Acknowledgements\n\n* [cachetools](https://github.com/tkem/cachetools/) by Thomas Kemmer\n* [asyncache](https://github.com/hephex/asyncache) by hephex\n\n\n# License\n\nAuthor: Marius Helf ([helfsmarius@gmail.com](mailto:helfsmarius@gmail.com))\n\nLicense: MIT -- see [LICENSE](LICENSE)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Persistent cache for Python cachetools.",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://github.com/mariushelf/shelved_cache",
"Homepage": "https://github.com/mariushelf/shelved_cache",
"Repository": "https://github.com/mariushelf/shelved_cache"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6c0179f4dbc62b3e10293e4b5b3ac3bae39302979c3632e5b89590b1c8f0e864",
"md5": "e76efdd19ea754ecb2e744e483387422",
"sha256": "37eb48da1b91dee27157a50a045cb433dc6486528279804e6189fd7a2d755a5e"
},
"downloads": -1,
"filename": "shelved_cache-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e76efdd19ea754ecb2e744e483387422",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.9.0",
"size": 8116,
"upload_time": "2024-10-19T20:09:40",
"upload_time_iso_8601": "2024-10-19T20:09:40.972884Z",
"url": "https://files.pythonhosted.org/packages/6c/01/79f4dbc62b3e10293e4b5b3ac3bae39302979c3632e5b89590b1c8f0e864/shelved_cache-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "35f8f305abd2649539a059147df87fbce38ae2aae15fe982010a8f7162a6fe6b",
"md5": "5f6f78f366aeccf52b6de363e246e039",
"sha256": "59c003f715d69f7bfadf461b68fae262db39cf6ab71d288dfeb24cc8637abece"
},
"downloads": -1,
"filename": "shelved_cache-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "5f6f78f366aeccf52b6de363e246e039",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.9.0",
"size": 6776,
"upload_time": "2024-10-19T20:09:42",
"upload_time_iso_8601": "2024-10-19T20:09:42.202294Z",
"url": "https://files.pythonhosted.org/packages/35/f8/f305abd2649539a059147df87fbce38ae2aae15fe982010a8f7162a6fe6b/shelved_cache-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-19 20:09:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mariushelf",
"github_project": "shelved_cache",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "shelved-cache"
}
JSON
