calliope.cache

Module Contents

Classes

Cache

Abstract base class that defines the Cache interface.

SqliteCache

Cache implemention which uses the SQLite database library.

Functions

save_cache_path(*resource)

Ensure $XDG_CACHE_HOME/<resource>/ exists, and return its path.

open(namespace[, cachedir])

Open a cache using the best available cache implementation.

Attributes

CacheLookupResult

The result of looking for a value in a cache.
calliope.cache.save_cache_path(*resource)

Ensure $XDG_CACHE_HOME/<resource>/ exists, and return its path. ‘resource’ should normally be the name of your application or a shared resource.

calliope.cache.CacheLookupResult

The result of looking for a value in a cache.

Tuple with named values: (found_timestamp, value).

If the value is found, found_timestamp will be set to the datetime of when it was stored. Otherwise, found_timestamp will be None.

exception calliope.cache.CacheError

Bases: Exception

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

class calliope.cache.Cache(namespace, cachedir=None)

Abstract base class that defines the Cache interface.

Do not use this class directly. Call the open() module method instead.

abstract lookup(key)

Lookup ‘key’ in the cache.

Returns a CacheLookupResult tuple.

Return type:

CacheLookupResult

abstract store(key, value, timestamp=None)

Store ‘value’ in the cache under the given key.

The contents of ‘value’ must be representable as JSON data.

The value will be marked with the current timestamp so cache expiry can be done. The timestamp parameter overrides this if needed.

wrap(key, call, expiry=None)

Either run call() and save the result, or return cached result.

This is intended for use when calling remote APIs. Lots of network access can be avoided if the result is saved for future use. For example, this snipped is used in the lastfm.similar_artists() function:

def similar_artists(lastfm, artist_name):
entry = lastfm.cache.wrap(‘artist-similar:{}’.format(artist_name),

lambda: lastfm.api.artist.get_similar(artist_name, limit=count))

By default, items in the cache never expire. You can pass a datetime.timedelta instance to force entries to expire after a certain time period. This may be an hour, a day or a week depending how soon changes in the remote API result need to be detected.

Parameters:

expiry (datetime.timedelta) –

sync()

Ensure data is synchronised to disk.

This may be a no-op. Or, it may block for an unknown amount time.

class calliope.cache.SqliteCache(namespace, cachedir=None, retry_timeout=30)

Bases: Cache

Cache implemention which uses the SQLite database library.

lookup(key)

Lookup ‘key’ in the cache.

Returns a tuple of (found_timestamp, value). If the value is not found in the cache, both values will be None.

store(key, value, timestamp=None)

Store ‘value’ in the cache under the given key.

The contents of ‘value’ must be representable as JSON data.

The value will be marked with the current timestamp so cache expiry can be done. The timestamp parameter overrides this if needed.

close()

Close cache.

This maybe needed to flush data to disk, depending on the implementation.

calliope.cache.open(namespace, cachedir=None)

Open a cache using the best available cache implementation.

The ‘namespace’ parameter should usually correspond with the name of tool or module using the cache.

The ‘cachedir’ parameter is mainly for use during automated tests.