DEPR: deprecate old_entity/new_entity of compare_entities

CHANGELOG.md

@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * `ParentList.remove` is now case insensitive when a name is used.
 
 ### Deprecated ###
+* the use of the arguments `old_entity` and `new_entity` in `compare_entities`
+  is now deprecated. Please use `entity0` and `entity1` respectively instead.
 
 ### Removed ###
 

src/linkahead/apiutils.py

@@ -28,10 +28,11 @@
 
 """
 from __future__ import annotations
+
 import logging
 import warnings
 from collections.abc import Iterable
-from typing import Any, Union, Optional
+from typing import Any, Optional, Union
 
 from .common.datatype import is_reference
 from .common.models import (SPECIAL_ATTRIBUTES, Container, Entity, File,
@@ -179,9 +180,12 @@ def getCommitIn(folder):
     return get_commit_in(folder)
 
 
-def compare_entities(old_entity: Entity, new_entity: Entity,
+def compare_entities(entity0: Optional[Entity] = None,
+                     entity1: Optional[Entity] = None,
                      compare_referenced_records: bool = False,
-                     entity_name_id_equivalency: bool = False
+                     entity_name_id_equivalency: bool = False,
+                     old_entity: Optional[Entity] = None,
+                     new_entity: Optional[Entity] = None,
                      ) -> tuple[dict[str, Any], dict[str, Any]]:
     """Compare two entities.
 
@@ -219,9 +223,9 @@ def compare_entities(old_entity: Entity, new_entity: Entity,
 
     Params
     ------
-    old_entity                : Entity
+    entity0                : Entity
                                 First entity to be compared.
-    new_entity                : Entity
+    entity1                : Entity
                                 Second entity to be compared.
     compare_referenced_records: bool, default: False
                                 If set to True, values with referenced records
@@ -252,9 +256,22 @@ def compare_entities(old_entity: Entity, new_entity: Entity,
     #    - Make the empty_diff functionality faster by adding a parameter to
     #      this function so that it returns after the first found difference?
     #    - Add parameter to restrict diff to some characteristics
-    entity0, entity1 = old_entity, new_entity
-
-    diff = ({"properties": {}, "parents": []},
+    if entity0 is None and old_entity is None:
+        raise ValueError("Please provide the first entity as first argument (`entity0`)")
+    if entity1 is None and new_entity is None:
+        raise ValueError("Please provide the second entity as second argument (`entity1`)")
+    if old_entity is not None:
+        warnings.warn("Please use 'entity0' instead of 'old_entity'.", DeprecationWarning)
+        if entity0 is not None:
+            raise ValueError("You cannot use both, entity0 and old_entity")
+        entity0 = old_entity
+    if new_entity is not None:
+        warnings.warn("Please use 'entity1' instead of 'new_entity'.", DeprecationWarning)
+        if entity1 is not None:
+            raise ValueError("You cannot use both, entity1 and new_entity")
+        entity1 = new_entity
+
+    diff: tuple = ({"properties": {}, "parents": []},
                    {"properties": {}, "parents": []})
 
     if entity0 is entity1: