cache-decorator 1.3.0

a simple decorator to cache the results of computationally heavy functions

A simple decorator to cache the results of computationally heavy functions. The package automatically serialize and deserialize depending on the format of the save path.

Currently it supports:

• .json

• .json.gz

• .json.bz

• .json.lzma

• .pkl

• .pkl.gz

• .pkl.bz

• .pkl.lzma

• .pkl.zip

• .npy

• .npz

• .csv

• .csv.gz

• .csv.bz2

• .csv.zip

• .csv.xz

• .xlsx

How do I install this package?

As usual, just download it using pip:

pip install cache_decorator

Tests Coverage

Since some software handling coverages sometime get slightly different results, here’s three of them:

Examples of Usage

To cache a function or a method you just have to decorate it with the cache decorator.

from time import sleep
from cache_decorator import Cache

@Cache()
def x(a, b):
    sleep(3)
    return a + b

class A:
    @Cache()
    def x(self, a, b):
        sleep(3)
        return a + b

By default the cache is differentiate by the parameters passed to the function. One can specify which parameters should be ignored.

from time import sleep
from cache_decorator import Cache

@Cache(args_to_ignore=["verbose"])
def x(a, verbose=False):
    sleep(3)
    if verbose:
        print("HEY")
    return a

Multiple arguments can be specified as a list of strings with the name of the arguments to ignore.

from time import sleep
from cache_decorator import Cache

@Cache(args_to_ignore=["verbose", "multiprocessing"])
def x(a, verbose=False, multiprocessing=False):
    sleep(3)
    if verbose:
        print("HEY")
    return a

The default cache directory is ./cache but this can be setted by passing the cache_dir parameter to the decorator or by setting the environment variable CACHE_DIR. In the case both are setted, the parameter folder has precedence over the environment one.

from time import sleep
from cache_decorator import Cache

@Cache(cache_dir="/tmp")
def x(a):
    sleep(3)
    return a

The path format can be modified by passing the cache_path parameter. This string will be formatted with infos about the function, its parameters and, if it’s a method, the self attributes.

De default path is:

from time import sleep
from cache_decorator import Cache

@Cache(cache_path="{cache_dir}/{file_name}_{function_name}/{_hash}.pkl")
def x(a):
    sleep(3)
    return a

But can be modified giving cache a more significative name, for example we can add the value of a into the file name.

from time import sleep
from cache_decorator import Cache

@Cache(cache_path="{cache_dir}/{file_name}_{function_name}/{a}_{_hash}.pkl")
def x(a):
    sleep(3)
    return a

Depending on the extension of the file, different serialization and deserialization dispatcher will be called.

from time import sleep
from cache_decorator import Cache

@Cache(cache_path="/tmp/{_hash}.pkl.gz")
def x(a):
    sleep(3)
    return a

@Cache(cache_path="/tmp/{_hash}.json")
def x(a):
    sleep(3)
    return {"1":1,"2":2}

@Cache(cache_path="/tmp/{_hash}.npy")
def x(a):
    sleep(3)
    return np.array([1, 2, 3])

@Cache(cache_path="/tmp/{_hash}.npz")
def x(a):
    sleep(3)
    return np.array([1, 2, 3]), np.array([1, 2, 4])

Cache also might have a validity duration.

from time import sleep
from cache_decorator import Cache

@Cache(
    cache_path="/tmp/{_hash}.pkl.gz",
    validity_duration="24d"
    )
def x(a):
    sleep(3)
    return a

In this example the cache will be valid for the next 24 days. and on the 25th day the cache will be rebuilt. The duration can be written as a time in seconds or as a string with unit. The units can be “s” seconds, “m” minutes, “h” hours, “d” days, “w” weeks.