Caches

The standard interface

Pyappcache supports multiple different cache backends, all with the same interface. No matter whether you’re using Redis, Memcache or the SQLiteCache you will use the same interface:

class pyappcache.cache.Cache(prefix='pyappache')

The standard, cross backend, interface to a cache.

prefix

A prefix that will be applied to cache keys to allow for multiple instances of this class to co-exist. Exact use varies by particular cache. Default is ‘pyappcache’.

compressor: Compressor

The compressor that will be used when a key asks for compression. Default is gzip via compression.GZIPCompressor

serialiser: Serialiser

The serialiers that will be used to turn Python objects back and forth into bytes. The default serialiser is pickle, via serialisation.PickleSerialiser

get(key)

Look up the value stored under a Key instance

Return type:

Optional[TypeVar(V)]

get_by_str(key_str)

Look up the value stored under a str.

Users of this method will have to construct string keys for themselves.

Return type:

Optional[Any]

set(key, value, ttl_seconds=0)

Set a value by Key

Return type:

None

set_by_str(key_str, value, ttl_seconds=0, compress=False)

Set a value by a str.

Return type:

None

invalidate(key)

Invalidate by Key.

Depending on the particular implementation of invalidation this may or may not immediately free memory in the underlying cache (usually not).

Return type:

None

abstract clear()

Remove all keys from the cache.

For most caches this will remove absolutely everything from the server, so use with care.

Return type:

None

Redis

class pyappcache.redis.RedisCache(client=None)

A redis Cache instance.

This uses GET/SET/DELETE.

clear() uses FLUSHDB

The clear method for this implementation will call FLUSHDB - and so remove everything in the database.

__init__(client=None)

Parameters:

client (Optional[Redis]) – A optional redis client to use. If one isn’t provided database 0 on localhost is used.

Memcache

class pyappcache.memcache.MemcacheCache(client=None)

An implementation of Cache for memcache.

All methods in this class will retry exactly once when the underlying pylibmc client returns a ConnectionError (to be robust against memcache restarts.

__init__(client=None)

Parameters:

client (Optional[Any]) – A optional (pylibmc-compatible) memcache client to use.

SqliteCache

Pyappcache also includes a Sqlite-based implementation of an LRU cache. This can be handy for scripts.

class pyappcache.sqlite_lru.SqliteCache(max_size=10000, connection=None)

Implementation of an LRU cache using sqlite3.

Note that as this is an LRU cache data accesses require write access (in order to update the last-used time).

__init__(max_size=10000, connection=None)

Parameters:

• max_size (int) – Maximum size of the LRU cache. Defaults to 10,000

• connection (Optional[Connection]) – Optionally, you can pass a sqlite3 connection. By default an in-memory database will be used (this will be is shared between all instances).

pyappcache.sqlite_lru.get_in_memory_conn()

Get a shared in-memory connection.

This is used by SqliteCache to get a named in-memory sqlite connection (pyappcache_memory - to avoid clobbering other users of in-memory sqlite databases) and multi-thread support.

See local sqlite file as cache for the common pattern of storing the cache in a file alongside a script.

Implementing support for a custom cache backend

If you use something else as a cache (a filesystem, some SQL database, dbm) implementing a custom driver is not too hard.

You need only subclass Cache and implement four abstract methods:

abstract Cache.get_raw(key_str)

Look up a value (as bytes) from a concrete key string.

Parameters:

key_str (str) – the (fully prefixed) key string to look up

Return type:

Optional[IO[bytes]]

abstract Cache.set_raw(key_str, value_bytes, ttl_seconds)

Set a value (as bytes) by a concrete key string.

Parameters:

key_str (str) – the (fully prefixed) key string to set.

Return type:

None

abstract Cache.invalidate_raw(key_str)

Invalidate a key by a concrete key string.

Parameters:

key_str (str) – the (fully prefixed) key string to invalidate

Return type:

None

abstract Cache.clear()

Remove all keys from the cache.

For most caches this will remove absolutely everything from the server, so use with care.

Return type:

None

Cache is implemented entirely in terms of these four methods so once you implement these, you get everything else “for free”.