spinedb_api.db_mapping_base

Module Contents

Classes

Status	Mapped item status.
DatabaseMappingBase	An in-memory mapping of a DB, mapping item types (table names), to numeric ids, to items.
MappedItemBase	A dictionary that represents a db item.

class spinedb_api.db_mapping_base.Status

Bases: enum.Enum

Mapped item status.

class spinedb_api.db_mapping_base.DatabaseMappingBase

An in-memory mapping of a DB, mapping item types (table names), to numeric ids, to items.

This class is not meant to be used directly. Instead, you should subclass it to fit your particular DB schema.

When subclassing, you need to implement item_types(), item_factory(), _make_sq(), and _query_commit_count().

reset(*item_types)

Resets the mapping for given item types as if nothing was fetched from the DB or modified in the mapping. Any modifications in the mapping that aren’t committed to the DB are lost after this.

reset_purging()

Resets purging status for all item types.

Fetching items of an item type that has been purged will automatically mark those items removed. Resetting the purge status lets fetched items to be added unmodified.

do_fetch_more(item_type, offset=0, limit=None, **kwargs)

Fetches items from the DB and adds them to the mapping.

Parameters:

item_type (str)

Returns:

items fetched from the DB.

Return type:

list(MappedItem)

do_fetch_all(item_type, commit_count=None)

Fetches all items of given type, but only once for each commit_count. In other words, the second time this method is called with the same commit_count, it does nothing. If not specified, commit_count defaults to the result of self._get_commit_count().

Parameters:

• item_type (str)

• commit_count (int,optional)

class spinedb_api.db_mapping_base.MappedItemBase(db_map, item_type, **kwargs)

Bases: dict

A dictionary that represents a db item.

Parameters:

db_map (DatabaseMappingBase) – the DB where this item belongs.

property status

Returns the status of this item.

Returns:

Status

property backup

Returns the committed version of this item.

Returns:

dict or None

property removed

Returns whether or not this item has been removed.

Returns:

bool

property item_type

Returns this item’s type

Returns:

str

property key

Returns a tuple (item_type, id) for convenience, or None if this item doesn’t yet have an id. TODO: When does the latter happen?

Returns:

tuple(str,int) or None

fields

A dictionary mapping fields to a another dict mapping “type” to a Python type, “value” to a description of the value for the key, and “optional” to a bool.

handle_refetch()

Called when an equivalent item is fetched from the DB.

1. If this item is compromised, then mark it as committed.

2. If this item is committed, then assume the one from the DB is newer and reset the state. Otherwise assume this is newer and do nothing.

handle_refresh()

Called when the mapping is refreshed.

If this item is committed, then set it as compromised.

classmethod ref_types()

Returns a set of item types that this class refers.

Returns:

set(str)

invalidate_id()

Sets id as invalid.

merge(other)

Merges this item with another and returns the merged item together with any errors. Used for updating items.

Parameters:

other (dict) – the item to merge into this.

Returns:

merged item. str: error description if any.

Return type:

dict

db_equivalent()

The equivalent of this item in the DB.

Returns:

MappedItemBase

first_invalid_key()

Goes through the _references class attribute and returns the key of the first reference that cannot be resolved.

Returns:

unresolved reference’s key if any.

Return type:

str or None

unique_key_values(skip_keys=())

Yields tuples of unique keys and their values.

Parameters:

skip_keys – Don’t yield these keys

Yields:

tuple(tuple,tuple) – the first element is the unique key, the second is the values.

resolve_internal_fields(skip_keys=())

Goes through the _internal_fields class attribute and updates this item by resolving those references. Returns any error.

Parameters:

skip_keys (tuple) – don’t resolve references for these keys.

Returns:

error description if any.

Return type:

str or None

polish()

Polishes this item once all it’s references have been resolved. Returns any error.

The base implementation sets defaults but subclasses can do more work if needed.

Returns:

error description if any.

Return type:

str or None

check_mutability()

Called before adding, updating, or removing this item. Returns any errors that prevent that.

Returns:

error description if any.

Return type:

str or None

is_valid()

Checks if this item has all its references. Removes the item from the in-memory mapping if not valid by calling cascade_remove.

Returns:

bool

validate()

Resolves all references and checks if the item is valid. The item is valid if it’s not removed, has all of its references, and none of them is removed.

add_referrer(referrer)

Adds a strong referrer to this item. Strong referrers are removed, updated and restored in cascade with this item.

Parameters:

referrer (MappedItemBase)

remove_referrer(referrer)

Removes a strong referrer.

Parameters:

referrer (MappedItemBase)

add_weak_referrer(referrer)

Adds a weak referrer to this item. Weak referrers’ update callbacks are called whenever this item changes.

Parameters:

referrer (MappedItemBase)

cascade_restore(source=None)

Restores this item (if removed) and all its referrers in cascade. Also, updates items’ status and calls their restore callbacks.

cascade_remove(source=None)

Removes this item and all its referrers in cascade. Also, updates items’ status and calls their remove callbacks.

cascade_update()

Updates this item and all its referrers in cascade. Also, calls items’ update callbacks.

cascade_add_unique()

Adds item and all its referrers unique keys and ids in cascade.

cascade_remove_unique()

Removes item and all its referrers unique keys and ids in cascade.

is_committed()

Returns whether or not this item is committed to the DB.

Returns:

bool

commit(commit_id)

Sets this item as committed with the given commit id.

get(key, default=None)

Overridden to return references.

update(other)

Overridden to update the item status and also to invalidate references that become obsolete.

force_id(id_)

Makes sure this item’s has the given id_, corresponding to the new id of the item in the DB after some external changes.

Parameters:

id (int) – The most recent id_ of the item as fetched from the DB.

handle_id_steal()

Called when a new item is fetched from the DB with this item’s id.