Added the possibility to use custom labels instead of 'old' and 'new'

Summary

This is related to: caosdb-advanced-user-tools#77 (moved)

It introduces two arguments for describe_diff that allow setting custom labels instead of 'old' and 'new' in the difference string representation.

Furthermore, I added docstrings and type hints.

Test Environment

I have added a unit test to test the function (specifically the new feature).

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)
• Up-to-date JSON schema (or not necessary)
• Appropriate user and developer documentation (or not necessary)
  • How do I use the software? Assume "stupid" users.
  • How do I develop or debug the software? Assume novice developers.
• 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)
• Appropriate user and developer documentation (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/linkahead/apiutils.py

@@ -512,24 +512,63 @@ def merge_entities(entity_a: Entity,
     return entity_a
 
 
-def describe_diff(olddiff, newdiff, name=None, as_update=True):
+def describe_diff(olddiff: dict[str, Any], newdiff: dict[str, Any],
+                  name: str = None,
+                  as_update: bool = True,
+                  label_old: str = "old version",
+                  label_new: str = "new version") -> str:
+    """
+    Generate a textual description of the differences between two entities.
+    These can be generated using :func:`compare_entities` and used within this function like this:
+
+    `describe_diff(*compare_entities(...))`
+
+    Arguments:
+    ----------
+
+    olddiff: dict[str, Any]
+      First element of the tuple output of :func:`compare_entities`.
+      This is referred to as the "old" version.
+
+    newdiff: dict[str, Any]
+      Second element of the tuple output of :func:`compare_entities`.
+      This is referred to as the "new" version.
+
+
+    name: str
+      Default None. Name of the entity that will be shown in the output text.
+
+    as_update: bool
+      Default True. Not used anymore.
+
+    label_old: str
+      Can be used to set a custom label for the diff that is associated with the old entity.
+
+    label_new: str
+      Can be used to set a custom label for the diff that is associated with the new entity.
+
+    Returns:
+    --------
+    A text description of the differences.
+
+    """
     description = ""
 
     for attr in list(set(list(olddiff.keys()) + list(newdiff.keys()))):
         if attr == "parents" or attr == "properties":
             continue
         description += "{} differs:\n".format(attr)
-        description += "old version: {}\n".format(
+        description += label_old + ": {}\n".format(
             olddiff[attr] if attr in olddiff else "not set")
-        description += "new version: {}\n\n".format(
+        description += label_new + ": {}\n\n".format(
             newdiff[attr] if attr in newdiff else "not set")
 
     if len(olddiff["parents"]) > 0:
-        description += ("Parents that are only in the old version:\n"
+        description += ("Parents that are only in the " + label_old + ":\n"
                         + ", ".join(olddiff["parents"]) + "\n")
 
     if len(newdiff["parents"]) > 0:
-        description += ("Parents that are only in the new version:\n"
+        description += ("Parents that are only in the " + label_new + ":\n"
                         + ", ".join(olddiff["parents"]) + "\n")
 
     for prop in list(set(list(olddiff["properties"].keys())
@@ -537,18 +576,21 @@ def describe_diff(olddiff, newdiff, name=None, as_update=True):
         description += "property {} differs:\n".format(prop)
 
         if prop not in olddiff["properties"]:
-            description += "it does not exist in the old version: \n"
+            description += "it does not exist in the " + label_old + ":\n"
         elif prop not in newdiff["properties"]:
-            description += "it does not exist in the new version: \n"
+            description += "it does not exist in the " + label_new + ":\n"
         else:
-            description += "old version: {}\n".format(
+            description += label_old + ": {}\n".format(
                 olddiff["properties"][prop])
-            description += "new version: {}\n\n".format(
+            description += label_new + ": {}\n\n".format(
                 newdiff["properties"][prop])
 
     if description != "":
-        description = ("## Difference between the old and the new "
-                       "version of {}\n\n".format(name))+description
+        description = ("## Difference between the " +
+                       label_old +
+                       " and the " +
+                       label_new +
+                       " of {}\n\n".format(name)) + description
 
     return description