scistag.common.cache.Cache

class Cache(version=1, cache_dir=None)

Bases: object

The Cache class shall help caching computation results, downloaded data but also objects with large wind-up time (such as neural networks) between execution sessions.

If you pass a version of 0 the get_app_session_id() will be used instead which will usually change on every restart except you set it yourself via set_app_session_id or are using a smart autoreloader such as VisualLog’s auto-reload capabilities which ensure this for you.

Parameters

• version (int) –

  The cache version. 1 by default.

  When ever you change this version all old cache values will be removed and/or ignored from the cache.

• cache_dir (Optional[str]) – The directory in which the cache data shall be stored

Methods

add_volatile_member	Adds a member to the volatile cache entry variable list so it can automatically be cleared upon unloading of this component.
cache	Tries to find the element key in the cache and return's it's content.
get	Returns a value from the cache.
get_app_session_id	Returns the app session id which is generated upon each application restart.
get_is_loading	Returns if the component is currently being loaded :rtype: bool :return: True if load is currently being executed for this component.
get_key_and_version	Returns the effective key, version combination to search for a key in combination with the cache's and the element's version.
handle_load	Event handling function for dynamically loading data on demand.
handle_unload	Event handler for unloading elements previously loaded in your handle_load function.
load	Call this before you start using a component for the first time.
override_app_session_id	Manually overrides the application's session ID.
set	Adds an item to the cache or updates it.
unload	Call this to unload all data from your component which was created during the handle_load execution and not flagged via a slash ("/") in its name as element to cache on disk.

Attributes

__annotations__
__dict__
__doc__
__module__
__weakref__	list of weak references to the object (if defined)
_app_session_id	The current run's session ID.
version	Returns the cache version
_access_lock	Multithreading access lock
_mem_cache	A cache for temporary data storage and objects with a life time bound to this component's usage state.
_mem_cache_versions	Version numbers for the elements stored in the memory cache
_mem_cache_params	Parameters for the elements stored in the memory cache
_disk_cache	Cache for persisting data between execution sessions
_version	The cache version.
loaded	Defines if the component was correctly loaded
_is_loading	Flag which tells if the component is currently being loaded and if new values added to the cache via self["objectName"] shall be flagged as volatile.
_volatile_cache_entries	Stores which cache entries shall be deleted upon the execution of unload().

__contains__(key)

Returns if an element exists in the cache.

Parameters

key – The item’s name

Return type

bool

Returns

True if the item exists.

__delitem__(key)

Deletes an element from the cache.

If the element does not exist a ValueError exception will be raised.

Parameters

key – The element’s name

add_volatile_member(name)

Adds a member to the volatile cache entry variable list so it can automatically be cleared upon unloading of this component.

When the component is unloaded (e.g. because a Widget or a Slide disappears) all members are automatically set to None to prevent that these objects are kept alive.

Parameters

name (str) – The name of the member variable to be added to the volatile

list.

Return type

None

cache(key, generator, *args, **kwargs)

Tries to find the element key in the cache and return’s it’s content. If no element with such a name and/or version number can be found generator be called to generate the data, store it in the cache for the next execution.

Parameters

• key (str) – The key of the cache element

• generator (Callable) – The function to call if the element is not stored in the cache yet.

• version –

  The version to assign to the cache entry. If either this or the cache’s main version get modified all prior cache entries will be ignored until they were update to this new version.

  Default version for memory cache entries is 0, for disk cache entries 1.

• hash_val – A single value, a list of values or a dict of values of which a hash value is computed and added to the version number to automatically invalidate it if any of the values changed.

• args – Argument parameters to be passed into the generator

• kwargs – Keyword parameter to be passed into the generator

Returns

The cached or newly created content

get(key, default=None, version=None, params=None, hash_params=False)

Returns a value from the cache.

If the element does not exist a ValueError exception will be raised.

Parameters

• key (str) – The item’s name.

• version –

  The cache element’s version.

  By default 0 for memory cache elements and 1 for disk cache elements.

• params (dict | None) – The parameters which were passed into the function and still need t match.

• hash_params – Defines the parameters shall be hashed to detect modifications.

• default – The value to return by default if no cache element could be found.

Returns

The item’s value.

Returns default if no value can be found.

classmethod get_app_session_id()

Returns the app session id which is generated upon each application restart.

Return type

int

get_is_loading()

Returns if the component is currently being loaded :rtype: bool :return: True if load is currently being executed for this component.

classmethod get_key_and_version(key, major, minor=None)

Returns the effective key, version combination to search for a key in combination with the cache’s and the element’s version.

Parameters

• key – The key (potentially still containing @version at it’s end), either “key” or “key@version”, e.g. “myDb@2”.

• major – The major version (provided by the cache object)

• minor –

  The minor version, per element.

  Default 0 for memory cache elements and 1 for disk cache entries.

Return type

tuple[str, str]

Returns

The effective key and version with which the element shall be persisted and which we assume upon restore.

Following rules apply: - minor >= 1: The cache’s version and the minor version are

combined. So if you change either the cache’s or the element version the element gets invalidated.

• minor <= -1: The data should be handled as “constant” which

  basically never changes. Changing the cache’s version has thus no effect, only if you directly change the element’s version.

• minor equals 0: The session’s ID will be used as minor version.

  This invalidates all cache entries when you completely close the app or service (including auto-restart mechanisms, e.g. for live-editing).

handle_load()

Event handling function for dynamically loading data on demand.

SciStag’s load and unload mechanism shall help minimizing the memory footprint of the application using it. If you have temporary data, for example a database which is just used while a component is used, a Slide or an ImageView while they are visible please overwrite this function, call it’s ancestor and then store your data in the “cache”.

You can do so by using the bracket operator like self['db'] = pd.read_csv(...), check if data is available via if 'db' in self: ... and access it via my_db = self['db'] accordingly.

All data stored this way will automatically get cleared and removed from the cache when the unload function is called, e.g. when the Slide or Widget disappears or when you call it for your custom component.

If you want to use member variables for storing your temporary data you can do so by calling add_volatile_member() and passing their name. Upon unloading None will be assigned to all registered variables.

Note: When overwriting this method call super().handle_load() at the beginning of yours.

handle_unload()

Event handler for unloading elements previously loaded in your handle_load function.

Note: When overwriting this method call super().handle_unload() at end beginning of yours.

load()

Call this before you start using a component for the first time. The scistag.slidestag.widget.Widget class does this automatically for all of its children when a Widget becomes visible.

classmethod override_app_session_id(session_id)

Manually overrides the application’s session ID.

Should only be used by application session managers.

Parameters

session_id (int) – The new session id

set(key, value, params=None, version=None)

Adds an item to the cache or updates it.

If a value is added (for the first time) during the execution of the component’s load() or handle_load method it is flagged as volatile and will be automatically removed again upon the execution of unload() / handle_unload().

Parameters

• key (str) – The item’s name

• value – The value to assign

• params (dict | None) – The parameters associated with the creation of value and to be stored (and verified) in combination with the version.

• version – The version of the cache element. By default 0 for memory cache elements and 1 for disk cache elements.

unload()

Call this to unload all data from your component which was created during the handle_load execution and not flagged via a slash (“/”) in its name as element to cache on disk.

_access_lock

Multithreading access lock

_app_session_id: int = 1668323886284

The current run’s session ID. is updated every re-start usually, may be stored and restored by helper classes such as the VisualLogAutoReloader between application restarts.

_disk_cache

Cache for persisting data between execution sessions

_is_loading

Flag which tells if the component is currently being loaded and if new values added to the cache via self["objectName"] shall be flagged as volatile.

During the execution of the load() function and their event handlers such as Widget.handle_load() this value is set to true. When new Widgets are added during this time or new values are added to the cache, e.g. via my_component[“data”] = load_data() they are flagged as volatile.

After the execution of unload() all volatile entries will be deleted from the cache and all widgets added as child will be automatically removed again.

_mem_cache

A cache for temporary data storage and objects with a life time bound to this component’s usage state.

A cache which whose content shall only live between a handle_load() and handle_unload(). This can be used to store data only while a component is being used, a Widget is visible etc. See handle_load().

_mem_cache_params

Parameters for the elements stored in the memory cache

_mem_cache_versions

Version numbers for the elements stored in the memory cache

_version

The cache version.

It is stored along all cache values stored on disk and only elements sharing the same version will be accepted.

_volatile_cache_entries

Stores which cache entries shall be deleted upon the execution of unload().

If a cache entry is added while _is_loading is set to True it will be added to this set. Upon the execution of unload() all elements named in this list will be removed from the _cache.

In addition you may add object member variables via add_volatile_member() which do not get removed but automatically cleared upon execution of unload.

loaded

Defines if the component was correctly loaded

property version: int

Returns the cache version

Return type

int