API

class fcache.Cache(cachename, appname[, appauthor=None])

Take cachename and appname, then create a cache file. If a matching cache file was found, a new one is not created.

appauthor is used on Windows to determine the appropriate cache directory. If not provided, it defaults to appname. See appdirs‘s documentation for more information.

Parameters:

• cachename (string) – a unique name for the cache.
• appname (string) – the name of the application the cache is created for.
• appauthor (string or None) – the name of the application’s author – if None, defaults to appname.

cachedir

The cache file’s parent directory, as determined by appdirs.user_cache_dir(). Treat this attribute as read-only.

cachename

The cache’s name, as passed to the Cache constructor method. Treat this attribute as read-only.

filename

The cache’s filename. It’s formed by passing cachename to hashlib‘s sha1() constructor. Treat this attribute as read-only.

delete()

Delete the cache file.

On Windows, if the file is in use by another application, an exception is raised. See os.remove() for more information.

Raises exceptions.OSError:  the cache file does not exist.

flush()

Clear all data from the cache. This removes all key/value pairs from the cache.

Raises exceptions.IOError:  the cache file does not exist.

get(key[, override=False])

Get data from the cache. All data stored under the name, key, is returned. If the data is expired, None is returned. Expired data is returned if override is True.

Parameters:

• key (string) – the name of the data to fetch.
• override (bool) – return expired data; defaults to False.

Returns:

the requested data or None if the requested data has expired.

Raises:

• exceptions.KeyError – key was not found.
• exceptions.IOError – the cache file does not exist or cannot be read.
• pickle.UnpicklingError – there was a problem unpickling an object.

Changed in version 0.2: Added the override argument.

invalidate([key=None])

Force data to expire. After forcing key to expire, calling get() on key will return None.

If key is None, then all data is forced to expire.

Parameters:

key (string or None) – the name of the data to invalidate; if None, defaults to all data.

Raises:

• exceptions.KeyError – key was not found.
• exceptions.IOError – the cache file does not exist or cannot be read.

New in version 0.2.

Changed in version 0.3: If key is None, then all data is forced to expire.

items([override=False])

Return a list of the cache’s keys and values. By default, only keys and values of non-expired data are returned. If override is True, then all keys and values are returned.

Parameters:

override (bool) – return expired keys and values; defaults to False.

Returns:

a list of cache keys/values, where each pair is a tuple.

Raises:

• exceptions.IOError – the cache file does not exist or cannot be read.
• pickle.UnpicklingError – there was a problem unpickling an object.

New in version 0.3.

keys([override=False])

Return a list of the cache’s keys. By default, only the keys that have valid data are returned. If override is True, then all keys are returned.

Parameters:

override (bool) – return expired data’s keys; defaults to False.

Returns:

a list of the cache’s keys.

Raises:

• exceptions.IOError – the cache file does not exist or cannot be read.
• pickle.UnpicklingError – there was a problem unpickling an object.

New in version 0.3.

remove(key)

Remove data from the cache. All data stored under key is deleted from the cache.

Parameters:

key (string) – the name of the data to remove.

Raises:

• exceptions.KeyError – key was not found.
• exceptions.IOError – the cache file does not exist or cannot be read.

set(key, value[, timeout=None])

Store data in the cache. The data, value, is stored under the name, key, in the cache. The data must be picklable. Optionally, the data can expire after timeout seconds have passed.

Parameters:

• key (string) – the name given to the data.
• value – the data to be stored.
• timeout (int, long, float, or None) – how long in seconds the data should be considered valid – if None, defaults to forever.

Raises:

• pickle.PicklingError – an unpicklable object was passed.
• exceptions.IOError – the cache file does not exist or cannot be read.

set_default(key[, default=None, timeout=None)

If key exists, return its value; if not, create key.

If key is in the cache and its data is valid, return its value. If not, store key with default value into the cache for timeout seconds and return default.

Works like dict.setdefault().

Parameters:

• key (string) – the name of the data to fetch/store.
• default – data to store and return if key doesn’t exist or doesn’t have valid data. Defaults to None.
• timeout (int, long, float, or None) – how long in seconds default should be considered valid; if None, defaults to forever.

Returns:

the value of key if it exists and is valid; if not, then the value of default.

Raises:

• exceptions.IOError – the cache file does not exist or cannot be read.
• pickle.UnpicklingError – there was a problem unpickling an object.
• pickle.PicklingError – an unpicklable object was passed.

New in version 0.3.

values([override=False])

Return a list of the cache’s values. By default, only values that are not expired are returned. If override is True, then all values are returned.

Parameters:

override (bool) – return expired data; defaults to False.

Returns:

a list of the cache’s values.

Raises:

• exceptions.IOError – the cache file does not exist or cannot be read.
• pickle.UnpicklingError – there was a problem unpickling an object.

New in version 0.3.