kv-caches

Caches speed up access to stores greatly, if used right. Usually, these require combining two KeyValueStore instances of the same or different kind. A simple example without error-handling is a store that uses a RedisStore in front of a FilesystemStore:

from minimalkv.memory.redisstore import RedisStore
from minimalkv.fs import FilesystemStore
from minimalkv.cache import CacheDecorator

from redis import StrictRedis

# initialize redis instance
r = StrictRedis()

store = CacheDecorator(
  cache=RedisStore(r),
  store=FilesystemStore('.')
)

# will store the value in the FilesystemStore
store.put(u'some_value', '123')

# fetches from the FilesystemStore, but caches the result
print store.get(u'some_value')

# any further calls to store.get('some_value') will be served from the
# RedisStore now

class minimalkv.cache.CacheDecorator(cache: KeyValueStore, store: KeyValueStore)

Write-through cache decorator.

Can combine two KeyValueStore instances into a single caching KeyValueStore. On a data-read request, the cache will be consulted first, if there is a cache miss or an error, data will be read from the backing store. Any retrieved value will be stored in the cache before being forward to the client.

Write, key-iteration and delete requests will be passed on straight to the backing store. After their completion, the cache will be updated.

No cache maintainenace above this is done by the decorator. The caching store itselfs decides how large to grow the cache and which data to keep, which data to throw away.

Parameters

cacheKeyValueStore

The caching backend.

storeKeyValueStore

The backing store. This is the “authorative” backend.

copy(source: str, dest: str) → str

Copy data at key source to key dest.

Copies the data in the backing store and removes the destination key from the cache, in case it was already populated.

Parameters

sourcestr

The source key of data to copy.

deststr

The destination for the copy.

Returns

keystr

The destination key.

Raises

ValueError

If the underlying store does not support copy.

delete(key: str) → None

Delete data at key.

Deletes data from both the cache and the backing store.

Parameters

keystr

Key of data to be deleted.

get(key: str) → bytes

Return data at key as a bytestring.

If a cache miss occurs, the value is retrieved, stored in the cache and returned.

If the cache raises an IOError, the cache is ignored, and the backing store is consulted directly.

It is possible for a caching error to occur while attempting to store the value in the cache. It will not be handled as well.

Parameters

keystr

The key to be read.

Returns

databytes

Value associated with the key as a bytes object.

get_file(key: str, file: str | BinaryIO) → str

Write data at key to file.

If a cache miss occurs, the value is retrieved, stored in the cache and returned.

If the cache raises an IOError, the retrieval cannot proceed: If file was an open file, data maybe been written to it already. The IOError bubbles up.

It is possible for a caching error to occur while attempting to store the value in the cache. It will not be handled as well.

Parameters

keystr

The key to be read.

fileBinaryIO or str

Output filename or file-like object with a write method.

open(key: str) → BinaryIO

Open record at key.

If a cache miss occurs, the value is retrieved, stored in the cache, then then another open is issued on the cache.

If the cache raises an IOError, the cache is ignored, and the backing store is consulted directly.

It is possible for a caching error to occur while attempting to store the value in the cache. It will not be handled as well.

Parameters

keystr

Key to open.

Returns

file: BinaryIO

Read-only file-like object for reading data at key.

put(key: str, data: bytes) → str

Store bytestring data at key.

Will store the value in the backing store. Afterwards delete the (original) value at key from the cache.

Parameters

keystr

The key under which the data is to be stored.

databytes

Data to be stored at key, must be of type bytes.

Returns

key: str

The key under which data was stored.

put_file(key: str, file: str | BinaryIO) → str

Store contents of file at key.

Will store the value in the backing store. Afterwards delete the (original) value at key from the cache.

Parameters

keystr

Key where to store data in file.

fileBinaryIO or str

A filename or a file-like object with a read method.

Returns

key: str

The key under which data was stored.