_cache module

class cache_manager._cache.Cache(path=None, pkg=None)

Cache manager class, stores and manages the information in the registry database as well as the files in the cache directory.

Args:

path:

Explicit path to set the cache in. Overrides the pkg keyword argument. Optional, defaults to None.

pkg:

Package/module name the cache is used on. This sets the cache directory in a folder located in the OS default cache directory.

Attrs:

con:

Current connection to the SQL database, an instance of sqlite3.Connection.

cur:

Current cursor of the SQL database, an instance of sqlite3.Cursor.

path:

Path to the current cache registry.

dir:

The directory of the cache.

free_space:

Amount of free space available in the cache (in bytes).

autoclean()

Keeps only ready/in writing items and for each item the best version and deletes anything else in the cache registry.

best(uri, params=None, status=3, newer_than=None, older_than=None)

Searches for the best (latest) version of an item in the cache registry.

Return type

Optional[CacheItem]

Args:

uri:

Uniform Resource Identifier.

params:

Collection of parameters in dict format where key-value pairs correspond to parameter-value respectively. Optional, defaults to None.

status:

Integer (or set of) defining the valid status of the item to be searched. Optional, defaults to 3 (READY status).

newer_than:

Date the times are required to be newer than. Optional, defaults to None.

older_than:

Date the times are required to be older than. Optional, defaults to None.

Returns:

The CacheItem instance corresponding to the latest version of it.

Example:

>>> cache = cm.Cache('./')
>>> cache.create('foo')
CacheItem[foo V:1 UNINITIALIZED]
>>> cache.create('foo')
CacheItem[foo V:2 UNINITIALIZED]
>>> cache.best('foo', status=0)
CacheItem[foo V:2 UNINITIALIZED]

best_or_new(uri, params=None, status=3, newer_than=None, older_than=None, attrs=None, ext=None, label=None, new_status=1, filename=None)

Searches for the best version of an item (i.e. last version). If such item could not be found, it creates a new one.

Return type

CacheItem

Args:

uri:

Uniform Resource Identifier.

params:

Collection of parameters in dict format where key-value pairs correspond to parameter-value respectively. Optional, defaults to None.

status:

Integer (or set of) defining the valid status of the item to be searched. Optional, defaults to 3 (READY status).

newer_than:

Date the times are required to be newer than. Optional, defaults to None.

older_than:

Date the times are required to be older than. Optional, defaults to None.

attrs:

Attributes of the item to be searched or created as dictionary of key-value pairs corresponding to the name and value of the attributes. Optional, defaults to None.

ext:

Extension of the file associated to the item. Optional, defaults to None. Currently not implemented.

label:

Label for the item (e.g. type, group, category…). Optional, defaults to None.

new_status:

Integer defining the new status to be set in the case a new item is created. Optional, defaults to 1 (WRITE status).

filename:

Name of the file associated to the item. Optional, defaults to None.

Returns:

The CacheItem instance of the best or new item according to the provided attributes.

Examples:

>>> cache = cm.Cache('./')
>>> cache.create('foo')
CacheItem[foo V:1 UNINITIALIZED]
>>> cache.create('foo')
CacheItem[foo V:2 UNINITIALIZED]
>>> cache.best_or_new('foo', status=0)
CacheItem[foo V:2 UNINITIALIZED]
>>> cache.best_or_new('bar')
CacheItem[bar V:1 WRITE]

by_attrs(attrs)

Searches entries in the registry based on their attributes (stored in the differen type-based attribute tables).

Return type

set[int]

Args:

attrs:

Attributes and corresponding values of the items to search for. By default, the different attributes in the search must be satisfied. This is, items that fulfill all the attribute-value pairs, will be included in the search result. In case one wants the results of the search to just fulfill at least one term, it must include the following key-value pair in the argument: ‘__and’: False. See example below.

Returns:

Set of keys corresponding to the elements in the registry with the searched attributes.

Examples:

>>> cache = cm.Cache('./')
>>> cache.create('foo1', attrs={'bar': 1, 'baz': 2})
CacheItem[foo1 V:1 UNINITIALIZED]
>>> cache.create('foo2', attrs={'bar': 1, 'baz': 5})
CacheItem[foo2 V:1 UNINITIALIZED]
>>> cache.by_attrs({'bar': 1, 'baz': 5})
{2}
>>> cache.by_attrs({'bar': 1, 'baz': 5, '__and': False})
{1, 2}

by_key(key, version)

Searches a single item by its key and version number.

Return type

CacheItem

Args:

key:

The key of the item to be fetched.

version:

The specific version of the item to be retrieved.

Returns:

The CacheItem instance of the item searched (if any).

Example:

>>> cache = cm.Cache('./')
>>> it = cache.create('foo')
>>> it.key
'31d0e534960b07c0bde745c17b05eaba'
>>> cache.by_key('31d0e534960b07c0bde745c17b05eaba', 1)
CacheItem[foo V:1 UNINITIALIZED]

clean_db()

Removes records from the database registry that do not have the corresponding file on the cache disk directory.

clean_disk()

Deletes files from the disk cache directory if they don’t have any record in the database registry.

contents()

Generates a collection of all the items in the database registry and files in the cache directory on the disk.

Return type

dict[str, dict[str, int | str | CacheItem]]

Returns:

Dictionary where keys correspond to each item’s version_id and values to dictionary with some of the item’s attributes, namely: status (current status of the item as integer), fname (file name as stored in the cache database), last_read (date where the item was last accessed), read_count (number of times the item has been accessed), item (the instance of the CacheItem itself), disk_fname (file name as stored in the cache directory on the disk).

Example:

>>> cache = cm.Cache('./')
>>> cache.create('foo')
CacheItem[foo V:1 UNINITIALIZED]
>>> cache.contents()
{'31d0e534960b07c0bde745c17b05eaba-1': {'status': 0, 'fname': '31d0            e534960b07c0bde745c17b05eaba-1', 'last_read': None, 'read_count': 0            , 'item': CacheItem[foo V:1 UNINITIALIZED], 'disk_fname': None}}

create(uri, params=None, attrs=None, status=0, ext=None, label=None, filename=None)

Creates a new entry in the registry.

Return type

CacheItem

Args:

uri:

Uniform Resource Identifier.

params:

Collection of parameters in dict format where key-value pairs correspond to parameter-value respectively. Optional, defaults to None.

attrs:

Extra attributes associated to the item. Keys are the attribute names and values their content. These attributes will be stored in the attribute tables according to their data type automatically. Optional, defaults to None.

status:

Status of the new item. Optional, defaults to 0.

ext:

Extension of the file associated to the item. Optional, defaults to None (automatically extracted from the file name).

label:

Label for the item (e.g. type, group, category…). Optional, defaults to None.

filename:

Name of the file associated to the item. Optional, defaults to None (automatically set).

Returns:

The newly created CacheItem instance.

Example:

>>> cache = cm.Cache('./')
>>> cache.create('foo')
CacheItem[31d0e534960b07c0bde745c17b05eaba V:1 UNINITIALIZED]

does_it_fit(size)

Checks whether a given size is lower than the current available space.

Return type

bool

Args:

size:

Integer corresponding to the size to be checked (in bytes).

Returns:

Whether the requested space is available.

move_in(path, uri=None, params=None, attrs=None, status=1, ext=None, label=None, filename=None)

Copies a file into the cache directory and creates the corresponding cache item registry.

Return type

CacheItem

Args:

path:

Current/original path of the file that has to be moved into the cache.

uri:

Uniform Resource Identifier. Optional, defaults to None.

params:

Collection of parameters in dict format where key-value pairs correspond to parameter-value respectively. Optional, defaults to None.

attrs:

Extra attributes associated to the item. Keys are the attribute names and values their content. These attributes will be stored in the attribute tables according to their data type automatically. Optional, defaults to None.

status:

Status of the new item. Optional, defaults to 1.

ext:

Extension of the file associated to the item. Optional, defaults to None (automatically extracted from the file name).

label:

Label for the item (e.g. type, group, category…). Optional, defaults to None.

filename:

Name of the file associated to the item. Optional, defaults to None (automatically set).

Returns:

The newly created CacheItem instance.

reload()

Reloads the cache_manager at the module level and reloads the current instance of Cache

remove(uri=None, params=None, version=None, attrs=None, status=None, ext=None, label=None, newer_than=None, older_than=None, key=None, disk=False, keep_record=True)

Removes item(s) from the cache. The removal procedure will depend on the parameters disk and keep_record, see argument description below for specifics on their behavior.

Return type

None

Args:

uri:

Uniform Resource Identifier. Optional, defaults to None.

params:

Collection of parameters in dict format where key-value pairs correspond to parameter-value respectively. Optional, defaults to None.

version:

Integer defining the version of the item to update. Optional, defaults to None.

attrs:

Extra attributes associated to the item. Keys are the attribute names and values their content. Optional, defaults to None. Currently not implemented

status:

Integer defining the status of the item to update. Optional, defaults to None.

ext:

Extension of the file associated to the item. Optional, defaults to None. Currently not implemented.

label:

Label for the item (e.g. type, group, category…). Optional, defaults to None. Currently not implemented.

newer_than:

Date the times are required to be newer than. Optional, defaults to None.

older_than:

Date the times are required to be older than. Optional, defaults to None.

key:

Unique key name for the item. Optional, defaults to None.

disk:

Whether to also remove the files associated to the entry(ies) from disk too. Optional, defaults to False.

keep_record:

Whether to keep the record of the entry in the registry (marks the entry status as trashed, status = -1). Otherwise the entry is permanently deleted. Optional, True by default.

Example:

>>> cache = cm.Cache('./')
>>> cache.create('foo')
CacheItem[foo V:1 UNINITIALIZED]
>>> cache.remove(uri='foo')
>>> cache.search(uri='foo')
[]

search(uri=None, params=None, status=None, version=None, newer_than=None, older_than=None, ext=None, label=None, filename=None, key=None, attrs=None, include_removed=False)

Looks up for items in the cache based on the passed parameter(s).

Return type

list[CacheItem]

Args:

uri:

Uniform Resource Identifier. Optional, defaults to None.

params:

Collection of parameters in dict format where key-value pairs correspond to parameter-value respectively. Optional, defaults to None.

status:

Integer defining the status of the item to update. Optional, defaults to None.

version:

Integer defining the version of the item to update. Optional, defaults to None.

newer_than:

Date the times are required to be newer than. Optional, defaults to None.

older_than:

Date the times are required to be older than. Optional, defaults to None.

ext:

Extension of the file associated to the item. Optional, defaults to None.

label:

Label for the item (e.g. type, group, category…). Optional, defaults to None.

filename:

Name of the file associated to the item. Optional, defaults to None.

key:

Unique key name for the item. Optional, defaults to None.

attrs:

Search by attributes. A dict of attribute names and values. Operators can be included at the end of the names or in front of the values, forming a tuple of length 2 in the latter case. Multiple values can be provided as lists. By default the attribute search parameters are joined by AND, this can be overridden by including “__and”: False in attrs. The types of the attributes will be inferred from the values, except if the values provided as their correct type, such as numeric types or datetime. Strings will be converted to dates only if prefixed with “DATE:”. Optional, defaults to None.

include_removed:

Whether to include items marked for removal (i.e. trashed, status = -1) in the search.

Returns:

List of CacheItem instances of the items fulfilling the search. terms.

Example:

>>> cache = cm.Cache('./')
>>> it = cache.create('foo')
>>> cache.search(uri='foo)
[CacheItem[foo V:1 UNINITIALIZED]]

update(uri=None, params=None, attrs=None, status=None, version=None, ext=None, label=None, newer_than=None, older_than=None, key=None, update=None)

Updates one or more items. All arguments except update are used to search for the items to be updated.

Args:

uri:

Uniform Resource Identifier. Optional, defaults to None.

params:

Collection of parameters in dict format where key-value pairs correspond to parameter-value respectively. Optional, defaults to None.

attrs:

Extra attributes associated to the item. Keys are the attribute names and values their content. Optional, defaults to None. Currently not implemented

status:

Integer defining the status of the item to update. Optional, defaults to None.

version:

Integer defining the version of the item to update. Optional, defaults to None.

ext:

Extension of the file associated to the item. Optional, defaults to None. Currently not implemented.

label:

Label for the item (e.g. type, group, category…). Optional, defaults to None. Currently not implemented.

newer_than:

Date the times are required to be newer than. Optional, defaults to None.

older_than:

Date the times are required to be older than. Optional, defaults to None.

key:

Unique key name for the item. Optional, defaults to None.

update:

Dictionary containing the key-value pairs of fields/attributes and the new values respectively to be updated. Optional, defaults to None.

Example:

>>> cache = cm.Cache('./')
>>> it = cache.create('foo', attrs={'bar': 123, 'baz': 456})
>>> it.attrs
{'bar': 123, 'baz': 456, '_uri': 'foo'}
>>> cache.update(uri='foo', update={'bar': 0})
>>> it = cache.search('foo')[0]
>>> it.attrs
{'_uri': 'foo', 'bar': 0, 'baz': 456}

update_status(uri=None, params=None, version=-1, status=3, key=None)

Updates the status of a given entry(ies) in the registry. All arguments other than status are used to identify/search the entry(ies) to update.

Args:

uri:

Uniform Resource Identifier. Optional, defaults to None.

params:

Collection of parameters in dict format where key-value pairs correspond to parameter-value respectively. Optional, defaults to None.

version:

Version number of the item(s). Optional, defaults to None.

status:

Integer defining the new status to be set. Optional, defaults to 3 (READY status).

key:

Unique identifier for the item (alphanumeric hash).

Example:

>>> cache = cm.Cache('./')
>>> it = cache.create('foo')
>>> it.status
0
>>> cache.update_status(uri='foo')
>>> it.status
3

property free_space: int

Calculates the available free space in the cache directory.

Returns:

The available space in bytes.