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.
- linkahead.apiutils.compare_entities(old_entity: Entity, new_entity: Entity, compare_referenced_records: bool = False) tuple[dict[str, Any], dict[str, Any]]
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.describe_diff(olddiff, newdiff, name=None, as_update=True)
- linkahead.apiutils.empty_diff(old_entity: Entity, new_entity: Entity, compare_referenced_records: bool = False) bool
Check whether the compare_entities found any differences between old_entity and new_entity.
- Parameters:
- linkahead.apiutils.getBranchIn(folder)
- linkahead.apiutils.getCommitIn(folder)
- linkahead.apiutils.getDiffIn(folder, save_dir=None)
- linkahead.apiutils.getOriginUrlIn(folder)
- 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) Entity
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:
- Raises:
EntityMergeConflictError – In case of an unresolvable merge conflict.
- linkahead.apiutils.new_record(record_type: str, name: str | None = None, description: str | None = None, tempid: int | None = None, insert: bool = False, **kwargs) Record
Function to simplify the creation of Records.
record_type: The name of the RecordType to use for this record. 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!