[3.12]: External versioning support (#327)

* Initial commit

* Fix lint

* lint

* lint

* addressing comments

* fix lint

* wip

* Added tests

* цшз

arango/collection.py

@@ -1758,6 +1758,7 @@ def insert_many(
         keep_none: Optional[bool] = None,
         merge: Optional[bool] = None,
         refill_index_caches: Optional[bool] = None,
+        version_attribute: Optional[str] = None,
     ) -> Result[Union[bool, List[Union[Json, ArangoServerError]]]]:
         """Insert multiple documents.
 
@@ -1812,6 +1813,9 @@ def insert_many(
             index caches if document insertions affect the edge index or
             cache-enabled persistent indexes.
         :type refill_index_caches: bool | None
+        param version_attribute: support for simple external versioning to
+            document operations.
+        :type version_attribute: str
         :return: List of document metadata (e.g. document keys, revisions) and
             any exception, or True if parameter **silent** was set to True.
         :rtype: [dict | ArangoServerError] | bool
@@ -1834,6 +1838,8 @@ def insert_many(
             params["keepNull"] = keep_none
         if merge is not None:
             params["mergeObjects"] = merge
+        if version_attribute is not None:
+            params["versionAttribute"] = version_attribute
 
         # New in ArangoDB 3.9.6 and 3.10.2
         if refill_index_caches is not None:
@@ -1880,6 +1886,7 @@ def update_many(
         silent: bool = False,
         refill_index_caches: Optional[bool] = None,
         raise_on_document_error: bool = False,
+        version_attribute: Optional[str] = None,
     ) -> Result[Union[bool, List[Union[Json, ArangoServerError]]]]:
         """Update multiple documents.
 
@@ -1932,6 +1939,9 @@ def update_many(
             as opposed to returning the error as an object in the result list.
             Defaults to False.
         :type raise_on_document_error: bool
+        param version_attribute: support for simple external versioning to
+            document operations.
+        :type version_attribute: str
         :return: List of document metadata (e.g. document keys, revisions) and
             any exceptions, or True if parameter **silent** was set to True.
         :rtype: [dict | ArangoError] | bool
@@ -1948,6 +1958,8 @@ def update_many(
         }
         if sync is not None:
             params["waitForSync"] = sync
+        if version_attribute is not None:
+            params["versionAttribute"] = version_attribute
 
         # New in ArangoDB 3.9.6 and 3.10.2
         if refill_index_caches is not None:
@@ -2084,6 +2096,7 @@ def replace_many(
         sync: Optional[bool] = None,
         silent: bool = False,
         refill_index_caches: Optional[bool] = None,
+        version_attribute: Optional[str] = None,
     ) -> Result[Union[bool, List[Union[Json, ArangoServerError]]]]:
         """Replace multiple documents.
 
@@ -2125,6 +2138,9 @@ def replace_many(
             index caches if document operations affect the edge index or
             cache-enabled persistent indexes.
         :type refill_index_caches: bool | None
+        param version_attribute: support for simple external versioning to
+            document operations.
+        :type version_attribute: str
         :return: List of document metadata (e.g. document keys, revisions) and
             any exceptions, or True if parameter **silent** was set to True.
         :rtype: [dict | ArangoServerError] | bool
@@ -2139,6 +2155,8 @@ def replace_many(
         }
         if sync is not None:
             params["waitForSync"] = sync
+        if version_attribute is not None:
+            params["versionAttribute"] = version_attribute
 
         # New in ArangoDB 3.9.6 and 3.10.2
         if refill_index_caches is not None:
@@ -2613,6 +2631,7 @@ def insert(
         keep_none: Optional[bool] = None,
         merge: Optional[bool] = None,
         refill_index_caches: Optional[bool] = None,
+        version_attribute: Optional[str] = None,
     ) -> Result[Union[bool, Json]]:
         """Insert a new document.
 
@@ -2651,6 +2670,9 @@ def insert(
             index caches if document insertions affect the edge index or
             cache-enabled persistent indexes.
         :type refill_index_caches: bool | None
+        param version_attribute: support for simple external versioning to
+            document operations.
+        :type version_attribute: str
         :return: Document metadata (e.g. document key, revision) or True if
             parameter **silent** was set to True.
         :rtype: bool | dict
@@ -2672,6 +2694,8 @@ def insert(
             params["keepNull"] = keep_none
         if merge is not None:
             params["mergeObjects"] = merge
+        if version_attribute is not None:
+            params["versionAttribute"] = version_attribute
 
         # New in ArangoDB 3.9.6 and 3.10.2
         if refill_index_caches is not None:
@@ -2710,6 +2734,7 @@ def update(
         sync: Optional[bool] = None,
         silent: bool = False,
         refill_index_caches: Optional[bool] = None,
+        version_attribute: Optional[str] = None,
     ) -> Result[Union[bool, Json]]:
         """Update a document.
 
@@ -2740,6 +2765,9 @@ def update(
             index caches if document insertions affect the edge index or
             cache-enabled persistent indexes.
         :type refill_index_caches: bool | None
+        param version_attribute: support for simple external versioning
+            to document operations.
+        :type version_attribute: str
         :return: Document metadata (e.g. document key, revision) or True if
             parameter **silent** was set to True.
         :rtype: bool | dict
@@ -2758,6 +2786,9 @@ def update(
         if sync is not None:
             params["waitForSync"] = sync
 
+        if version_attribute is not None:
+            params["versionAttribute"] = version_attribute
+
         # New in ArangoDB 3.9.6 and 3.10.2
         if refill_index_caches is not None:
             params["refillIndexCaches"] = refill_index_caches
@@ -2793,6 +2824,7 @@ def replace(
         sync: Optional[bool] = None,
         silent: bool = False,
         refill_index_caches: Optional[bool] = None,
+        version_attribute: Optional[str] = None,
     ) -> Result[Union[bool, Json]]:
         """Replace a document.
 
@@ -2818,6 +2850,9 @@ def replace(
             index caches if document insertions affect the edge index or
             cache-enabled persistent indexes.
         :type refill_index_caches: bool | None
+        param version_attribute: support for simple external versioning to
+            document operations.
+        :type version_attribute: str
         :return: Document metadata (e.g. document key, revision) or True if
             parameter **silent** was set to True.
         :rtype: bool | dict
@@ -2834,6 +2869,9 @@ def replace(
         if sync is not None:
             params["waitForSync"] = sync
 
+        if version_attribute is not None:
+            params["versionAttribute"] = version_attribute
+
         # New in ArangoDB 3.9.6 and 3.10.2
         if refill_index_caches is not None:
             params["refillIndexCaches"] = refill_index_caches

tests/test_document.py

@@ -1,4 +1,5 @@
 import pytest
+from packaging import version
 
 from arango.exceptions import (
     DocumentCountError,
@@ -2067,3 +2068,74 @@ def test_document_management_via_db(db, col):
     assert result["_id"] == doc1_id
     assert doc1_id not in col
     assert len(col) == 2
+
+
+def test_version_attributes_update_many(col, db_version):
+    if db_version < version.parse("3.12.0"):
+        pytest.skip("Version attributes is tested in 3.12.0+")
+
+    col.insert_many(
+        [
+            {"_key": "test1", "version": 0},
+            {"_key": "test2", "version": 0},
+            {"_key": "test3", "version": 0},
+        ]
+    )
+
+    docs = [
+        {"_key": "test1", "version": 2},
+        {"_key": "test1", "version": 3},
+        {"_key": "test1", "version": 1},
+        {"_key": "test2", "version": 1},
+        {"_key": "test2", "version": 9},
+        {"_key": "test2", "version": 42},
+        {"_key": "test2", "version": 0},
+        {"_key": "test3"},
+        {"_key": "test3", "version": 5},
+        {"_key": "test3", "version": 4},
+        {"_key": "test3", "value": 2},
+    ]
+
+    col.update_many(docs, version_attribute="version")
+    assert col["test1"]["version"] == 3
+    assert col["test2"]["version"] == 42
+    assert col["test3"]["version"] == 5
+
+    docs = [
+        {"_key": "test1", "version": 2},
+        {"_key": "test1", "version": 3},
+        {"_key": "test1", "version": 5},
+        {"_key": "test2", "version": 1},
+        {"_key": "test2", "version": 9},
+        {"_key": "test2", "version": 42},
+        {"_key": "test2", "version": 0},
+        {"_key": "test3", "version": 5},
+        {"_key": "test3", "version": 6},
+    ]
+
+    col.replace_many(docs, version_attribute="version")
+    assert col["test1"]["version"] == 5
+    assert col["test2"]["version"] == 42
+    assert col["test3"]["version"] == 6
+
+    docs = [
+        {"_key": "test1", "version": 0},
+        {"_key": "test2", "version": 0},
+        {"_key": "test3", "version": 0},
+    ]
+
+    col.insert_many(docs, overwrite_mode="update", version_attribute="version")
+    assert col["test1"]["version"] == 5
+    assert col["test2"]["version"] == 42
+    assert col["test3"]["version"] == 6
+
+    docs = [
+        {"_key": "test1", "version": 43},
+        {"_key": "test2", "version": 41},
+        {"_key": "test3", "version": 43},
+    ]
+
+    col.insert_many(docs, overwrite_mode="replace", version_attribute="version")
+    assert col["test1"]["version"] == 43
+    assert col["test2"]["version"] == 42
+    assert col["test3"]["version"] == 43