spinetoolbox.spine_db_manager

The SpineDBManager class

authors:

16. Vennström (VTT) and M. Marin (KTH)

date:

2.10.2019

Module Contents

Classes

SpineDBManager

Class to manage DBs within a project.

Functions

do_create_new_spine_database(url)

Creates a new spine database at the given url.

spinetoolbox.spine_db_manager.do_create_new_spine_database(url)

Creates a new spine database at the given url.

class spinetoolbox.spine_db_manager.SpineDBManager(settings, logger, project)

Bases: PySide2.QtCore.QObject

Class to manage DBs within a project.

TODO: Expand description, how it works, the cache, the signals, etc.

Initializes the instance.

Parameters:

• settings (QSettings) – Toolbox settings
• logger (LoggingInterface) – a general, non-database-specific logger
• project (SpineToolboxProject) –

database_created

session_refreshed

session_committed

session_rolled_back

scenarios_added

alternatives_added

object_classes_added

objects_added

relationship_classes_added

relationships_added

entity_groups_added

parameter_definitions_added

parameter_values_added

parameter_value_lists_added

parameter_tags_added

scenarios_removed

alternatives_removed

object_classes_removed

objects_removed

relationship_classes_removed

relationships_removed

entity_groups_removed

parameter_definitions_removed

parameter_values_removed

parameter_value_lists_removed

parameter_tags_removed

scenarios_updated

alternatives_updated

object_classes_updated

objects_updated

relationship_classes_updated

relationships_updated

parameter_definitions_updated

parameter_values_updated

parameter_value_lists_updated

parameter_tags_updated

parameter_definition_tags_set

items_removed_from_cache

_scenario_alternatives_added

_scenario_alternatives_updated

_scenario_alternatives_removed

_parameter_definition_tags_added

_parameter_definition_tags_removed

_GROUP_SEP = ǀ

db_maps

db_editors

create_new_spine_database(self, url)

close_session(self, url)

Pops any db map on the given url and closes its connection.

Parameters:url (str) –

close_all_sessions(self)

Closes connections to all database mappings.

show_data_store_form(self, db_url_codenames, logger)

Creates a new SpineDBEditor and shows it.

Parameters:

• db_url_codenames (dict) – Mapping db urls to codenames.
• logger (LoggingInterface) – Where to log SpineDBAPIError

get_db_map(self, url, logger, upgrade=False, codename=None)

Returns a DiffDatabaseMapping instance from url if possible, None otherwise. If needed, asks the user to upgrade to the latest db version.

Parameters:

• url (str, URL) –
• logger (LoggingInterface) – Where to log SpineDBAPIError
• upgrade (bool, optional) –
• codename (str, NoneType, optional) –

Returns:

DiffDatabaseMapping, NoneType

_do_get_db_map(self, url, upgrade, codename)

Returns a memorized DiffDatabaseMapping instance from url. Called by get_db_map.

Parameters:

• url (str, URL) –
• upgrade (bool, optional) –
• codename (str, NoneType, optional) –

Returns:

DiffDatabaseMapping

register_listener(self, ds_form, *db_maps)

Register given ds_form as listener for all given db_map’s signals.

Parameters:

• ds_form (SpineDBEditor) –
• db_maps (DiffDatabaseMapping) –

unregister_listener(self, ds_form, db_map)

Unregisters given ds_form from given db_map signals.

Parameters:

• ds_form (SpineDBEditor) –
• db_map (DiffDatabaseMapping) –

set_logger_for_db_map(self, logger, db_map)

unset_logger_for_db_map(self, db_map)

fetch_db_maps_for_listener(self, listener, *db_maps)

Fetches given db_map for given listener.

Parameters:

• listener (SpineDBEditor) –
• *db_maps – database maps to fetch

_clean_up_fetcher(self, fetcher)

Cleans up things after fetcher has finished working.

Parameters:fetcher (SpineDBFetcher) – the fetcher to clean up

_stop_fetchers(self)

Quits all fetchers and deletes them.

refresh_session(self, *db_maps)

commit_session(self, *db_maps, rollback_if_no_msg=False, cookie=None)

Commits the current session.

Parameters:

• *db_maps – database maps to commit
• rollback_if_no_msg (bool) – if True, the commit will be rolled back if no commit message is provided
• cookie (object, optional) – a free form identifier which will be forwarded to session_committed signal

static _get_commit_msg(db_map)

rollback_session(self, *db_maps)

static _get_rollback_confirmation(db_map)

_commit_db_map_session(self, db_map)

_rollback_db_map_session(self, db_map)

ok_to_close(self, db_map)

Prompts the user to commit or rollback changes to given database map.

Returns:True if successfully committed or rolled back, False otherwise Return type:bool

connect_signals(self)

Connects signals.

error_msg(self, db_map_error_log)

cache_items(self, item_type, db_map_data)

Caches data for a given type. It works for both insert and update operations.

Parameters:

• item_type (str) –
• db_map_data (dict) – lists of dictionary items keyed by DiffDatabaseMapping

update_icons(self, db_map_data)

Runs when object classes are added or updated. Setups icons for those classes. :param item_type: :type item_type: str :param db_map_data: lists of dictionary items keyed by DiffDatabaseMapping :type db_map_data: dict

entity_class_icon(self, db_map, entity_type, entity_class_id, for_group=False)

Returns an appropriate icon for a given entity_class.

Parameters:

• db_map (DiffDatabaseMapping) –
• entity_type (str) – either ‘object_class’ or ‘relationship_class’
• entity_class_id (int) –

Returns:

QIcon

get_item(self, db_map, item_type, id_)

Returns the item of the given type in the given db map that has the given id, or an empty dict if not found.

Parameters:

• db_map (DiffDatabaseMapping) –
• item_type (str) –
• id (int) –

Returns:

dict

_pop_item(self, db_map, item_type, id_)

get_item_by_field(self, db_map, item_type, field, value)

Returns the first item of the given type in the given db map that has the given value for the given field Returns an empty dictionary if none found.

Parameters:

• db_map (DiffDatabaseMapping) –
• item_type (str) –
• field (str) –
• value –

Returns:

dict

get_items_by_field(self, db_map, item_type, field, value)

Returns all items of the given type in the given db map that have the given value for the given field. Returns an empty list if none found.

Parameters:

• db_map (DiffDatabaseMapping) –
• item_type (str) –
• field (str) –
• value –

Returns:

list

get_items(self, db_map, item_type)

Returns all the items of the given type in the given db map, or an empty list if none found.

Parameters:

• db_map (DiffDatabaseMapping) –
• item_type (str) –

Returns:

list

get_field(self, db_map, item_type, id_, field)

static _display_data(parsed_data)

Returns the value’s database representation formatted for Qt.DisplayRole.

static _tool_tip_data(parsed_data)

Returns the value’s database representation formatted for Qt.ToolTipRole.

get_value(self, db_map, item_type, id_, role=Qt.DisplayRole)

Returns the value or default value of a parameter.

Parameters:

• db_map (DiffDatabaseMapping) –
• item_type (str) – either “parameter_definition” or “parameter_value”
• id (int) – The parameter_value or definition id
• role (int, optional) –

static parse_value(db_value)

format_value(self, parsed_value, role=Qt.DisplayRole)

Formats the given value for the given role.

Parameters:

• parsed_value (object) – A python object as returned by spinedb_api.from_database
• role (int, optional) –

get_value_indexes(self, db_map, item_type, id_)

Returns the value or default value indexes of a parameter.

Parameters:

• db_map (DiffDatabaseMapping) –
• item_type (str) – either “parameter_definition” or “parameter_value”
• id (int) – The parameter_value or definition id

get_value_index(self, db_map, item_type, id_, index, role=Qt.DisplayRole)

Returns the value or default value of a parameter for a given index.

Parameters:

• db_map (DiffDatabaseMapping) –
• item_type (str) – either “parameter_definition” or “parameter_value”
• id (int) – The parameter_value or definition id
• index – The index to retrieve
• role (int, optional) –

_split_and_parse_value_list(self, item)

get_value_list_item(self, db_map, id_, index, role=Qt.DisplayRole)

Returns one value item of a parameter_value_list.

Parameters:

• db_map (DiffDatabaseMapping) –
• id (int) – The parameter_value_list id
• index (int) – The value item index
• role (int, optional) –

get_parameter_value_list(self, db_map, id_, role=Qt.DisplayRole)

Returns a parameter_value_list formatted for the given role.

Parameters:

• db_map (DiffDatabaseMapping) –
• id (int) – The parameter_value_list id
• role (int, optional) –

static get_db_items(query, key=lambda x: x['id'])

static _make_query(db_map, sq_name, ids=())

get_alternatives(self, db_map, ids=())

Returns alternatives from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_scenarios(self, db_map, ids=())

Returns scenarios from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_scenario_alternatives(self, db_map, ids=())

Returns scenario alternatives from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_object_classes(self, db_map, ids=())

Returns object classes from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_objects(self, db_map, ids=())

Returns objects from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_relationship_classes(self, db_map, ids=())

Returns relationship classes from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_relationships(self, db_map, ids=())

Returns relationships from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_entity_groups(self, db_map, ids=())

Returns entity groups from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_object_parameter_definitions(self, db_map, ids=())

Returns object parameter definitions from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_relationship_parameter_definitions(self, db_map, ids=())

Returns relationship parameter definitions from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_parameter_definitions(self, db_map, ids=())

Returns both object and relationship parameter definitions.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_parameter_definition_tags(self, db_map, ids=())

Returns parameter definition tags.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_object_parameter_values(self, db_map, ids=())

Returns object parameter values from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_relationship_parameter_values(self, db_map, ids=())

Returns relationship parameter values from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_parameter_values(self, db_map, ids=())

Returns both object and relationship parameter values.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_parameter_value_lists(self, db_map, ids=())

Returns parameter_value lists from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

get_parameter_tags(self, db_map, ids=())

Get parameter tags from database.

Parameters:db_map (DiffDatabaseMapping) – Returns:dictionary items Return type:list

import_data(self, db_map_data, command_text='Import data')

Imports the given data into given db maps using the dedicated import functions from spinedb_api. Condenses all in a single command for undo/redo.

Parameters:

• db_map_data (dict(DiffDatabaseMapping, list)) – Maps dbs to data to be passed as keyword arguments to get_data_for_import
• command_text (str, optional) – What to call the command that condenses the operation.

add_or_update_items(self, db_map_data, method_name, get_method_name, signal_name)

Adds or updates items in db.

Parameters:

• db_map_data (dict) – lists of items to add or update keyed by DiffDatabaseMapping
• method_name (str) – attribute of DiffDatabaseMapping to call for performing the operation
• get_method_name (str) – attribute of SpineDBManager to call for getting affected items
• signal_name (str) – signal attribute of SpineDBManager to emit if successful

add_alternatives(self, db_map_data)

Adds alternatives to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_scenarios(self, db_map_data)

Adds scenarios to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_object_classes(self, db_map_data)

Adds object classes to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_objects(self, db_map_data)

Adds objects to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_relationship_classes(self, db_map_data)

Adds relationship classes to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_relationships(self, db_map_data)

Adds relationships to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_object_groups(self, db_map_data)

Adds object groups to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_entity_groups(self, db_map_data)

Adds entity groups to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_parameter_definitions(self, db_map_data)

Adds parameter definitions to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_parameter_values(self, db_map_data)

Adds parameter values to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_checked_parameter_values(self, db_map_data)

Adds parameter values in db without checking integrity.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_parameter_value_lists(self, db_map_data)

Adds parameter_value lists to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

add_parameter_tags(self, db_map_data)

Adds parameter tags to db.

Parameters:db_map_data (dict) – lists of items to add keyed by DiffDatabaseMapping

update_alternatives(self, db_map_data)

Updates alternatives in db.

Parameters:db_map_data (dict) – lists of items to update keyed by DiffDatabaseMapping

update_scenarios(self, db_map_data)

Updates scenarios in db.

Parameters:db_map_data (dict) – lists of items to update keyed by DiffDatabaseMapping

update_object_classes(self, db_map_data)

Updates object classes in db.

Parameters:db_map_data (dict) – lists of items to update keyed by DiffDatabaseMapping

update_objects(self, db_map_data)

Updates objects in db.

Parameters:db_map_data (dict) – lists of items to update keyed by DiffDatabaseMapping

update_relationship_classes(self, db_map_data)

Updates relationship classes in db.

Parameters:db_map_data (dict) – lists of items to update keyed by DiffDatabaseMapping

update_relationships(self, db_map_data)

Updates relationships in db.

Parameters:db_map_data (dict) – lists of items to update keyed by DiffDatabaseMapping

update_parameter_definitions(self, db_map_data)

Updates parameter definitions in db.

Parameters:db_map_data (dict) – lists of items to update keyed by DiffDatabaseMapping

update_parameter_values(self, db_map_data)

Updates parameter values in db.

Parameters:db_map_data (dict) – lists of items to update keyed by DiffDatabaseMapping

update_checked_parameter_values(self, db_map_data)

Updates parameter values in db without checking integrity.

Parameters:db_map_data (dict) – lists of items to update keyed by DiffDatabaseMapping

update_expanded_parameter_values(self, db_map_data)

Updates expanded parameter values in db without checking integrity.

Parameters:db_map_data (dict) – lists of expanded items to update keyed by DiffDatabaseMapping

update_parameter_value_lists(self, db_map_data)

Updates parameter_value lists in db.

Parameters:db_map_data (dict) – lists of items to update keyed by DiffDatabaseMapping

update_parameter_tags(self, db_map_data)

Updates parameter tags in db.

Parameters:db_map_data (dict) – lists of items to update keyed by DiffDatabaseMapping

set_scenario_alternatives(self, db_map_data)

Sets scenario alternatives in db.

Parameters:db_map_data (dict) – lists of items to set keyed by DiffDatabaseMapping

set_parameter_definition_tags(self, db_map_data)

Sets parameter_definition tags in db.

Parameters:db_map_data (dict) – lists of items to set keyed by DiffDatabaseMapping

remove_items(self, db_map_typed_ids)

do_cascade_remove_items(self, db_map_typed_ids)

do_remove_items(self, db_map_typed_ids)

Removes items from database.

Parameters:db_map_typed_ids (dict) – lists of items to remove, keyed by item type (str), keyed by DiffDatabaseMapping

_pop_item(self, db_map, item_type, id_)

uncache_items(self, db_map_typed_ids)

Removes data from cache.

Parameters:db_map_typed_ids –

static db_map_ids(db_map_data)

static db_map_class_ids(db_map_data)

_refresh_scenario_alternatives(self, db_map_data)

Refreshes cached scenarios when updating scenario alternatives.

Parameters:db_map_data (dict) – lists of updated items keyed by DiffDatabaseMapping

_refresh_parameter_definitions_by_tag(self, db_map_data)

Refreshes cached parameter definitions when updating parameter tags.

Parameters:db_map_data (dict) – lists of updated items keyed by DiffDatabaseMapping

cascade_refresh_relationship_classes(self, db_map_data)

Refreshes cached relationship classes when updating object classes.

Parameters:db_map_data (dict) – lists of updated items keyed by DiffDatabaseMapping

cascade_refresh_relationships_by_object(self, db_map_data)

Refreshed cached relationships in cascade when updating objects.

Parameters:db_map_data (dict) – lists of updated items keyed by DiffDatabaseMapping

cascade_refresh_parameter_definitions(self, db_map_data)

Refreshes cached parameter definitions in cascade when updating entity classes.

Parameters:db_map_data (dict) – lists of updated items keyed by DiffDatabaseMapping

cascade_refresh_parameter_definitions_by_value_list(self, db_map_data)

Refreshes cached parameter definitions when updating parameter_value lists.

Parameters:db_map_data (dict) – lists of updated items keyed by DiffDatabaseMapping

cascade_refresh_parameter_values_by_entity_class(self, db_map_data)

Refreshes cached parameter values in cascade when updating entity classes.

Parameters:db_map_data (dict) – lists of updated items keyed by DiffDatabaseMapping

cascade_refresh_parameter_values_by_entity(self, db_map_data)

Refreshes cached parameter values in cascade when updating entities.

Parameters:db_map_data (dict) – lists of updated items keyed by DiffDatabaseMapping

cascade_refresh_parameter_values_by_alternative(self, db_map_data)

Refreshes cached parameter values in cascade when updating alternatives.

Parameters:db_map_data (dict) – lists of updated items keyed by DiffDatabaseMapping

cascade_refresh_parameter_values_by_definition(self, db_map_data)

Refreshes cached parameter values in cascade when updating parameter definitions.

Parameters:db_map_data (dict) – lists of updated items keyed by DiffDatabaseMapping

cascade_refresh_parameter_definitions_by_tag(self, db_map_data)

Refreshes cached parameter definitions when updating parameter tags.

Parameters:db_map_data (dict) – lists of updated items keyed by DiffDatabaseMapping

find_cascading_relationship_classes(self, db_map_ids)

Finds and returns cascading relationship classes for the given object_class ids.

find_cascading_entities(self, db_map_ids, item_type)

Finds and returns cascading entities for the given entity_class ids.

find_cascading_relationships(self, db_map_ids)

Finds and returns cascading relationships for the given object ids.

find_cascading_parameter_data(self, db_map_ids, item_type)

Finds and returns cascading parameter definitions or values for the given entity_class ids.

find_cascading_parameter_definitions_by_value_list(self, db_map_ids)

Finds and returns cascading parameter definitions for the given parameter_value_list ids.

find_cascading_parameter_definitions_by_tag(self, db_map_ids)

Finds and returns cascading parameter definitions for the given parameter_tag ids.

find_cascading_parameter_values_by_entity(self, db_map_ids)

Finds and returns cascading parameter values for the given entity ids.

find_cascading_parameter_values_by_definition(self, db_map_ids)

Finds and returns cascading parameter values for the given parameter_definition ids.

find_groups_by_entity(self, db_map_ids)

Finds and returns groups for the given entity ids.

find_groups_by_member(self, db_map_ids)

Finds and returns groups for the given entity ids.

find_cascading_parameter_values_by_alternative(self, db_map_ids)

Finds and returns cascading parameter values for the given parameter alternative ids.

find_cascading_alternative_scenarios_by_alternative(self, db_map_ids)

Finds and returns cascading parameter values for the given parameter alternative ids.

find_cascading_alternative_scenarios_by_scenario(self, db_map_ids)

Finds and returns cascading parameter values for the given parameter alternative ids.