API

class fcache.cache.FileCache(appname, flag='c', mode=438, keyencoding='utf-8', serialize=True, app_cache_dir=None)

A persistent file cache that is dictionary-like and has a write buffer.

appname is passed to platformdirs to determine a system-appropriate location for the cache files. The cache directory used is available via cache_dir.

By default, a write buffer is used, so writing to cache files is not done until sync() is explicitly called. This behavior can be changed using the optional flag argument.

Note

Keys and values are always stored as bytes objects. If data serialization is enabled, keys are returned as str objects. If data serialization is disabled, keys are returned as a bytes object.

Parameters:

• appname (str) – The app/script the cache should be associated with.

• flag (str) – How the cache should be opened. See below for details.

• mode – The Unix mode for the cache files or False to prevent changing permissions.

• keyencoding (str) – The encoding the keys use, defaults to ‘utf-8’. This is used if serialize is False; the keys are treated as bytes objects.

• serialize (bool) – Whether or not to (de)serialize the values. If a cache is used with a Shelf, set this to False.

• app_cache_dir (str) – absolute path to root cache directory to be used in place of system-appropriate location determined by platformdirs

The optional flag argument can be:

Value	Meaning
'r'	Open existing cache for reading only
'w'	Open existing cache for reading and writing
'c'	Open cache for reading and writing, creating it if it doesn’t exist (default)
'n'	Always create a new, empty cache, open for reading and writing

If a 's' is appended to the flag argument, the cache will be opened in sync mode. Writing to the cache will happen immediately and will not be buffered.

If an application needs to use more than one cache, then it should use subcaches. To create a subcache, append a series of one or more names separated by periods to the application name when creating a FileCache object (e.g. 'appname.subcache' or 'appname.subcache.subcache'). Subcaches are a way for an application to use more than one cache without polluting a user’s cache directory. All caches – main caches or subcaches – are totally independent. The only aspect in which they are linked is that all of an application’s caches exist in the same system directory. Because each cache is independent of every other cache, calling delete() on an application’s main cache will not delete data in its subcaches.

cache_dir

The absolute path to the directory where the cache files are stored. The appname passed to FileCache is used to determine a system-appropriate place to store the cache files.

close()

Sync the write buffer, then close the cache.

If a closed FileCache object’s methods are called, a ValueError will be raised.

create()

Create the write buffer and cache directory.

delete()

Delete the write buffer and cache directory.

sync()

Sync the write buffer with the cache files and clear the buffer.

If the FileCache object was opened with the optional 's' flag argument, then calling sync() will do nothing.

In addition to the four methods listed above, FileCache objects also support the following standard dict operations and methods:

list(f)

Return a list of all the keys used in the FileCache f.

len(f)

Return the number of items in the FileCache f.

f[key]

Return the item of f with key key. Raises a KeyError if key is not in the cache.

f[key] = value

Set f[key] to value.

del f[key]

Remove f[key] from f. Raises a KeyError if key is not in the cache.

key in f

Return True if f has a key key, else False.

key not in f

Equivalent to not key in f.

iter(f)

Return an iterator over the keys of the cache. This is a shortcut for iter(f.keys()).

clear()

Remove all items from the write buffer and cache.

The write buffer object and cache directory are not deleted.

get(key[, default])

Return the value for key if key is in the cache, else default. If default is not given, it defaults to None, so that this method never raises a KeyError.

items()

Return a new view of the cache’s items ((key, value) pairs). See the documentation of view objects.

keys()

Return a new view of the cache’s keys. See the documentation of view objects.

pop(key[, default])

If key is in the cache, remove it and return its value, else return default. If default is not given and key is not in the cache, a KeyError is raised.

popitem()

Remove and return a (key, value) pair from the cache.

setdefault(key[, default])

If key is in the cache, return its value. If not, insert key with a value of default and return default. default defaults to None.

update([other])

Update the cache with the key/value pairs from other, overwriting existing keys. Return None.

values()

Return a new view of the cache’s values. See the documentation of view objects.