Adding update_many method

Author: apetenchea

arangoasync/collection.py

@@ -1177,7 +1177,7 @@ async def insert_many(
         merge_objects: Optional[bool] = None,
         refill_index_caches: Optional[bool] = None,
         version_attribute: Optional[str] = None,
-    ) -> Result[Optional[Jsons]]:
+    ) -> Result[Jsons]:
         """Insert multiple documents.
 
         Note:
@@ -1213,15 +1213,15 @@ async def insert_many(
                 instead of the new one overwriting the old one. Applies only when
                 **overwrite_mode** is set to "update" (update-insert).
             refill_index_caches (bool | None): Whether to add new entries to
-                in-memory index caches if document insertions affect the edge index
+                in-memory index caches if document operations affect the edge index
                 or cache-enabled persistent indexes.
             version_attribute (str | None): Support for simple external versioning to
                 document operations. Only applicable if **overwrite** is set to `True`
                 or **overwrite_mode** is set to "update" or "replace".
 
         Returns:
-            None | list: Documents metadata (e.g. document id, key, revision) and
-                errors or `None` if **silent** is set to `True`.
+            list: Documents metadata (e.g. document id, key, revision) and
+                errors or just errors if **silent** is set to `True`.
 
         Raises:
             DocumentInsertError: If insertion fails.
@@ -1266,3 +1266,90 @@ def response_handler(
             return self.deserializer.loads_many(resp.raw_body)
 
         return await self._executor.execute(request, response_handler)
+
+    async def replace_many(
+        self,
+        documents: Sequence[T],
+        wait_for_sync: Optional[bool] = None,
+        ignore_revs: Optional[bool] = None,
+        return_new: Optional[bool] = None,
+        return_old: Optional[bool] = None,
+        silent: Optional[bool] = None,
+        refill_index_caches: Optional[bool] = None,
+        version_attribute: Optional[str] = None,
+    ) -> Result[Jsons]:
+        """Insert multiple documents.
+
+        Note:
+            If replacing a document fails, the exception is not raised but
+            returned as an object in the "errors" list. It is up to you to
+            inspect the list to determine which documents were replaced
+            successfully (returns document metadata) and which were not
+            (returns exception object).
+
+        Args:
+            documents (list): New documents to replace the old ones. If an item
+                contains the "_key" or "_id" field, the value is used as the key
+                of the new document (otherwise it is auto-generated).
+            wait_for_sync (bool | None): Wait until documents have been synced to disk.
+            ignore_revs (bool | None): If this is set to `False`, then any `_rev`
+                attribute given in a body document is taken as a precondition. The
+                document is only replaced if the current revision is the one
+                specified.
+            return_new (bool | None): Additionally return the complete new document
+                under the attribute `new` in the result.
+            return_old (bool | None): Additionally return the complete old document
+                under the attribute `old` in the result. Only available if the
+                `overwrite` option is used.
+            silent (bool | None): If set to `True`, an empty object is returned as
+                response if all document operations succeed. No meta-data is returned
+                for the created documents. If any of the operations raises an error,
+                an array with the error object(s) is returned.
+            refill_index_caches (bool | None): Whether to add new entries to
+                in-memory index caches if document operations affect the edge index
+                or cache-enabled persistent indexes.
+            version_attribute (str | None): Support for simple external versioning to
+                document operations. Only applicable if **overwrite** is set to `True`
+                or **overwrite_mode** is set to "update" or "replace".
+
+        Returns:
+            list: Documents metadata (e.g. document id, key, revision) and
+                errors or just errors if **silent** is set to `True`.
+
+        Raises:
+            DocumentReplaceError: If replacing fails.
+
+        References:
+            - `replace-multiple-documents <https://docs.arangodb.com/stable/develop/http-api/documents/#replace-multiple-documents>`__
+        """  # noqa: E501
+        params: Params = {}
+        if wait_for_sync is not None:
+            params["waitForSync"] = wait_for_sync
+        if ignore_revs is not None:
+            params["ignoreRevs"] = ignore_revs
+        if return_new is not None:
+            params["returnNew"] = return_new
+        if return_old is not None:
+            params["returnOld"] = return_old
+        if silent is not None:
+            params["silent"] = silent
+        if refill_index_caches is not None:
+            params["refillIndexCaches"] = refill_index_caches
+        if version_attribute is not None:
+            params["versionAttribute"] = version_attribute
+
+        request = Request(
+            method=Method.PUT,
+            endpoint=f"/_api/document/{self.name}",
+            data=self._doc_serializer.dumps(documents),
+            params=params,
+        )
+
+        def response_handler(
+            resp: Response,
+        ) -> Jsons:
+            if not resp.is_success:
+                raise DocumentReplaceError(resp, request)
+            return self.deserializer.loads_many(resp.raw_body)
+
+        return await self._executor.execute(request, response_handler)

tests/test_document.py

@@ -335,3 +335,39 @@ async def test_document_insert_many(doc_col, bad_col, docs):
     await doc_col.truncate()
     result = await doc_col.insert_many(docs, silent=True)
     assert len(result) == 0
+
+
+@pytest.mark.asyncio
+async def test_document_replace_many(doc_col, bad_col, docs):
+    # Check errors
+    with pytest.raises(DocumentReplaceError):
+        await bad_col.replace_many(docs)
+
+    # Empty list
+    result = await doc_col.replace_many([])
+    assert len(result) == 0
+
+    # Replace "not found" documents
+    result = await doc_col.replace_many(docs, return_new=True)
+    assert len(result) == len(docs)
+    for res in result:
+        assert "error" in res
+
+    # Replace successfully
+    result = await doc_col.insert_many(docs, return_new=True)
+    replacements = []
+    for doc in result:
+        replacements.append({"_key": doc["_key"], "val": 42})
+    result = await doc_col.replace_many(replacements, return_new=True)
+    assert len(result) == len(docs)
+    for doc in result:
+        assert doc["new"]["val"] == 42
+
+    # Silent mode
+    result = await doc_col.replace_many(docs, silent=True)
+    assert len(result) == 0
+    await doc_col.truncate()
+    result = await doc_col.replace_many(docs, silent=True)
+    assert len(result) == len(docs)
+    for res in result:
+        assert "error" in res