Base API

class cachelib.base.BaseCache(default_timeout=300)

Bases: object

Baseclass for the cache systems. All the cache systems implement this API or a superset of it.

Parameters:

default_timeout (int) – the default timeout (in seconds) that is used if no timeout is specified on set(). A timeout of 0 indicates that the cache never expires.

get(key)

Look up key in the cache and return the value for it.

Parameters:

key (str) – the key to be looked up.

Returns:

The value if it exists and is readable, else None.

Return type:

Any

delete(key)

Delete key from the cache.

Parameters:

key (str) – the key to delete.

Returns:

Whether the key existed and has been deleted.

Return type:

boolean

get_many(*keys)

Returns a list of values for the given keys. For each key an item in the list is created:

foo, bar = cache.get_many("foo", "bar")

Has the same error handling as get().

Parameters:

keys (str) – The function accepts multiple keys as positional arguments.

Return type:

List[Any]

get_dict(*keys)

Like get_many() but return a dict:

d = cache.get_dict("foo", "bar")
foo = d["foo"]
bar = d["bar"]
Parameters:

keys (str) – The function accepts multiple keys as positional arguments.

Return type:

Dict[str, Any]

set(key, value, timeout=None)

Add a new key/value to the cache (overwrites value, if key already exists in the cache).

Parameters:

  • key (str) – the key to set

  • value (Any) – the value for the key

  • timeout (int | None) – the cache timeout for the key in seconds (if not specified, it uses the default timeout). A timeout of 0 indicates that the cache never expires.

Returns:

True if key has been updated, False for backend errors. Pickling errors, however, will raise a subclass of pickle.PickleError.

Return type:

boolean

add(key, value, timeout=None)

Works like set() but does not overwrite the values of already existing keys.

Parameters:

  • key (str) – the key to set

  • value (Any) – the value for the key

  • timeout (int | None) – the cache timeout for the key in seconds (if not specified, it uses the default timeout). A timeout of 0 indicates that the cache never expires.

Returns:

Same as set(), but also False for already existing keys.

Return type:

boolean

set_many(mapping, timeout=None)

Sets multiple keys and values from a mapping.

Parameters:

  • mapping (Dict[str, Any]) – a mapping with the keys/values to set.

  • timeout (int | None) – the cache timeout for the key in seconds (if not specified, it uses the default timeout). A timeout of 0 indicates that the cache never expires.

Returns:

A list containing all keys successfully set

Return type:

boolean

delete_many(*keys)

Deletes multiple keys at once.

Parameters:

keys (str) – The function accepts multiple keys as positional arguments.

Returns:

A list containing all successfully deleted keys

Return type:

boolean

has(key)

Checks if a key exists in the cache without returning it. This is a cheap operation that bypasses loading the actual data on the backend.

Parameters:

key (str) – the key to check

Return type:

bool

clear()

Clears the cache. Keep in mind that not all caches support completely clearing the cache.

Returns:

Whether the cache has been cleared.

Return type:

boolean

inc(key, delta=1)

Increments the value of a key by delta. If the key does not yet exist it is initialized with delta.

For supporting caches this is an atomic operation.

Parameters:

  • key (str) – the key to increment.

  • delta (int) – the delta to add.

Returns:

The new value or None for backend errors.

Return type:

int | None

dec(key, delta=1)

Decrements the value of a key by delta. If the key does not yet exist it is initialized with -delta.

For supporting caches this is an atomic operation.

Parameters:

  • key (str) – the key to increment.

  • delta (int) – the delta to subtract.

Returns:

The new value or None for backend errors.

Return type:

int | None

class cachelib.base.NullCache(default_timeout=300)

Bases: BaseCache

A cache that doesn’t cache. This can be useful for unit testing.

Parameters:

default_timeout (int) – a dummy parameter that is ignored but exists for API compatibility with other caches.

has(key)

Checks if a key exists in the cache without returning it. This is a cheap operation that bypasses loading the actual data on the backend.

Parameters:

key (str) – the key to check

Return type:

bool