What is Cachew?

TLDR: cachew lets you cache function calls into an sqlite database on your disk in a matter of single decorator (similar to functools.lru_cache). The difference from functools.lru_cache is that cached data is persisted between program runs, so next time you call your function, it will only be a matter of reading from the cache. Cache is invalidated automatically if your function's arguments change, so you don't have to think about maintaining it.

In order to be cacheable, your function needs to return a simple data type, or an Iterator over such types.

A simple type is defined as:

primitive: str/int/float/bool
JSON-like types (dict/list/tuple)
datetime
Exception (useful for error handling )
NamedTuples
dataclasses

That allows to automatically infer schema from type hints (PEP 526) and not think about serializing/deserializing. Thanks to type hints, you don't need to annotate your classes with any special decorators, inherit from some special base classes, etc., as it's often the case for serialization libraries.

Motivation

I often find myself processing big chunks of data, merging data together, computing some aggregates on it or extracting few bits I'm interested at. While I'm trying to utilize REPL as much as I can, some things are still fragile and often you just have to rerun the whole thing in the process of development. This can be frustrating if data parsing and processing takes seconds, let alone minutes in some cases.

Conventional way of dealing with it is serializing results along with some sort of hash (e.g. md5) of input files, comparing on the next run and returning cached data if nothing changed.

Simple as it sounds, it is pretty tedious to do every time you need to memorize some data, contaminates your code with routine and distracts you from your main task.

Examples

Processing Wikipedia

Imagine you're working on a data analysis pipeline for some huge dataset, say, extracting urls and their titles from Wikipedia archive. Parsing it (extract_links function) takes hours, however, as long as the archive is same you will always get same results. So it would be nice to be able to cache the results somehow.

With this library your can achieve it through single @cachew decorator.

>>> from typing import NamedTuple, Iterator
>>> class Link(NamedTuple):
...     url : str
...     text: str
...
>>> @cachew
... def extract_links(archive_path: str) -> Iterator[Link]:
...     for i in range(5):
...         # simulate slow IO
...         # this function runs for five seconds for the purpose of demonstration, but realistically it might take hours
...         import time; time.sleep(1)
...         yield Link(url=f'http://link{i}.org', text=f'text {i}')
...
>>> list(extract_links(archive_path='wikipedia_20190830.zip')) # that would take about 5 seconds on first run
[Link(url='http://link0.org', text='text 0'), Link(url='http://link1.org', text='text 1'), Link(url='http://link2.org', text='text 2'), Link(url='http://link3.org', text='text 3'), Link(url='http://link4.org', text='text 4')]

>>> from timeit import Timer
>>> res = Timer(lambda: list(extract_links(archive_path='wikipedia_20190830.zip'))).timeit(number=1)
... # second run is cached, so should take less time
>>> print(f"call took {int(res)} seconds")
call took 0 seconds

>>> res = Timer(lambda: list(extract_links(archive_path='wikipedia_20200101.zip'))).timeit(number=1)
... # now file has changed, so the cache will be discarded
>>> print(f"call took {int(res)} seconds")
call took 5 seconds

When you call extract_links with the same archive, you start getting results in a matter of milliseconds, as fast as sqlite reads it.

When you use newer archive, archive_path changes, which will make cachew invalidate old cache and recompute it, so you don't need to think about maintaining it separately.

Incremental data exports

This is my most common usecase of cachew, which I'll illustrate with example.

I'm using an environment sensor to log stats about temperature and humidity. Data is synchronized via bluetooth in the sqlite database, which is easy to access. However sensor has limited memory (e.g. 1000 latest measurements). That means that I end up with a new database every few days, each of them containing only a slice of data I need, e.g.:

...
20190715100026.db
20190716100138.db
20190717101651.db
20190718100118.db
20190719100701.db
...

To access all of historic temperature data, I have two options:

Go through all the data chunks every time I wan to access them and 'merge' into a unified stream of measurements, e.g. something like:
```
def measurements(chunks: List[Path]) -> Iterator[Measurement]:
    for chunk in chunks:
        # read measurements from 'chunk' and yield unseen ones
```
This is very easy, but slow and you waste CPU for no reason every time you need data.
Keep a 'master' database and write code to merge chunks in it.

This is very efficient, but tedious:
- requires serializing/deserializing data -- boilerplate
- requires manually managing sqlite database -- error prone, hard to get right every time
- requires careful scheduling, ideally you want to access new data without having to refresh cache

Cachew gives the best of two worlds and makes it both easy and efficient. The only thing you have to do is to decorate your function:

@cachew      
def measurements(chunks: List[Path]) -> Iterator[Measurement]:
    # ...

as long as chunks stay same, data stays same so you always read from sqlite cache which is very fast
you don't need to maintain the database, cache is automatically refreshed when chunks change (i.e. you got new data)

All the complexity of handling database is hidden in cachew implementation.

How it works

first your objects get converted into a simpler JSON-like representation
after that, they are mapped into byte blobs via orjson.

When the function is called, cachew computes the hash of your function's arguments and compares it against the previously stored hash value.

If they match, it would deserialize and yield whatever is stored in the cache database
If the hash mismatches, the original function is called and new data is stored along with the new hash

Features

automatic schema inference: 1, 2
supported types:
- primitive: str, int, float, bool, datetime, date, Exception
  
  See tests.test_types, tests.test_primitive, tests.test_dates, tests.test_exceptions
- @dataclass and NamedTuple
- Optional types
- Union types
- nested datatypes
detects datatype schema changes and discards old data automatically

Performance

Updating cache takes certain overhead, but that would depend on how complicated your datatype in the first place, so I'd suggest measuring if you're not sure.

During reading cache all that happens is reading blobls from sqlite/decoding as JSON, and mapping them onto your target datatype, so the overhead depends on each of these steps.

It would almost certainly make your program faster if your computations take more than several seconds.

You can find some of my performance tests in benchmarks/ dir, and the tests themselves in src/cachew/tests/marshall.py.

Using

See docstring for up-to-date documentation on parameters and return types. You can also use extensive unit tests as a reference.

Some useful (but optional) arguments of @cachew decorator:

cache_path can be a directory, or a callable that returns a path and depends on function's arguments.

By default, settings.DEFAULT_CACHEW_DIR is used.
depends_on is a function which determines whether your inputs have changed, and the cache needs to be invalidated.

By default it just uses string representation of the arguments, you can also specify a custom callable.

For instance, it can be used to discard cache if the input file was modified.
cls is the type that would be serialized.

By default, it is inferred from return type annotations, but can be specified explicitly if you don't control the code you want to cache.

Installing

Package is available on pypi.

pip3 install --user cachew

Developing

I'm using tox to run tests, and Github Actions for CI.

Implementation

why NamedTuples and dataclasses?

NamedTuple and `dat

Cachew

Install / Use

README