MAINT: deprecate old arguments

src/linkahead/apiutils.py

@@ -622,11 +622,14 @@ def merge_entities(entity_a: Entity,
     return entity_a
 
 
-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:
+def describe_diff(entity0_diff: dict[str, Any], entity1_diff: dict[str, Any],
+                  name: Optional[str] = None,
+                  as_update: Optional[bool] = None,
+                  label_e0: str = "first version",
+                  label_e1: str = "second version",
+                  olddiff: Any = None,
+                  newdiff: Any = None,
+                  ) -> 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:
@@ -636,25 +639,25 @@ def describe_diff(olddiff: dict[str, Any], newdiff: dict[str, Any],
     Arguments:
     ----------
 
-    olddiff: dict[str, Any]
+    entity0_diff: 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]
+    entity1_diff: dict[str, Any]
       Second element of the tuple output of :func:`compare_entities`.
       This is referred to as the "new" version.
 
 
-    name: str
+    name: Optional[str]
       Default None. Name of the entity that will be shown in the output text.
 
-    as_update: bool
-      Default True. Not used anymore.
+    as_update: Optional[bool]
+      Default None. Not used anymore.
 
-    label_old: str
+    label_e0: str
       Can be used to set a custom label for the diff that is associated with the old entity.
 
-    label_new: str
+    label_e1: str
       Can be used to set a custom label for the diff that is associated with the new entity.
 
     Returns:
@@ -664,42 +667,51 @@ def describe_diff(olddiff: dict[str, Any], newdiff: dict[str, Any],
     """
     description = ""
 
-    for attr in list(set(list(olddiff.keys()) + list(newdiff.keys()))):
+    if as_update:
+        warnings.warn("'as_update' is deprecated. Do not use it.", DeprecationWarning)
+    if olddiff:
+        warnings.warn("'olddiff' is deprecated. Use 'entity0_diff' instead.", DeprecationWarning)
+        entity0_diff=olddiff
+    if newdiff:
+        warnings.warn("'newdiff' is deprecated. Use 'entity1_diff' instead.", DeprecationWarning)
+        entity1_diff=newdiff
+
+    for attr in list(set(list(entity0_diff.keys()) + list(entity1_diff.keys()))):
         if attr == "parents" or attr == "properties":
             continue
         description += "{} differs:\n".format(attr)
-        description += label_old + ": {}\n".format(
-            olddiff[attr] if attr in olddiff else "not set")
-        description += label_new + ": {}\n\n".format(
-            newdiff[attr] if attr in newdiff else "not set")
+        description += label_e0 + ": {}\n".format(
+            entity0_diff[attr] if attr in entity0_diff else "not set")
+        description += label_e1 + ": {}\n\n".format(
+            entity1_diff[attr] if attr in entity1_diff else "not set")
 
-    if len(olddiff["parents"]) > 0:
-        description += ("Parents that are only in the " + label_old + ":\n"
-                        + ", ".join(olddiff["parents"]) + "\n")
+    if len(entity0_diff["parents"]) > 0:
+        description += ("Parents that are only in the " + label_e0 + ":\n"
+                        + ", ".join(entity0_diff["parents"]) + "\n")
 
-    if len(newdiff["parents"]) > 0:
-        description += ("Parents that are only in the " + label_new + ":\n"
-                        + ", ".join(olddiff["parents"]) + "\n")
+    if len(entity1_diff["parents"]) > 0:
+        description += ("Parents that are only in the " + label_e1 + ":\n"
+                        + ", ".join(entity0_diff["parents"]) + "\n")
 
-    for prop in list(set(list(olddiff["properties"].keys())
-                         + list(newdiff["properties"].keys()))):
+    for prop in list(set(list(entity0_diff["properties"].keys())
+                         + list(entity1_diff["properties"].keys()))):
         description += "property {} differs:\n".format(prop)
 
-        if prop not in olddiff["properties"]:
-            description += "it does not exist in the " + label_old + ":\n"
-        elif prop not in newdiff["properties"]:
-            description += "it does not exist in the " + label_new + ":\n"
+        if prop not in entity0_diff["properties"]:
+            description += "it does not exist in the " + label_e0 + ":\n"
+        elif prop not in entity1_diff["properties"]:
+            description += "it does not exist in the " + label_e1 + ":\n"
         else:
-            description += label_old + ": {}\n".format(
-                olddiff["properties"][prop])
-            description += label_new + ": {}\n\n".format(
-                newdiff["properties"][prop])
+            description += label_e0 + ": {}\n".format(
+                entity0_diff["properties"][prop])
+            description += label_e1 + ": {}\n\n".format(
+                entity1_diff["properties"][prop])
 
     if description != "":
         description = ("## Difference between the " +
-                       label_old +
+                       label_e0 +
                        " and the " +
-                       label_new +
+                       label_e1 +
                        " of {}\n\n".format(name)) + description
 
     return description