decorators for easily caching function results
Project description
caching
Library for easily caching computations that take a long time to run, e.g., training Keras models.
Installation
- Optionally, create and/or activate a virtual environment to install this package in. E.g.,
conda create -n example_env python=3
conda activate example_env
- Clone the caching repo to a location of your choice:
git clone https://github.com/klasleino/caching.git
- Change into the repo directory and install using pip:
cd caching
pip install -e .
Usage
Caching utility is provided via decorators.
The primary decorator is the Cachable
decorator found in the cachable
package.
This decorator is used on a function (either member or non-member) to specify that the value returned by the function should be cached.
If the function is called again with the same parameters, the result will be loaded from the cache rather than running the function again.
For example, consider the following code:
from cachable import Cachable
@Cachable(directory='cache')
def f(a, b, c):
return dict(a=a, b=b, c=c)
# Call 1 (body of `f` is run).
res = f(1, 2, 3)
# Call 2 (loaded from cache).
res = f(1, 2, 3)
# Call 3 (body of `f` is run).
res = f(4, 5, 6)
In the first call, the function, f
, will be run, and the result will be saved in a file in a directory called "cache".
The file name of the cached result will contain the parameters, a
, b
, and c
and the values passed to them in call 1.
In the second call, the function will not be run, because an existing file with the given parameters exists; instead, the result will be loaded from the cached file.
Finally, in the third call, the parameters are different, thus the function will be run again, and a new cache entry made.
Cached Objects
Objects returned by Cachable
functions are wrapped as a cachable.cached_objects.CachedObject
.
CachedObjects
s can mostly be used the same as their non-wrapped counterparts, but the original object returned by the non-decorated function can be obtained from the obj
field of the CachedObject
.
The CachedObject
also keeps track of the parameters used to create the object.
Default Parameters
Parameters taking their default values will not be included in the name of the cached file. This keeps file names shorter, and allows backwards compatibility with previously cached files, provided the default value is chosen appropriately.
Non-primitive Arguments
Any argument with a canonical string representation can be passed as an argument to a Cachable
function.
The argument, arg
, is taken to be an unseen value if str(arg)
does not match the string representation of any previous values passed.
This may present a problem for generic objects, as two objects may be the same, while str(obj1) != str(obj2)
.
Any instance of CachedObject
has a canonical string representation, so CachedObject
s can be given as parameters to other cached objects.
For other custom objects, the CachableParam
decorator in the cachable
package can be used.
This gives the decorated object a canonical string representation based on the arguments passed to the object's __init__
function.
For example, a custom object can be used as a parameter to a Cachable
function using the following code:
from cachable import Cachable, CachableParam
@CachableParam()
class P(object):
def __init__(a, b, c):
self.a = a
self.b = b
self.c = c
@Cachable(directory='cache')
def f(p):
return dict(a=p.a, b=p.b, c=p.c)
# Call 1 (body of `f` is run).
res = f(P(1, 2, 3))
# Call 2 (loaded from cache).
res = f(P(1, 2, 3))
Note that the behavior of the caching may not be correct if the CachableParam
is modified after it is constructed; therefore this should only be used on objects that are treated as immutable.
Hidden Parameters
If a Cachable
function takes a parameter that for whatever reason should not affect the cached file name, the parameter can be hidden by beginning its name with an underscore, e.g.,
from cachable import Cachable
@Cachable(directory='cache')
def f(a, b, c, _msg):
print(_msg)
return dict(a=a, b=b, c=c)
# Call 1 (body of `f` is run).
res = f(1, 2, 3, 'hello')
# Call 2 (loaded from cache).
res = f(1, 2, 3, 'world')
Refreshing
If for whatever reason, it is desired for the body of a Cachable
function to be rerun with a set of parameters previously used, a special parameter called _refresh
can be used, e.g.,
from cachable import Cachable
@Cachable(directory='cache')
def f(a, b, c):
return dict(a=a, b=b, c=c)
# Call 1 (body of `f` is run).
res = f(1, 2, 3)
# Call 2 (body of `f` is run).
res = f(1, 2, 3, _refresh=True)
Loaders
By default, the results of Cachable
functions are saved using python's pickle
utility.
If another format is preferred, an alternative loader can be used.
Several default implementations of alternative loaders can be found in the cachable.loaders
package.
For example, to cache a Keras model, the following could be used to save the resulting model as an h5
file using Keras' model.save()
:
from cachable import Cachable
from cachable.loaders import KerasModelLoader
@Cachable(name='my_cached_model', directory='cache', loader=KerasModelLoader())
def create_and_train_model(**model_hyperparameters):
# Create and train a model...
return model
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file cachable-0.0.1.tar.gz
.
File metadata
- Download URL: cachable-0.0.1.tar.gz
- Upload date:
- Size: 9.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/46.1.3.post20200330 requests-toolbelt/0.9.1 tqdm/4.56.0 CPython/3.8.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9112caa2d70db38db8d0c6862a9b75f95a8c072d49739482966009f80d92d7bd |
|
MD5 | 2562344cd3a8fcdf0b2198a77772570d |
|
BLAKE2b-256 | 40bee568ee0991b2186f593689c729f6e04b8594d7f55197f5a79f3d4cc63984 |
File details
Details for the file cachable-0.0.1-py3-none-any.whl
.
File metadata
- Download URL: cachable-0.0.1-py3-none-any.whl
- Upload date:
- Size: 8.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/46.1.3.post20200330 requests-toolbelt/0.9.1 tqdm/4.56.0 CPython/3.8.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | a1bda4ad372b333b0ec4138a4c24b74543ba1ad11cb60cef6dbca2ccf38522ae |
|
MD5 | f5e7728ea22ae2315a921b3d254a6f52 |
|
BLAKE2b-256 | aa9c0659eb88fc7de533a1c434ab3788b2e0a434951bdc2b81328c17210036a4 |