File Backend

class cachelib.file.FileSystemCache(cache_dir, threshold=500, default_timeout=300, mode=None, hash_method=hashlib.sha256, ignore_delete_many_errors=True)

Bases: BaseCache

A cache that stores the items on the file system. This cache depends on being the only user of the cache_dir. Make absolutely sure that nobody but this cache stores files there or otherwise the cache will randomly delete files therein.

Parameters:

  • cache_dir (str) – the directory where cache files are stored.

  • threshold (int) – the maximum number of items the cache stores before it starts deleting some. A threshold value of 0 indicates no threshold.

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

  • mode (int | None) – the file mode wanted for the cache files, default 0600

  • hash_method (Any) – Default sha256(). The hash method used to generate the filename for cached results.

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

serializer = <cachelib.serializers.FileSystemSerializer object>
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

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

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(key, value, timeout=None, mgmt_element=False)

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.

  • mgmt_element (bool)

Returns:

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

Return type:

bool

delete(key, mgmt_element=False)

Delete key from the cache.

Parameters:

  • key (str) – the key to delete.

  • mgmt_element (bool)

Returns:

Whether the key existed and has been deleted.

Return type:

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