feat(apiutils): added the possibility to use custom labels instead of 'old'...

feat(apiutils): added the possibility to use custom labels instead of 'old' and 'new' in describe_diff function

src/linkahead/apiutils.py

@@ -514,9 +514,9 @@ def merge_entities(entity_a: Entity,
 
 def describe_diff(olddiff: dict[str, Any], newdiff: dict[str, Any],
                   name: str = None,
-                  as_update=True,
-                  label_old="old version",
-                  label_new="new version"):
+                  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:
@@ -541,6 +541,16 @@ def describe_diff(olddiff: dict[str, Any], newdiff: dict[str, Any],
     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 = ""
 
@@ -548,17 +558,17 @@ def describe_diff(olddiff: dict[str, Any], newdiff: dict[str, Any],
         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())
@@ -566,18 +576,21 @@ def describe_diff(olddiff: dict[str, Any], newdiff: dict[str, Any],
         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