scistag.common.component.Component

class Component(cache_dir=None)

Bases: Cache

The Component class integrates the functionality for intelligent property handling and dynamic data loading and unloading.

It lays the foundation for the scistag.slidestag.widget.Widget class which needs to automatically react to the change to single properties to minimize the need of using methods to do so while keeping the memory footprint of applications such as SlideStag as low as possible even when many users are using a service at the same time.

• See properties for details about the property handling.

Parameters

• version –

  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

PROPERTIES	The Component class' base properties as dictionary
__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
properties	Stores this classes' properties and their behavior.

__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

__setattr__(key, value)

Customizes the setter behavior of the attributes of Component class objects.

If a property is defined in properties and a setter function with the name set_{key} exists it is automatically called instead of setting the value directly. If a property is flagged as “readOnly” and the user tries to modify this property a ValueException is raised.

Parameters

• key – The key of the (potential) property

• value – The new value

Return type

None

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.

PROPERTIES = {}

The Component class’ base properties as dictionary

Every dictionary entry should have the following structure:

• info: A short information describing the property’s data

• (optional) type: The property’s type, either a string or a Python type

• (optional) readOnly: Defines if the property may only be read.

  False by default

A class derived from Component should always extend it’s ancestor class’ PROPERTIES class attribute:

PROPERTIES = {"myNewAttribute": {"info": "Example for a new attribute", "type": int}} | Component.PROPERTIES

The PROPERTY class attribute should be assigned to every object’s property object attribute at the end of it’s constructor:

self.properties = self.PROPERTIES

See scistag.slidestag.widget.Widget for an extended example of it’s usage.

_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

properties

Stores this classes’ properties and their behavior.

They define which properties automatically call a setter function when being changed, which properties are read-only, their type etc.

To for example define a property x which shall automatically call it’s change handler set_x when being changed just declare it as common member variable, add it to this variable as key and declare the set_x method. When ever you want to change it’s value directly via myComponent.x = newValue the set_x function will be called. To prevent recursion this function then has to store the value directly to the object’s dictionary via self.__dict__[‘x’] = new_value.

To define read-only properties set theirs “readOnly” flag such as self.properties['x'] = {"readOnly": True}

For further details see Component.PROPERTIES.

Parameters

cache_dir – The directory in which temporary computing results can be stored on disk.

property version: int

Returns the cache version

Return type

int