ENH: Add EntityMergeConflictError class

src/caosdb/apiutils.py

@@ -27,12 +27,13 @@
 Some simplified functions for generation of records etc.
 """
 
+import logging
 import sys
 import tempfile
 import warnings
+
 from collections.abc import Iterable
 from subprocess import call
-
 from typing import Optional, Any, Dict, List
 
 from caosdb.common.datatype import (BOOLEAN, DATETIME, DOUBLE, FILE, INTEGER,
@@ -40,8 +41,14 @@ from caosdb.common.datatype import (BOOLEAN, DATETIME, DOUBLE, FILE, INTEGER,
 from caosdb.common.models import (Container, Entity, File, Property, Query,
                                   Record, RecordType, execute_query,
                                   get_config, SPECIAL_ATTRIBUTES)
+from caosdb.exceptions import CaosDBException
 
-import logging
+
+class EntityMergeConflictError(CaosDBException):
+    """An error that is raised in case of an unresolvable conflict when merging
+    to entities.
+
+    """
 
 
 def new_record(record_type, name=None, description=None,
@@ -366,13 +373,13 @@ 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):
-    """
-    Merge entity_b into entity_a such that they have the same parents and properties.
+    """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 a RuntimeError will be raised informing of an
-    unresolvable merge conflict.
+    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 informing of an unresolvable merge
+    conflict.
 
     The merge operation is done in place.
 
@@ -392,13 +399,18 @@ def merge_entities(entity_a: Entity, entity_b: Entity, merge_references_with_emp
     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`, a RuntimeError is raised instead. Default is False.
+       If `False`, an EntityMergeConflictError is raised instead. Default is False.
 
     Returns
     -------
     entity_a : Entity
        The initial entity_a after the in-place merge
 
+    Raises
+    ------
+    EntityMergeConflictError
+        In case of an unresolvable merge conflict.
+
     """
 
     logging.warning(
@@ -433,8 +445,8 @@ 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 RuntimeError(
-                            f"Merge conflict:\nEntity a ({entity_a.id}, {entity_a.name}) "
+                        raise EntityMergeConflictError(
+                            f"Entity a ({entity_a.id}, {entity_a.name}) "
                             f"has a Property '{key}' with {attribute}="
                             f"{diff_r2['properties'][key][attribute]}\n"
                             f"Entity b ({entity_b.id}, {entity_b.name}) "
@@ -463,7 +475,8 @@ def merge_entities(entity_a: Entity, entity_b: Entity, merge_references_with_emp
                 # force overwrite
                 setattr(entity_a, special_attribute, sa_b)
             else:
-                raise RuntimeError("Merge conflict.")
+                raise EntityMergeConflictError(
+                    f"Conflict in special attribute {special_attribute}.")
     return entity_a