spinetoolbox.spine_db_manager

The SpineDBManager class.

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, parent, synchronous=False)

Bases: PySide6.QtCore.QObject

Class to manage DBs within a project.

Parameters

• settings (QSettings) – Toolbox settings

• parent (QObject, optional) – parent object

• synchronous (bool) – If True, fetch database synchronously

property db_maps

property db_urls

error_msg

items_added

Emitted whenever items are added to a DB.

Parameters

• str – item type, such as “object_class”

• dict – mapping DatabaseMapping to list of added dict-items.

items_updated

Emitted whenever items are updated in a DB.

Parameters

• str – item type, such as “object_class”

• dict – mapping DatabaseMapping to list of updated dict-items.

items_removed

Emitted whenever items are removed from a DB.

Parameters

• str – item type, such as “object_class”

• dict – mapping DatabaseMapping to list of updated dict-items.

_connect_signals()

receive_error_msg(db_map_error_log)

receive_session_refreshed(db_maps)

receive_session_committed(db_maps, cookie)

receive_session_rolled_back(db_maps)

_get_worker(db_map)

Returns a worker.

Parameters

db_map (DatabaseMapping) – database mapping

Returns

worker for the db_map

Return type

SpineDBWorker

register_fetch_parent(db_map, parent)

Registers a fetch parent.

Parameters

• db_map (DatabaseMapping) – target database mapping

• parent (FetchParent) – fetch parent

can_fetch_more(db_map, parent)

Whether or not we can fetch more items of given type from given db.

Parameters

• db_map (DatabaseMapping) –

• parent (FetchParent) – The object that requests the fetching and that might want to react to further DB modifications.

Returns

bool

fetch_more(db_map, parent)

Fetches more items of given type from given db.

Parameters

• db_map (DatabaseMapping) –

• parent (FetchParent) – The object that requests the fetching.

get_icon_mngr(db_map)

Returns an icon manager for given db_map.

Parameters

db_map (DatabaseMapping) –

Returns

SpineDBIconManager

update_icons(db_map, item_type, items)

Runs when items are added or updated. Setups icons.

static db_map_key(db_map)

Creates an identifier for given db_map.

Parameters

db_map (DatabaseMapping) – database mapping

Returns

identification key

Return type

int

db_map_from_key(key)

Returns database mapping that corresponds to given identification key.

Parameters

key (int) – identification key

Returns

database mapping

Return type

DatabaseMapping

Raises

KeyError – raised if database map is not found

db_map(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

DatabaseMapping

create_new_spine_database(url, logger, overwrite=False)

close_session(url)

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

Parameters

url (str) –

close_all_sessions()

Closes connections to all database mappings.

get_db_map(url, logger, ignore_version_error=False, window=False, codename=None, create=False)

Returns a DatabaseMapping 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) –

• ignore_version_error (bool, optional) –

• window (bool, optional) –

• codename (str, NoneType, optional) –

• create (bool, optional) –

Returns

DatabaseMapping, NoneType

_do_get_db_map(url, **kwargs)

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

Parameters

• url (str, URL) –

• codename (str, NoneType) –

• upgrade (bool) –

• create (bool) –

Returns

DatabaseMapping

query(db_map, sq_name)

For tests.

add_db_map_listener(db_map, listener)

Adds listener for given db_map.

remove_db_map_listener(db_map, listener)

Removes db_map from the maps listener listens to.

db_map_listeners(db_map)

register_listener(listener, *db_maps)

Register given listener for all given db_map’s signals.

Parameters

• listener (object) –

• *db_maps –

unregister_listener(listener, *db_maps, dirty_db_maps=None, commit_dirty=False, commit_msg='')

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 –

• commit_dirty (bool) – True to commit dirty database mapping, False to roll back

• commit_msg (str) – commit message

Returns

All the db maps that failed to commit

Return type

failed_db_maps (list)

add_data_store_db_map(db_map, store)

Adds a Data Store instance under a db_map into memory

remove_data_store_db_map(db_map, store)

Removes a Data Store instance from memory

update_data_store_db_maps()

Updates the db maps of the dict that maps db_maps to Data Stores

is_dirty(db_map)

Returns True if mapping has pending changes.

Parameters

db_map (DatabaseMapping) – database mapping

Returns

True if db_map has pending changes, False otherwise

Return type

bool

dirty(*db_maps)

Filters clean mappings from given database maps.

Parameters

*db_maps – mappings to check

Returns

dirty mappings

Return type

list of DatabaseMapping

dirty_and_without_editors(listener, *db_maps)

Checks which of the given database mappings are dirty and have no editors.

Parameters

• listener (Any) – a listener object

• *db_maps – mappings to check

Returns

mappings that are dirty and don’t have editors

Return type

list of DatabaseMapping

clean_up()

refresh_session(*db_maps)

reset_session(*db_maps)

commit_session(commit_msg, *dirty_db_maps, cookie=None)

Commits the current session.

Parameters

• commit_msg (str) – commit message for all database maps

• *dirty_db_maps – dirty database maps to commit

• cookie (object, optional) – a free form identifier which will be forwarded to SpineDBWorker.commit_session

_do_commit_session(db_map, commit_msg, cookie=None)

Commits session for given db.

Parameters

• db_map (DatabaseMapping) – db map

• commit_msg (str) – commit message

• cookie (Any) – a cookie to include in receive_session_committed call

Returns

bool

notify_session_committed(cookie, *db_maps)

Notifies manager and listeners when a commit has taken place by a third party.

Parameters

• cookie (Any) – commit cookie

• *db_maps – database maps that were committed

rollback_session(*dirty_db_maps)

Rolls back the current session.

Parameters

*dirty_db_maps – dirty database maps to commit

_do_rollback_session(db_map)

Rolls back session for given db.

Parameters

db_map (DatabaseMapping) – db map

entity_class_renderer(db_map, entity_class_id, for_group=False, color=None)

Returns an icon renderer for a given entity class.

Parameters

• db_map (DatabaseMapping) – database map

• entity_class_id (int) – entity class id

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

• color (QColor, optional) – icon color

Returns

requested renderer or None if no entity class was found

Return type

QSvgRenderer

entity_class_icon(db_map, entity_class_id, for_group=False)

Returns an appropriate icon for a given entity class.

Parameters

• db_map (DatabaseMapping) – database map

• 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

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

• item_type (str) –

• id (TempId) –

Returns

the item

Return type

PublicItem

get_field(db_map, item_type, id_, field)

static get_items(db_map, item_type)

Returns a list of the items of the given type in the given db map.

Parameters

• db_map (DatabaseMapping) –

• item_type (str) –

Returns

list

get_items_by_field(db_map, item_type, field, value)

Returns a list of items of the given type in the given db map that have the given value for the given field.

Parameters

• db_map (DatabaseMapping) –

• item_type (str) –

• field (str) –

• value –

Returns

list

get_item_by_field(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 (DatabaseMapping) –

• item_type (str) –

• field (str) –

• value –

Returns

dict

static display_data_from_parsed(parsed_data)

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

static tool_tip_data_from_parsed(parsed_data)

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

_format_list_value(db_map, item_type, value, list_value_id)

get_value(db_map, item, role=Qt.ItemDataRole.DisplayRole)

Returns the value or default value of a parameter.

Parameters

• db_map (DatabaseMapping) – database mapping

• item (PublicItem) – parameter value item, parameter definition item, or list value item

• role (Qt.ItemDataRole) – data role

Returns

any

get_value_from_data(data, role=Qt.ItemDataRole.DisplayRole)

Returns the value or default value of a parameter directly from data. Used by EmptyParameterModel.data().

Parameters

• data (str) – joined value and type

• role (int, optional) –

Returns

any

static _parse_value(db_value, type_=None)

_format_value(parsed_value, role=Qt.ItemDataRole.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(db_map, item_type, id_)

Returns the value or default value indexes of a parameter.

Parameters

• db_map (DatabaseMapping) –

• item_type (str) – either “parameter_definition” or “parameter_value”

• id (int) – The parameter_value or definition id

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

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

Parameters

• db_map (DatabaseMapping) –

• 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) –

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

Returns one value item of a parameter_value_list.

Parameters

• db_map (DatabaseMapping) –

• id (int) – The parameter_value_list id

• index (int) – The value item index

• role (int, optional) –

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

Returns a parameter_value_list formatted for the given role.

Parameters

• db_map (DatabaseMapping) –

• id (int) – The parameter_value_list id

• role (int, optional) –

get_scenario_alternative_id_list(db_map, scen_id)

import_data(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(DatabaseMapping, 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_alternatives(db_map_data)

Adds alternatives to db.

Parameters

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

add_scenarios(db_map_data)

Adds scenarios to db.

Parameters

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

add_entity_classes(db_map_data)

Adds entity classes to db.

Parameters

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

add_entities(db_map_data)

Adds entities to db.

Parameters

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

add_entity_groups(db_map_data)

Adds entity groups to db.

Parameters

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

add_entity_alternatives(db_map_data)

Adds entity alternatives to db.

Parameters

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

add_parameter_definitions(db_map_data)

Adds parameter definitions to db.

Parameters

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

add_parameter_values(db_map_data)

Adds parameter values to db without checking integrity.

Parameters

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

add_parameter_value_lists(db_map_data)

Adds parameter_value lists to db.

Parameters

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

add_list_values(db_map_data)

Adds parameter_value list values to db.

Parameters

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

add_metadata(db_map_data)

Adds metadata to db.

Parameters

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

add_entity_metadata(db_map_data)

Adds entity metadata to db.

Parameters

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

add_parameter_value_metadata(db_map_data)

Adds parameter value metadata to db.

Parameters

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

_add_ext_item_metadata(db_map_data, item_type)

add_ext_entity_metadata(db_map_data)

Adds entity metadata together with all necessary metadata to db.

Parameters

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

add_ext_parameter_value_metadata(db_map_data)

Adds parameter value metadata together with all necessary metadata to db.

Parameters

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

update_alternatives(db_map_data)

Updates alternatives in db.

Parameters

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

update_scenarios(db_map_data)

Updates scenarios in db.

Parameters

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

update_entity_classes(db_map_data)

Updates entity classes in db.

Parameters

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

update_entities(db_map_data)

Updates entities in db.

Parameters

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

update_entity_alternatives(db_map_data)

Updates entity alternatives in db.

Parameters

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

update_parameter_definitions(db_map_data)

Updates parameter definitions in db.

Parameters

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

update_parameter_values(db_map_data)

Updates parameter values in db.

Parameters

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

update_expanded_parameter_values(db_map_data)

Updates expanded parameter values in db.

Parameters

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

update_parameter_value_lists(db_map_data)

Updates parameter_value lists in db.

Parameters

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

update_list_values(db_map_data)

Updates parameter_value list values in db.

Parameters

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

update_metadata(db_map_data)

Updates metadata in db.

Parameters

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

update_entity_metadata(db_map_data)

Updates entity metadata in db.

Parameters

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

update_parameter_value_metadata(db_map_data)

Updates parameter value metadata in db.

Parameters

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

_update_ext_item_metadata(db_map_data, item_type)

update_ext_entity_metadata(db_map_data)

Updates entity metadata in db.

Parameters

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

update_ext_parameter_value_metadata(db_map_data)

Updates parameter value metadata in db.

Parameters

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

set_scenario_alternatives(db_map_data)

Sets scenario alternatives in db.

Parameters

db_map_data (dict) – lists of items to set keyed by DatabaseMapping

static get_data_to_set_scenario_alternatives(db_map, scenarios)

Returns data to add and remove, in order to set wide scenario alternatives.

Parameters

• db_map (DatabaseMapping) – the db_map

• scenarios –

  One or more wide scenario dict objects to set. Each item must include the following keys:

  • ”id”: integer scenario id

  • ”alternative_id_list”: list of alternative ids for that scenario

Returns

list: scenario_alternative dict objects to add. set: integer scenario_alternative ids to remove

purge_items(db_map_item_types, **kwargs)

Purges selected items from given database.

Parameters

• db_map_item_types (dict) – mapping from database map to list of purgable item types

• **kwargs – keyword arguments passed to remove_items()

add_items(item_type, db_map_data, identifier=None, **kwargs)

Pushes commands to add items to undo stack.

update_items(item_type, db_map_data, identifier=None, **kwargs)

Pushes commands to update items to undo stack.

add_update_items(item_type, db_map_data, identifier=None, **kwargs)

Pushes commands to add_update items to undo stack.

remove_items(db_map_typed_ids, identifier=None, **kwargs)

Pushes commands to remove items to undo stack.

get_command_identifier()

do_add_items(db_map, item_type, data, check=True)

do_update_items(db_map, item_type, data, check=True)

do_add_update_items(db_map, item_type, data, check=True)

do_remove_items(db_map, item_type, ids, check=True)

Removes items from database.

Parameters

• db_map – DatabaseMapping instance

• item_type (str) – database item type

• ids (set) – ids to remove

do_restore_items(db_map, item_type, ids)

Restores items in database.

Parameters

• db_map – DatabaseMapping instance

• item_type (str) – database item type

• ids (set) – ids to restore

static db_map_ids(db_map_data)

static db_map_class_ids(db_map_data)

find_cascading_entity_classes(db_map_ids)

Finds and returns cascading entity classes for the given dimension ids.

find_cascading_entities(db_map_ids)

Finds and returns cascading entities for the given element ids.

find_cascading_parameter_data(db_map_ids, item_type)

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

find_cascading_parameter_values_by_entity(db_map_ids)

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

find_cascading_parameter_values_by_definition(db_map_ids)

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

find_cascading_scenario_alternatives_by_scenario(db_map_ids)

Finds and returns cascading scenario alternatives for the given scenario ids.

find_groups_by_entity(db_map_ids)

Finds and returns groups for the given entity ids.

duplicate_scenario(scen_data, dup_name, db_map)

duplicate_entity(orig_name, dup_name, class_name, db_maps)

Duplicates entity, its parameter values and related multidimensional entities.

Parameters

• orig_name (str) – original entity’s name

• dup_name (str) – duplicate’s name

• class_name (str) – entity class name

• db_maps (Iterable of DatabaseMapping) – database mappings where duplication should take place

_get_data_for_export(db_map_item_ids)

export_data(caller, db_map_item_ids, file_path, file_filter)

_is_url_available(url, logger)

export_to_sqlite(file_path, data_for_export, caller)

Exports given data into SQLite file.

static export_to_json(file_path, data_for_export, caller)

Exports given data into JSON file.

static export_to_excel(file_path, data_for_export, caller)

Exports given data into Excel file.

get_items_for_commit(db_map, commit_id)

static get_all_multi_spine_db_editors()

Yields all instances of MultiSpineDBEditor currently open.

Yields

MultiSpineDBEditor

get_all_spine_db_editors()

Yields all instances of SpineDBEditor currently open.

Yields

SpineDBEditor

_get_existing_spine_db_editor(db_url_codenames)

open_db_editor(db_url_codenames, reuse_existing_editor)

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

• reuse_existing_editor (bool) – if True and the same URL is already open, just raise the existing window