linkahead.apiutils module

API-Utils: Some simplified functions for generation of records etc.

exception linkahead.apiutils.EntityMergeConflictError(msg)

Bases: LinkAheadException

An error that is raised in case of an unresolvable conflict when merging two entities.

linkahead.apiutils.apply_to_ids(entities, func)

Apply a function to all ids.

All ids means the ids of the entities themselves but also to all parents, properties and referenced entities.

Parameters:

  • entities (list of Entity)

  • func (function with one parameter.)

linkahead.apiutils.compare_entities(old_entity: Entity, new_entity: Entity, compare_referenced_records: bool = False)

Compare two entites.

Return a tuple of dictionaries, the first index belongs to additional information for old entity, the second index belongs to additional information for new entity.

Additional information means in detail: - Additional parents (a list under key “parents”) - Information about properties:

  • Each property lists either an additional property or a property with a changed: - datatype - importance or - value (not implemented yet)

    In case of changed information the value listed under the respective key shows the value that is stored in the respective entity.

If compare_referenced_records is True, also referenced entities will be compared using this function (which is then called with compare_referenced_records = False to prevent infinite recursion in case of circular references).

Parameters:

  • old_entity (Entity) – Entities to be compared

  • new_entity (Entity) – Entities to be compared

  • compare_referenced_records (bool, optional) – Whether to compare referenced records in case of both, old_entity and new_entity, have the same reference properties and both have a Record object as value. If set to False, only the corresponding Python objects are compared which may lead to unexpected behavior when identical records are stored in different objects. Default is False.

linkahead.apiutils.create_flat_list(ent_list: List[Entity], flat: List[Entity])

Recursively adds all properties contained in entities from ent_list to the output list flat. Each element will only be added once to the list.

TODO: Currently this function is also contained in newcrawler module crawl.

We are planning to permanently move it to here.

linkahead.apiutils.create_id_query(ids)
linkahead.apiutils.describe_diff(olddiff, newdiff, name=None, as_update=True)
linkahead.apiutils.empty_diff(old_entity: Entity, new_entity: Entity, compare_referenced_records: bool = False)

Check whether the compare_entities found any differences between old_entity and new_entity.

Parameters:

  • old_entity (Entity) – Entities to be compared

  • new_entity (Entity) – Entities to be compared

  • compare_referenced_records (bool, optional) – Whether to compare referenced records in case of both, old_entity and new_entity, have the same reference properties and both have a Record object as value.

linkahead.apiutils.getBranchIn(folder)
linkahead.apiutils.getCommitIn(folder)
linkahead.apiutils.getDiffIn(folder, save_dir=None)
linkahead.apiutils.getOriginUrlIn(folder)
linkahead.apiutils.get_type_of_entity_with(id_)
linkahead.apiutils.id_query(ids)
linkahead.apiutils.merge_entities(entity_a: Entity, entity_b: Entity, merge_references_with_empty_diffs=True, force=False, merge_id_with_resolved_entity: bool = False)

Merge entity_b into entity_a such that they have the same parents and properties.

datatype, unit, value, name and description will only be changed in entity_a if they are None for entity_a and set for entity_b. If there is a corresponding value for entity_a different from None, an EntityMergeConflictError will be raised to inform about an unresolvable merge conflict.

The merge operation is done in place.

Returns entity_a.

WARNING: This function is currently experimental and insufficiently tested. Use with care.

Parameters:

  • entity_a (Entity) – The entities to be merged. entity_b will be merged into entity_a in place

  • entity_b (Entity) – The entities to be merged. entity_b will be merged into entity_a in place

  • merge_references_with_empty_diffs (bool, optional) – Whether the merge is performed if entity_a and entity_b both reference record(s) that may be different Python objects but have empty diffs. If set to False a merge conflict will be raised in this case instead. Default is True.

  • force (bool, optional) – If True, in case entity_a and entity_b have the same properties, the values of entity_a are replaced by those of entity_b in the merge. If False, an EntityMergeConflictError is raised instead. Default is False.

  • merge_id_with_resolved_entity (bool, optional) – If true, the values of two reference properties will be considered the same if one is an integer id and the other is a db.Entity with this id. I.e., a value 123 is identified with a value <Record id=123/>. Default is False.

Returns:

entity_a – The initial entity_a after the in-place merge

Return type:

Entity

Raises:

EntityMergeConflictError – In case of an unresolvable merge conflict.

linkahead.apiutils.new_record(record_type, name=None, description=None, tempid=None, insert=False, **kwargs)

Function to simplify the creation of Records.

record_type: The name of the RecordType to use for this record.

(ids should also work.)

name: Name of the new Record. kwargs: Key-value-pairs for the properties of this Record.

Returns: The newly created Record.

Of course this functions requires an open database connection!

linkahead.apiutils.resolve_reference(prop: Property)

resolves the value of a reference property

The integer value is replaced with the entity object. If the property is not a reference, then the function returns without change.

linkahead.apiutils.retrieve_entities_with_ids(entities)
linkahead.apiutils.retrieve_entity_with_id(eid)