locache 2.0.0

Cache expensive function calls to disk.

locache

A small utility library for caching the results of deterministic and pure function calls to disk. This ability is only intended for use on expensive function calls with simple arguments and keyword arguments. The cache can optionally invalidate itself if changes to the function's source code are detetcted.

Installation

pip3 install locache

Examples

When used in normal python scripts, @persist is sufficient.

foo.py:

from locache import persist

@persist
def my_func(x, num=3):
    print("Hi from foo!")
    return x * num

my_func(1)        # prints "Hi from foo!", returns 3
my_func(2, num=2) # prints "Hi from foo!", returns 4
my_func(1)        # returns 3
my_func(2, num=2) # returns 4

Running foo.py will lead to the creation of a foo.py.cache/my_func/ directory, with files x=1_num=3 and x=2_num=2.

Notebooks

When using python notebooks, the name keyword is also required:

bar.ipynb:

from locache import persist

@persist(name="notebook")
def my_func(x, num=3):
    print("Hi from foo!")
    return x * num

my_func(1)        # prints "Hi from foo!", returns 3
my_func(1)        # returns 3

Running this cell will lead to the creation of a notebook.cache/my_func/ directory in the same directory as the notebook.

Resetting the Cache

By default, the cache is invalidated and reset if source code changes to the function in question are dedicated. This behaviour can be surpressed: @persist(auto_invalidate=False)

Results for specific function calls can be removed from the cache by deleting the appropriate file.

Programmatic resetting of the cache is also possible:

from locache import persist, reset_cache

@persist
def foo(x):
    print("hello from foo")
    return x ** 2

foo(1) # prints "Hi from foo!", returns 3
foo(1) # returns 3

reset_cache(foo)

foo(1) # prints "Hi from foo!", returns 3

In a notebook setting, the relevant name needs to also be passed:

@persist(name="notebook")
def foo(x):
    return x**2

foo(1)
reset_cache(foo, name="notebook")

Logging

Cache logging can optionally be enabled:

from locache import verbose; verbose(True)

Anti-Examples

Don't pass large data structures to persisted functions:

import numpy as np
from locache import persist

@persist # don't do this!
def foo(x):
    return np.sum(x * x)

arr = np.ones(10) + np.randn(10)
foo(arr)