# 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.

  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

  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

  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

  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

  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

  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

  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]

  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]

  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

  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

  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

  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

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