Base API

class cachelib.base.BaseCache(default_timeout=300, ignore_delete_many_errors=True)

Bases: object

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

Parameters:

  • default_timeout (int | timedelta) –

    the default timeout that is used if no timeout is specified on set(). Either a number of seconds or a datetime.timedelta. A timeout of 0 indicates that the cache never expires.

    Changed in version 0.17.0: Accepts a datetime.timedelta.

  • ignore_delete_many_errors (bool) –

    If False, delete_many() will raise a RuntimeError if any key fails to delete. Keys that do not exist are considered successfully deleted and do not raise.

    Changelog

    Added in version 0.16.0.

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:

bool

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 | timedelta | None) – the cache timeout for the key, either a number of seconds or a datetime.timedelta (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:

bool | None

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 | timedelta | None) – the cache timeout for the key, either a number of seconds or a datetime.timedelta (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:

bool

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 | timedelta | None) – the cache timeout for the key, either a number of seconds or a datetime.timedelta (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:

list[Any]

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

Raises:

RuntimeError – If ignore_delete_many_errors is False and a key still exists after the delete attempt.

Return type:

list[Any]

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:

bool

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, ignore_delete_many_errors=True)

Bases: BaseCache

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

Parameters:

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

  • ignore_delete_many_errors (bool)

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