spinetoolbox.spine_db_manager

The SpineDBManager class

authors

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

date

2.10.2019

Module Contents

Classes

SpineDBManagerBase	Class to manage DBs within a project.
MiniSpineDBManager	Class to manage DBs within a project.
SpineDBManager	Class to manage DBs within a project.

Functions

do_create_new_spine_database(url)	Creates a new spine database at the given url.
_grouper(iterable, n)

spinetoolbox.spine_db_manager.do_create_new_spine_database(url)

Creates a new spine database at the given url.

spinetoolbox.spine_db_manager._grouper(iterable, n)

class spinetoolbox.spine_db_manager.SpineDBManagerBase(parent, cache, icon_mngr)

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

parent (QObject, optional) – parent object

error_msg

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

features_added

tools_added

tool_features_added

tool_feature_methods_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

features_removed

tools_removed

tool_features_removed

tool_feature_methods_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

features_updated

tools_updated

tool_features_updated

tool_feature_methods_updated

items_removed_from_cache

scenario_alternatives_added

scenario_alternatives_updated

scenario_alternatives_removed

parameter_definition_tags_added

parameter_definition_tags_removed

data_imported

_GROUP_SEP =  ǀ

connect_signals(self)

Connects signals.

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

get_icon_mngr(self, db_map)

Returns an icon manager for given db_map.

Parameters

db_map (DiffDatabaseMapping) –

Returns

SpineDBIconManager

update_icons(self, db_map_data)

Runs when object classes are added or updated. Setups icons for those classes.

Parameters

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

class spinetoolbox.spine_db_manager.MiniSpineDBManager(parent, cache, icon_mngr)

Bases: SpineDBManagerBase

Class to manage DBs within a project.

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

Initializes the instance.

Parameters

parent (QObject, optional) – parent object

class spinetoolbox.spine_db_manager.SpineDBManager(settings, parent)

Bases: SpineDBManagerBase

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

• parent (QObject, optional) – parent object

property thread(self)

property db_maps(self)

db_map(self, url)

Returns a database mapping for given URL.

Parameters

url (str) – a database URL

Returns

a database map or None if not found

Return type

DiffDatabaseMapping

is_url_available(self, url, logger)

create_new_spine_database(self, url, logger)

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.

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

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 (LoggerInterface) –

• codename (str, NoneType, optional) –

• upgrade (bool, optional) –

• create (bool, optional) –

Returns

DiffDatabaseMapping, NoneType

_do_get_db_map(self, url, codename, upgrade, create)

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

Parameters

• url (str, URL) –

• codename (str, NoneType) –

• upgrade (bool) –

• create (bool) –

Returns

DiffDatabaseMapping

register_listener(self, listener, *db_maps)

Register given listener for all given db_map’s signals.

Parameters

• listener (object) –

• db_maps (DiffDatabaseMapping) –

unregister_listener(self, listener, *db_maps)

Unregisters given listener from given db_map signals. If any of the db_maps becomes an orphan and is dirty, prompts user to commit or rollback.

Parameters

• listener (object) –

• db_maps (DiffDatabaseMapping) –

Returns

True if operation was successful, False otherwise

Return type

bool

_prompt_to_commit_changes(self)

Prompts the user to commit or rollback changes to ‘dirty’ db maps.

Returns

True to commit, False to rollback, None to do nothing

Return type

bool

get_fetcher(self)

Returns a fetcher.

Returns

SpineDBFetcher

fetch_next(self)

Starts the next fetcher in line.

_handle_fetcher_finished(self)

Cleans up things after fetcher has finished working.

clean_up(self)

refresh_session(self, *db_maps)

commit_session(self, *db_maps, cookie=None)

Commits the current session.

Parameters

• *db_maps – database maps to commit

• cookie (object, optional) – a free form identifier which will be forwarded to session_committed signal

static _get_commit_msg(db_names)

rollback_session(self, *db_maps)

static _get_rollback_confirmation(db_names)

connect_signals(self)

Connects signals.

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

Returns an icon renderer for a given entity class.

Parameters

• db_map (DiffDatabaseMapping) – database map

• entity_type (str) – either ‘object_class’ or ‘relationship_class’

• entity_class_id (int) – entity class’ id

• for_group (bool) – if True, return the group object icon instead

Returns

requested renderer or None if no entity class was found

Return type

QSvgRenderer

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) – database map

• entity_type (str) – either ‘object_class’ or ‘relationship_class’

• entity_class_id (int) – entity class’ id

• for_group (bool) – if True, return the group object icon instead

Returns

requested icon or None if no entity class was found

Return type

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

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_from_parsed(parsed_data)

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

static tool_tip_data_from_parsed(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) –

get_scenario_alternative_id_list(self, db_map, scen_id)

static get_db_items(query, chunk_size=1000)

Runs the given query and yields results by chunks of given size.

Yields

generator(list)

static _make_query(db_map, sq_name, ids=(), key=('id'))

Makes a database query

Parameters

• db_map (DatabaseMappingBase) – database map

• sq_name (str) – name of the subquery

• ids (Iterable of int) – ids by which the query should be filtered

Returns

database subquery

Return type

Alias

get_alternatives(self, db_map, ids=())

Returns alternatives from database.

Parameters

• db_map (DatabaseMappingBase) – database map

• ids (Iterable of int) – ids by which the alternatives should be filtered

Yields

list – dictionary items

get_scenarios(self, db_map, ids=())

Returns scenarios from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_scenario_alternatives(self, db_map, ids=())

Returns scenario alternatives from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_object_classes(self, db_map, ids=())

Returns object classes from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_objects(self, db_map, ids=())

Returns objects from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_relationship_classes(self, db_map, ids=())

Returns relationship classes from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_relationships(self, db_map, ids=())

Returns relationships from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_entity_groups(self, db_map, ids=())

Returns entity groups from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_object_parameter_definitions(self, db_map, ids=())

Returns object parameter definitions from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_relationship_parameter_definitions(self, db_map, ids=())

Returns relationship parameter definitions from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_parameter_definitions(self, db_map, ids=())

Returns both object and relationship parameter definitions.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_parameter_definition_tags(self, db_map, ids=())

Returns parameter definition tags.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_object_parameter_values(self, db_map, ids=())

Returns object parameter values from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_relationship_parameter_values(self, db_map, ids=())

Returns relationship parameter values from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_parameter_values(self, db_map, ids=())

Returns both object and relationship parameter values.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_parameter_value_lists(self, db_map, ids=())

Returns parameter_value lists from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_parameter_tags(self, db_map, ids=())

Get parameter tags from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_features(self, db_map, ids=())

Returns features from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_tools(self, db_map, ids=())

Get tools from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_tool_features(self, db_map, ids=())

Returns tool features from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

get_tool_feature_methods(self, db_map, ids=())

Returns tool feature methods from database.

Parameters

db_map (DiffDatabaseMapping) –

Yields

list – dictionary items

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, dict())) – 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)

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 without checking integrity.

Parameters

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

check_add_parameter_values(self, db_map_data)

Adds parameter values in db with 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

add_features(self, db_map_data)

Adds features to db.

Parameters

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

add_tools(self, db_map_data)

Adds tools to db.

Parameters

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

add_tool_features(self, db_map_data)

Adds tool features to db.

Parameters

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

add_tool_feature_methods(self, db_map_data)

Adds tool feature methods 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 without checking integrity.

Parameters

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

check_update_parameter_values(self, db_map_data)

Updates parameter values in db with 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

update_features(self, db_map_data)

Updates features in db.

Parameters

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

update_tools(self, db_map_data)

Updates tools in db.

Parameters

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

update_tool_features(self, db_map_data)

Updates tools features in db.

Parameters

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

update_tool_feature_methods(self, db_map_data)

Updates tools feature methods 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_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)

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 alternative ids.

find_cascading_scenario_alternatives_by_alternative(self, db_map_ids)

Finds and returns cascading scenario_alternatives for the given alternative ids.

find_cascading_scenario_alternatives_by_scenario(self, db_map_ids)

Finds and returns cascading scenario_alternatives for the given scenario ids.

find_cascading_features_by_parameter_definition(self, db_map_ids)

Finds and returns cascading features for the given parameter definition ids.

find_cascading_features_by_parameter_value_list(self, db_map_ids)

Finds and returns cascading features for the given parameter value list ids.

find_cascading_tool_features_by_feature(self, db_map_ids)

Finds and returns cascading tool features for the given feature ids.

export_data(self, caller, db_map_item_ids, file_path, file_filter)

duplicate_object(self, db_maps, object_data, orig_name, dup_name)

get_all_multi_spine_db_editors(self)

Yields all instances of MultiSpineDBEditor currently open.

Returns

Generator

get_all_spine_db_editors(self)

Yields all instances of SpineDBEditor currently open.

Returns

Generator

_get_existing_spine_db_editor(self, db_url_codenames)

open_db_editor(self, db_url_codenames)

Opens a SpineDBEditor with given urls. Uses an existing MultiSpineDBEditor if any. Also, if the same urls are open in an existing SpineDBEditor, just raises that one instead of creating another.

Parameters

db_url_codenames (dict) – mapping url to codename