F merge conflict error

Summary

Precondition for https://gitlab.indiscale.com/caosdb/customers/leibniz-zmt/management/-/issues/133. Introduces an EntityMergeConflictError class that's raised in case of merge conflicts in apiutils.merge_entities.

Focus

New error class in apiutils.

Test Environment

unittest should be sufficient.

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related issues
• Up-to-date CHANGELOG.md (or not necessary)
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md (or not necessary)
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there specifications? Are they satisfied?

For further good practices have a look at our review guidelines.

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,13 @@ 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
+    two entities.
+    """
 
 
 def new_record(record_type, name=None, description=None,
@@ -365,14 +371,15 @@ def empty_diff(old_entity: Entity, new_entity: Entity, compare_referenced_record
     return True
 
 
-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.
+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.
 
-    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 to inform about 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,9 @@ 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}:\n"
+                    f"A: {sa_a}\nB: {sa_b}")
     return entity_a