scistag.datastag.data_stag_vault.DataStagVault

class DataStagVault

Bases: object

The root access point to a DataStag

Initializer

Methods

add	Adds given value to the element stored in the database.
collect_garbage	Executes a garbage collection removing outdated elements
delete	Deletes an element :type name: str :param name: The element's name :rtype: bool :return: True on success
delete_multiple	Deletes a set of elements.
exists	Verifies if given element exists
find	Finds a list of elements by name :type mask: str :param mask: The search mask.
get	Tries to read an element from the database :type name: str :param name: The element's name :type default: Union[str, bool, int, float, bytes, dict, list, ndarray, None] :param default: The default return value if the element does not exist :rtype: Union[str, bool, int, float, bytes, dict, list, ndarray, None] :return: The element
get_ex	Tries to read an element from the database.
get_local_vault	Returns the local vault instance
get_server_up_time	Get the server's working time to compute the deprecation of elements :rtype: float :return: Time offset since start in seconds
get_status	Returns the database status :type advanced: bool :param advanced: Defines if advanced details shall be received as well :return: A dictionary containing the status
get_sub_folders	Returns all sub folders of folder_name :param name: The main folder :param recursive: Defines if the search shall be recursive.
get_values_by_name	Returns the data of a set of elements by name.
lelements	Tries to receive a list of elements from the vault
llen	Tries to retrieve the data of a list
pop	Tries to remove an element at the beginning of a list :type name: str :param name: The name's list :type default: Union[str, bool, int, float, bytes, dict, list, ndarray, None] :param default: The default return value if the list is empty or does not exist :type index: int :param index: The index from which the element shall be "popped".
push	Appends an element at the end of a list :type name: str :param name: The element's name :type data: list[StagDataTypes] :param data: The data to be added.
set	Stores a named element in the database :type name: str :param name: The element's name :type data: StagDataTypes :param data: The data to be added.

Attributes

FOLDER_SEPARATOR	The sign which defines in which folder a key is located
__annotations__
__dict__
__doc__
__module__
__weakref__	list of weak references to the object (if defined)
local_vault
global_dictionary	A dictionary containing all elements
folders	A folder based more fine grained search index

_delete_element(name)

Deletes an element from the global database

Parameters

name (str) – The element’s name

Return type

bool

Returns

True on success

_get_element_by_name(name, deprecation_time=None)

Tries to retrieve a database element

Parameters

• name (str) – The element’s name

• deprecation_time (float | None) – The server uptime in seconds. If provided the element will be deleted if it timed out.

Return type

DataStagElement | None

_get_folder(name)

Returns the element’s folder name defined by slashes

Parameters

name (str) – The elements name

Return type

str

Returns

The folder, “” if none

_get_global_name(folder_name, rel_name)

Returns the global element name :param folder_name: The folder name :param rel_name: The relative element name :return: Combined global element name

_get_list_instance(name)

Tries to retrieve the element of the type list

Parameters

name (str) – The element’s name

Return type

DataStagList | None

Returns

_get_round_deprecation_time(dep_time)

Returns the deprecation time rounded up to the next second as integer

Parameters

dep_time (float) – The deprecation time

Returns

Deprecation time in seconds

_register_element(name, element)

Registers a new element in the global map and the search tree

Parameters

• name (str) – The element’s name

• element (DataStagElement) – The element

_remove_from_deprecation_list(element)

Checks whether the element was already in a deprecation list and removes if from that one

Parameters

element (DataStagElement) – The element

Returns

True if the element was already existing and had to be removed

_split_folder_and_name(name)

Returns the element’s folder name defined by slashes

Parameters

name – The elements name

Returns

The folder and file name

_update_deprecating_element(element, dep_time=None)

Registers the element in the deprecation registry so it can automatically be destroyed once it’s outdated

Parameters

• element (DataStagElement) – The element

• dep_time (Optional[float]) – The element’s new deprecation time

add(name, value=1, timeout_s=None, default=0)

Adds given value to the element stored in the database. If it does not exist yet, it will be initialized with default. :type name: str :param name: The element’s name :type value: float | int :param value: The value to be added :type timeout_s: float | None :param timeout_s: The timeout for automatic deletion :param default: The default value :rtype: float | int :return: The new value

collect_garbage()

Executes a garbage collection removing outdated elements

Return type

bool

Returns

True if at least one time interval passed

delete(name)

Deletes an element :type name: str :param name: The element’s name :rtype: bool :return: True on success

delete_multiple(search_masks, recursive=False)

Deletes a set of elements. :type search_masks: list[str] :param search_masks: The element’s names or search masks. May not point directly to the root directory :type recursive: bool :param recursive: Defines if the search shall be executed recursive :rtype: int :return: The count of removed elements

exists(name)

Verifies if given element exists

Parameters

name (str) – The element’s name

Return type

bool

Returns

True if the element exists

find(mask, limit=100, relative_names=False, recursive=False)

Finds a list of elements by name :type mask: str :param mask: The search mask. If it contains a folder the mask is only applied to the nested element :type limit: int :param limit: The maximum count of entries :type relative_names: bool :param relative_names: Defines if the relative names shall be returned :type recursive: bool :param recursive: Defines if the search shall continue recursive :return: A list of elements of all valid elements matching the search mask

get(name, default=None)

Tries to read an element from the database :type name: str :param name: The element’s name :type default: Union[str, bool, int, float, bytes, dict, list, ndarray, None] :param default: The default return value if the element does not exist :rtype: Union[str, bool, int, float, bytes, dict, list, ndarray, None] :return: The element

get_ex(name, default=None, version_counter=-1)

Tries to read an element from the database. Allows to add a version check so only data will be returned if it changed since the last get_ex. :param name: The element’s name :param default: The default return value if the element does not exist :param version_counter: If set then a value will only be returned if the element’s update counter does not match :return: The element’s version, The element

classmethod get_local_vault()

Returns the local vault instance

Return type

DataStagVault

static get_server_up_time()

Get the server’s working time to compute the deprecation of elements :rtype: float :return: Time offset since start in seconds

get_status(advanced=False)

Returns the database status :type advanced: bool :param advanced: Defines if advanced details shall be received as well :return: A dictionary containing the status

get_sub_folders(name, recursive=True)

Returns all sub folders of folder_name :param name: The main folder :param recursive: Defines if the search shall be recursive. :return: The list of all nested folders

get_values_by_name(mask, limit=100, flat=True)

Returns the data of a set of elements by name. :type mask: str :param mask: The search mask. If it contains a folder the mask is only applied to the nested element :type limit: int :param limit: The maximum count of entries :type flat: bool :param flat: Returns a list of all values received without providing the element names :return: A list containing the data and names of all valid elements

lelements(name, start, end)

Tries to receive a list of elements from the vault

Parameters

• name (str) – The list’s name

• start (int) – The first element’s index

• end (int | None) – The stop index (not included anymore). -1 = end of the list

Return type

list[StagDataTypes]

Returns

The list’s content in given range

llen(name)

Tries to retrieve the data of a list

Parameters

name (str) – The list’s name

Return type

int

Returns

The list length’s if it does exist. Otherwise 0.

pop(name, default=None, index=0)

Tries to remove an element at the beginning of a list :type name: str :param name: The name’s list :type default: Union[str, bool, int, float, bytes, dict, list, ndarray, None] :param default: The default return value if the list is empty or does not exist :type index: int :param index: The index from which the element shall be “popped”. By default from the front :rtype: Union[str, bool, int, float, bytes, dict, list, ndarray, None] :return: The element which was removed

push(name, data, timeout_s=None, index=-1)

Appends an element at the end of a list :type name: str :param name: The element’s name :type data: list[StagDataTypes] :param data: The data to be added. See StagDataTypes for supported types :type timeout_s: float | None :param timeout_s: The timeout for automatic deletion in seconds :param index: The index at which the elements shall be inserted. By default at the end. :rtype: int :return: The new length of the list

set(name, data, timeout_s=None)

Stores a named element in the database :type name: str :param name: The element’s name :type data: StagDataTypes :param data: The data to be added. See StagDataTypes for supported types :type timeout_s: float | None :param timeout_s: The timeout for automatic deletion :rtype: bool :return: True on success

FOLDER_SEPARATOR = '.'

The sign which defines in which folder a key is located

folders: dict[str, dict]

A folder based more fine grained search index

global_dictionary: dict[str, scistag.datastag.data_stag_element.DataStagElement]

A dictionary containing all elements