.. image:: https://github.com/con/fscacher/workflows/Test/badge.svg?branch=master
:target: https://github.com/con/fscacher/actions?workflow=Test
:alt: CI Status
.. image:: https://codecov.io/gh/con/fscacher/branch/master/graph/badge.svg
:target: https://codecov.io/gh/con/fscacher
.. image:: https://img.shields.io/pypi/pyversions/fscacher.svg
:target: https://pypi.org/project/fscacher/
.. image:: https://img.shields.io/github/license/con/fscacher.svg
:target: https://opensource.org/licenses/MIT
:alt: MIT License
`GitHub <https://github.com/con/fscacher>`_
| `PyPI <https://pypi.org/project/fscacher/>`_
| `Issues <https://github.com/con/fscacher/issues>`_
| `Changelog <https://github.com/con/fscacher/blob/master/CHANGELOG.md>`_
``fscacher`` provides a cache & decorator for memoizing functions whose outputs
depend upon the contents of a file argument.
If you have a function ``foo()`` that takes a file path as its first argument,
and if the behavior of ``foo()`` is pure in the *contents* of the path and the
values of its other arguments, ``fscacher`` can help cache that function, like
so:
.. code:: python
from fscacher import PersistentCache
cache = PersistentCache("insert_name_for_cache_here")
@cache.memoize_path
def foo(path, ...):
...
Now the outputs of ``foo()`` will be cached for each set of input arguments and
for a "fingerprint" (timestamps & size) of each ``path``. If ``foo()`` is
called twice with the same set of arguments, the result from the first call
will be reused for the second, unless the file pointed to by ``path`` changes,
in which case the function will be run again. If ``foo()`` is called with a
non-`path-like object
<https://docs.python.org/3/glossary.html#term-path-like-object>`_ as the value
of ``path``, the cache is ignored.
``memoize_path()`` optionally takes an ``exclude_kwargs`` argument, which must
be a sequence of names of arguments of the decorated function that will be
ignored for caching purposes.
Caches are stored on-disk and thus persist between Python runs. To clear a
given ``PersistentCache`` and erase its data store, call the ``clear()``
method.
By default, caches are stored in the user-wide cache directory, under an
fscacher-specific folder, with each one identified by the name passed to the
constructor (which defaults to "cache" if not specified). To specify a
different location, use the ``path`` argument to the constructor instead of
passing a name:
.. code:: python
cache = PersistentCache(path="/my/custom/location")
If your code runs in an environment where different sets of libraries or the
like could be used in different runs, and these make a difference to the output
of your function, you can make the caching take them into account by passing a
list of library version strings or other identifiers for the current run as the
``token`` argument to the ``PersistentCache`` constructor.
Finally, ``PersistentCache``'s constructor also optionally takes an ``envvar``
argument giving the name of an environment variable. If that environment
variable is set to "``clear``" when the cache is constructed, the cache's
``clear()`` method will be called at the end of initialization. If the
environment variable is set to "``ignore``" instead, then caching will be
disabled, and the cache's ``memoize_path`` method will be a no-op. If the
given environment variable is not set, or if ``envvar`` is not specified, then
``PersistentCache`` will query the ``FSCACHER_CACHE`` environment variable
instead.
Installation
============
``fscacher`` requires Python 3.7 or higher. Just use `pip
<https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to install it and
its dependencies::
python3 -m pip install fscacher
Raw data
{
"_id": null,
"home_page": "https://github.com/con/fscacher",
"name": "fscacher",
"maintainer": "John T. Wodder II",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "fscacher@varonathe.org",
"keywords": "caching,file cache",
"author": "Center for Open Neuroscience",
"author_email": "debian@onerussian.com",
"download_url": "https://files.pythonhosted.org/packages/74/aa/1485a2bc2e7623fc6d9751a09e4a29082b9b1089d932b3b741cf5ff583b5/fscacher-0.4.0.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/con/fscacher/workflows/Test/badge.svg?branch=master\n :target: https://github.com/con/fscacher/actions?workflow=Test\n :alt: CI Status\n\n.. image:: https://codecov.io/gh/con/fscacher/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/con/fscacher\n\n.. image:: https://img.shields.io/pypi/pyversions/fscacher.svg\n :target: https://pypi.org/project/fscacher/\n\n.. image:: https://img.shields.io/github/license/con/fscacher.svg\n :target: https://opensource.org/licenses/MIT\n :alt: MIT License\n\n`GitHub <https://github.com/con/fscacher>`_\n| `PyPI <https://pypi.org/project/fscacher/>`_\n| `Issues <https://github.com/con/fscacher/issues>`_\n| `Changelog <https://github.com/con/fscacher/blob/master/CHANGELOG.md>`_\n\n``fscacher`` provides a cache & decorator for memoizing functions whose outputs\ndepend upon the contents of a file argument.\n\nIf you have a function ``foo()`` that takes a file path as its first argument,\nand if the behavior of ``foo()`` is pure in the *contents* of the path and the\nvalues of its other arguments, ``fscacher`` can help cache that function, like\nso:\n\n.. code:: python\n\n from fscacher import PersistentCache\n\n cache = PersistentCache(\"insert_name_for_cache_here\")\n\n @cache.memoize_path\n def foo(path, ...):\n ...\n\nNow the outputs of ``foo()`` will be cached for each set of input arguments and\nfor a \"fingerprint\" (timestamps & size) of each ``path``. If ``foo()`` is\ncalled twice with the same set of arguments, the result from the first call\nwill be reused for the second, unless the file pointed to by ``path`` changes,\nin which case the function will be run again. If ``foo()`` is called with a\nnon-`path-like object\n<https://docs.python.org/3/glossary.html#term-path-like-object>`_ as the value\nof ``path``, the cache is ignored.\n\n``memoize_path()`` optionally takes an ``exclude_kwargs`` argument, which must\nbe a sequence of names of arguments of the decorated function that will be\nignored for caching purposes.\n\nCaches are stored on-disk and thus persist between Python runs. To clear a\ngiven ``PersistentCache`` and erase its data store, call the ``clear()``\nmethod.\n\nBy default, caches are stored in the user-wide cache directory, under an\nfscacher-specific folder, with each one identified by the name passed to the\nconstructor (which defaults to \"cache\" if not specified). To specify a\ndifferent location, use the ``path`` argument to the constructor instead of\npassing a name:\n\n.. code:: python\n\n cache = PersistentCache(path=\"/my/custom/location\")\n\nIf your code runs in an environment where different sets of libraries or the\nlike could be used in different runs, and these make a difference to the output\nof your function, you can make the caching take them into account by passing a\nlist of library version strings or other identifiers for the current run as the\n``token`` argument to the ``PersistentCache`` constructor.\n\nFinally, ``PersistentCache``'s constructor also optionally takes an ``envvar``\nargument giving the name of an environment variable. If that environment\nvariable is set to \"``clear``\" when the cache is constructed, the cache's\n``clear()`` method will be called at the end of initialization. If the\nenvironment variable is set to \"``ignore``\" instead, then caching will be\ndisabled, and the cache's ``memoize_path`` method will be a no-op. If the\ngiven environment variable is not set, or if ``envvar`` is not specified, then\n``PersistentCache`` will query the ``FSCACHER_CACHE`` environment variable\ninstead.\n\n\nInstallation\n============\n``fscacher`` requires Python 3.7 or higher. Just use `pip\n<https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to install it and\nits dependencies::\n\n python3 -m pip install fscacher\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Caching results of operations on heavy file trees",
"version": "0.4.0",
"project_urls": {
"Bug Tracker": "https://github.com/con/fscacher/issues",
"Homepage": "https://github.com/con/fscacher",
"Source Code": "https://github.com/con/fscacher"
},
"split_keywords": [
"caching",
"file cache"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f1290f64e53f11c854533e6ad7f4924ea0f19d3d58e445217d2a86aaa6c3c86b",
"md5": "ebae826c66ce1c5bc1c553ee2e97fa85",
"sha256": "41e3eece14c71be18a3da49ac88da3d025a89e6283f390178922622b1394bf87"
},
"downloads": -1,
"filename": "fscacher-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ebae826c66ce1c5bc1c553ee2e97fa85",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 12075,
"upload_time": "2023-08-16T13:20:24",
"upload_time_iso_8601": "2023-08-16T13:20:24.671265Z",
"url": "https://files.pythonhosted.org/packages/f1/29/0f64e53f11c854533e6ad7f4924ea0f19d3d58e445217d2a86aaa6c3c86b/fscacher-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "74aa1485a2bc2e7623fc6d9751a09e4a29082b9b1089d932b3b741cf5ff583b5",
"md5": "7cc8df4952b1a59cea002dd1bfdafe84",
"sha256": "3bd842711b836fb04e5f639944d29d637bb5de16399a926a865cffb2a7f27ce4"
},
"downloads": -1,
"filename": "fscacher-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "7cc8df4952b1a59cea002dd1bfdafe84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 34258,
"upload_time": "2023-08-16T13:20:26",
"upload_time_iso_8601": "2023-08-16T13:20:26.236874Z",
"url": "https://files.pythonhosted.org/packages/74/aa/1485a2bc2e7623fc6d9751a09e4a29082b9b1089d932b3b741cf5ff583b5/fscacher-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-16 13:20:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "con",
"github_project": "fscacher",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "fscacher"
}
JSON
