ENH: Implement merge_id_with_entity argument

src/linkahead/apiutils.py

@@ -354,7 +354,7 @@ def empty_diff(old_entity: Entity, new_entity: Entity, compare_referenced_record
 
 
 def merge_entities(entity_a: Entity, entity_b: Entity, merge_references_with_empty_diffs=True,
-                   force=False):
+                   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
@@ -380,8 +380,14 @@ def merge_entities(entity_a: Entity, entity_b: Entity, merge_references_with_emp
         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.
+        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
     -------
@@ -427,6 +433,24 @@ def merge_entities(entity_a: Entity, entity_b: Entity, merge_references_with_emp
                         setattr(entity_a.get_property(key), attribute,
                                 diff_r2["properties"][key][attribute])
                     else:
+                        raise_error = True
+                        if merge_id_with_resolved_entity is True and attribute == "value":
+                            # Do a special check for the case of an id value on the
+                            # one hand, and a resolved entity on the other side.
+                            this = entity_a.get_property(key).value
+                            that = entity_b.get_property(key).value
+                            same = False
+                            if isinstance(this, list) and isinstance(that, list):
+                                if len(this) == len(that):
+                                    same = all([_same_id_as_resolved_entity(a, b)
+                                                for a, b in zip(this, that)])
+                            else:
+                                same = _same_id_as_resolved_entity(this, that)
+                            if same is True:
+                                setattr(entity_a.get_property(key), attribute,
+                                        diff_r2["properties"][key][attribute])
+                                raise_error = False
+                        if raise_error is True:
                             raise EntityMergeConflictError(
                                 f"Entity a ({entity_a.id}, {entity_a.name}) "
                                 f"has a Property '{key}' with {attribute}="
@@ -586,3 +610,16 @@ def create_flat_list(ent_list: List[Entity], flat: List[Entity]):
                     flat.append(p.value)
                 # TODO: move inside if block?
                 create_flat_list([p.value], flat)
+
+
+def _same_id_as_resolved_entity(this, that):
+    """Checks whether ``this`` and ``that`` either are the same or whether one
+    is an id and the other is a db.Entity with this id.
+
+    """
+    if isinstance(this, Entity) and not isinstance(that, Entity):
+        # this is an Entity with an id, that is not
+        return this.id is not None and this.id == that
+    if not isinstance(this, Entity) and isinstance(that, Entity):
+        return that.id is not None and that.id == this
+    return this == that