Add new parameters to insert_many method (#212)

Author: dvzubarev

arango/collection.py

@@ -1322,6 +1322,9 @@ def insert_many(
         silent: bool = False,
         overwrite: bool = False,
         return_old: bool = False,
+        overwrite_mode: Optional[str] = None,
+        keep_none: Optional[bool] = None,
+        merge: Optional[bool] = None,
     ) -> Result[Union[bool, List[Union[Json, ArangoServerError]]]]:
         """Insert multiple documents.
 
@@ -1359,6 +1362,21 @@ def insert_many(
         :param return_old: Include body of the old documents if replaced.
             Applies only when value of **overwrite** is set to True.
         :type return_old: bool
+        :param overwrite_mode: Overwrite behavior used when the document key
+            exists already. Allowed values are "replace" (replace-insert),
+            "update" (update-insert), "ignore" or "conflict".
+            Implicitly sets the value of parameter **overwrite**.
+        :type overwrite_mode: str | None
+        :param keep_none: If set to True, fields with value None are retained
+            in the document. Otherwise, they are removed completely. Applies
+            only when **overwrite_mode** is set to "update" (update-insert).
+        :type keep_none: bool | None
+        :param merge: If set to True (default), sub-dictionaries are merged
+            instead of the new one overwriting the old one. Applies only when
+            **overwrite_mode** is set to "update" (update-insert).
+        :type merge: bool | None
+        :return: Document metadata (e.g. document key, revision) or True if
+            parameter **silent** was set to True.
         :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
@@ -1375,6 +1393,13 @@ def insert_many(
         if sync is not None:
             params["waitForSync"] = sync
 
+        if overwrite_mode is not None:
+            params["overwriteMode"] = overwrite_mode
+        if keep_none is not None:
+            params["keepNull"] = keep_none
+        if merge is not None:
+            params["mergeObjects"] = merge
+
         request = Request(
             method="post",
             endpoint=f"/_api/document/{self.name}",

tests/test_document.py

@@ -234,6 +234,63 @@ def test_document_insert_many(col, bad_col, docs):
         bad_col.insert_many(docs)
     assert err.value.error_code in {11, 1228}
 
+    # test overwrite_mode: replace
+    extra_docs = [
+        {"_key": docs[0]["_key"], "foo": {"qux": 2}},
+        {"_key": "20", "foo": "t"},
+    ]
+    results = col.insert_many(
+        documents=extra_docs,
+        return_old=True,
+        return_new=True,
+        overwrite_mode="replace",
+        keep_none=False,
+        merge=True,
+    )
+
+    assert "old" in results[0]
+    assert "new" in results[0]
+    assert "old" not in results[1]
+    assert "new" in results[1]
+
+    # test overwrite_mode: update
+    extra_docs = [
+        {"_key": docs[0]["_key"], "foo": {"t": 1}},
+        {"_key": "20", "foo": None},
+    ]
+    results = col.insert_many(
+        documents=extra_docs,
+        return_old=True,
+        return_new=True,
+        overwrite_mode="update",
+        keep_none=False,
+        merge=True,
+    )
+    assert "old" in results[0]
+    assert "new" in results[0]
+    assert results[0]["new"]["foo"] == {"qux": 2, "t": 1}
+    assert "old" in results[1]
+    assert "new" in results[1]
+    assert "foo" not in results[1]["new"]
+
+    extra_docs = [
+        {"_key": docs[0]["_key"], "foo": {"t": 1}},
+        {"_key": "21", "foo": None},
+    ]
+
+    # Test insert conflict
+    results = col.insert_many(
+        documents=extra_docs,
+        return_old=True,
+        return_new=True,
+        overwrite_mode="conflict",
+        keep_none=True,
+        merge=True,
+    )
+    assert isinstance(results[0], DocumentInsertError)
+    assert results[0].error_code == 1210
+    assert "new" in results[1]
+
 
 def test_document_update(col, docs):
     doc = docs[0]