Document replace

Author: apetenchea

arangoasync/collection.py

@@ -13,6 +13,7 @@
     DocumentGetError,
     DocumentInsertError,
     DocumentParseError,
+    DocumentReplaceError,
     DocumentRevisionError,
     DocumentUpdateError,
     IndexCreateError,
@@ -638,3 +639,85 @@ def response_handler(resp: Response) -> bool | Json:
             raise DocumentUpdateError(resp, request, msg)
 
         return await self._executor.execute(request, response_handler)
+
+    async def replace(
+        self,
+        document: T,
+        ignore_revs: Optional[bool] = None,
+        wait_for_sync: 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[bool | Json]:
+        """Replace a document.
+
+        Args:
+            document (dict): New document. It must contain the "_key" or "_id" field.
+                Edge document must also have "_from" and "_to" fields.
+            ignore_revs (bool | None): If set to `True`, the `_rev` attribute in the
+                document is ignored. If this is set to `False`, then the `_rev`
+                attribute given in the body document is taken as a precondition.
+                The document is only replaced if the current revision is the one
+                specified.
+            wait_for_sync (bool | None): Wait until document has been synced to disk.
+            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.
+            silent (bool | None): If set to `True`, no document metadata is returned.
+                This can be used to save resources.
+            refill_index_caches (bool | None): Whether to add new entries to
+                in-memory index caches if document updates affect the edge index
+                or cache-enabled persistent indexes.
+            version_attribute (str | None): Support for simple external versioning to
+                document operations.
+
+        Returns:
+            bool | dict: Document metadata (e.g. document id, key, revision) or `True`
+                if **silent** is set to `True`.
+
+        Raises:
+            DocumentRevisionError: If precondition was violated.
+            DocumentReplaceError: If replace fails.
+
+        References:
+            - `replace-a-document <https://docs.arangodb.com/stable/develop/http-api/documents/#replace-a-document>`__
+        """  # noqa: E501
+        params: Params = {}
+        if ignore_revs is not None:
+            params["ignoreRevs"] = ignore_revs
+        if wait_for_sync is not None:
+            params["waitForSync"] = wait_for_sync
+        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._extract_id(cast(Json, document))}",
+            params=params,
+            data=self._doc_serializer.dumps(document),
+        )
+
+        def response_handler(resp: Response) -> bool | Json:
+            if resp.is_success:
+                if silent is True:
+                    return True
+                return self._executor.deserialize(resp.raw_body)
+            msg: Optional[str] = None
+            if resp.status_code == HTTP_PRECONDITION_FAILED:
+                raise DocumentRevisionError(resp, request)
+            elif resp.status_code == HTTP_NOT_FOUND:
+                msg = "Document, collection or transaction not found."
+            raise DocumentReplaceError(resp, request, msg)
+
+        return await self._executor.execute(request, response_handler)

arangoasync/exceptions.py

@@ -239,6 +239,10 @@ class DocumentParseError(ArangoClientError):
     """Failed to parse document input."""
 
 
+class DocumentReplaceError(ArangoServerError):
+    """Failed to replace document."""
+
+
 class DocumentRevisionError(ArangoServerError):
     """The expected and actual document revisions mismatched."""
 

tests/test_document.py

@@ -3,6 +3,7 @@
 from arangoasync.exceptions import (
     DocumentInsertError,
     DocumentParseError,
+    DocumentReplaceError,
     DocumentUpdateError,
 )
 from tests.helpers import generate_col_name
@@ -49,8 +50,10 @@ async def test_document_update(doc_col, bad_col, docs):
     assert doc["val"] != 42
     await doc_col.insert(doc)
     doc["val"] = 42
-    updated = await doc_col.update(doc)
+    updated = await doc_col.update(doc, return_old=True, return_new=True)
     assert updated["_key"] == doc["_key"]
+    assert "old" in updated
+    assert "new" in updated
     new_value = await doc_col.get(doc)
     assert new_value["val"] == doc["val"]
 
@@ -60,3 +63,35 @@ async def test_document_update(doc_col, bad_col, docs):
     assert updated is True
     new_value = await doc_col.get(doc)
     assert "val" not in new_value
+
+
+@pytest.mark.asyncio
+async def test_document_replace(doc_col, bad_col, docs):
+    # Test updating a non-existent document
+    with pytest.raises(DocumentReplaceError):
+        await bad_col.replace({"_key": "non-existent", "val": 42})
+
+    # Verbose replace
+    doc = docs[0]
+    assert doc["val"] != 42
+    await doc_col.insert(doc)
+    doc["val"] = 42
+    doc.pop("loc")
+    doc.pop("text")
+    replaced = await doc_col.replace(doc, return_old=True, return_new=True)
+    assert replaced["_key"] == doc["_key"]
+    new_value = await doc_col.get(doc)
+    assert new_value["val"] == doc["val"]
+    assert "text" not in new_value
+    assert "loc" not in new_value
+    assert "new" in replaced
+    assert "old" in replaced
+
+    # Silent replace
+    doc["text"] = "abcd"
+    doc["new_entry"] = 3.14
+    replaced = await doc_col.replace(doc, silent=True)
+    assert replaced is True
+    new_value = await doc_col.get(doc)
+    assert new_value["text"] == doc["text"]
+    assert new_value["new_entry"] == doc["new_entry"]