Edges CRUD

Author: apetenchea

arangoasync/collection.py

@@ -2317,7 +2317,7 @@ async def update(
         return_old: Optional[bool] = None,
         if_match: Optional[str] = None,
     ) -> Result[Json]:
-        """Update a vertex in the graph.
+        """Update an edge in the graph.
 
         Args:
             edge (dict): Partial or full document with the updated values.
@@ -2336,7 +2336,7 @@ async def update(
         Returns:
             dict: Document metadata (e.g. document id, key, revision).
                 If `return_new` or "return_old" are specified, the result contains
-                the document metadata in the "vertex" field and two additional fields
+                the document metadata in the "edge" field and two additional fields
                 ("new" and "old").
 
         Raises:
@@ -2385,3 +2385,154 @@ def response_handler(resp: Response) -> Json:
             raise DocumentUpdateError(resp, request, msg)
 
         return await self._executor.execute(request, response_handler)
+
+    async def replace(
+        self,
+        edge: T,
+        wait_for_sync: Optional[bool] = None,
+        keep_null: Optional[bool] = None,
+        return_new: Optional[bool] = None,
+        return_old: Optional[bool] = None,
+        if_match: Optional[str] = None,
+    ) -> Result[Json]:
+        """Replace an edge in the graph.
+
+        Args:
+            edge (dict): Partial or full document with the updated values.
+                It must contain the "_key" or "_id" field, along with "_from" and
+                "_to" fields.
+            wait_for_sync (bool | None): Wait until document has been synced to disk.
+            keep_null (bool | None): If the intention is to delete existing attributes
+                with the patch command, set this parameter to `False`.
+            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.
+            if_match (str | None): You can conditionally replace a document based on a
+                target revision id by using the "if-match" HTTP header.
+
+        Returns:
+            dict: Document metadata (e.g. document id, key, revision).
+                If `return_new` or "return_old" are specified, the result contains
+                the document metadata in the "edge" field and two additional fields
+                ("new" and "old").
+
+        Raises:
+            DocumentRevisionError: If precondition was violated.
+            DocumentReplaceError: If replace fails.
+
+        References:
+            - `replace-an-edge <https://docs.arangodb.com/stable/develop/http-api/graphs/named-graphs/#replace-an-edge>`__
+        """  # noqa: E501
+        params: Params = {}
+        if wait_for_sync is not None:
+            params["waitForSync"] = wait_for_sync
+        if keep_null is not None:
+            params["keepNull"] = keep_null
+        if return_new is not None:
+            params["returnNew"] = return_new
+        if return_old is not None:
+            params["returnOld"] = return_old
+
+        headers: RequestHeaders = {}
+        if if_match is not None:
+            headers["If-Match"] = if_match
+
+        request = Request(
+            method=Method.PUT,
+            endpoint=f"/_api/gharial/{self._graph}/edge/"
+            f"{self._prep_from_doc(cast(Json, edge))}",
+            params=params,
+            headers=headers,
+            data=self._doc_serializer.dumps(edge),
+        )
+
+        def response_handler(resp: Response) -> Json:
+            if resp.is_success:
+                return self._parse_result(self.deserializer.loads(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 = (
+                    "The graph cannot be found or the edge collection is not "
+                    "part of the graph. It is also possible that the vertex "
+                    "collection referenced in the _from or _to attribute is not part "
+                    "of the graph or the vertex collection is part of the graph, but "
+                    "does not exist. Finally check that _from or _to vertex do exist."
+                )
+            raise DocumentReplaceError(resp, request, msg)
+
+        return await self._executor.execute(request, response_handler)
+
+    async def delete(
+        self,
+        edge: T,
+        ignore_missing: bool = False,
+        wait_for_sync: Optional[bool] = None,
+        return_old: Optional[bool] = None,
+        if_match: Optional[str] = None,
+    ) -> Result[bool | Json]:
+        """Delete an edge from the graph.
+
+        Args:
+            edge (dict): Partial or full document with the updated values.
+                It must contain the "_key" or "_id" field, along with "_from" and
+                "_to" fields.
+            ignore_missing (bool): Do not raise an exception on missing document.
+            wait_for_sync (bool | None): Wait until operation has been synced to disk.
+            return_old (bool | None): Additionally return the complete old document
+                under the attribute `old` in the result.
+            if_match (str | None): You can conditionally replace a document based on a
+                target revision id by using the "if-match" HTTP header.
+
+        Returns:
+            bool | dict: `True` if vertex was deleted successfully, `False` if vertex
+                was not found and **ignore_missing** was set to `True` (does not apply
+                in transactions). Old document is returned if **return_old** is set
+                to `True`.
+
+        Raises:
+            DocumentRevisionError: If precondition was violated.
+            DocumentDeleteError: If deletion fails.
+
+        References:
+            - `remove-an-edge <https://docs.arangodb.com/stable/develop/http-api/graphs/named-graphs/#remove-an-edge>`__
+        """  # noqa: E501
+        params: Params = {}
+        if wait_for_sync is not None:
+            params["waitForSync"] = wait_for_sync
+        if return_old is not None:
+            params["returnOld"] = return_old
+
+        headers: RequestHeaders = {}
+        if if_match is not None:
+            headers["If-Match"] = if_match
+
+        request = Request(
+            method=Method.DELETE,
+            endpoint=f"/_api/gharial/{self._graph}/edge/"
+            f"{self._prep_from_doc(cast(Json, edge))}",
+            params=params,
+            headers=headers,
+        )
+
+        def response_handler(resp: Response) -> bool | Json:
+            if resp.is_success:
+                data: Json = self.deserializer.loads(resp.raw_body)
+                if "old" in data:
+                    return cast(Json, data["old"])
+                return True
+            msg: Optional[str] = None
+            if resp.status_code == HTTP_PRECONDITION_FAILED:
+                raise DocumentRevisionError(resp, request)
+            elif resp.status_code == HTTP_NOT_FOUND:
+                if resp.error_code == DOCUMENT_NOT_FOUND and ignore_missing:
+                    return False
+                msg = (
+                    "Either the graph cannot be found, the edge collection is not "
+                    "part of the graph, or the edge does not exist"
+                )
+            raise DocumentDeleteError(resp, request, msg)
+
+        return await self._executor.execute(request, response_handler)

arangoasync/graph.py

@@ -857,7 +857,7 @@ async def update_edge(
         Returns:
             dict: Document metadata (e.g. document id, key, revision).
                 If `return_new` or "return_old" are specified, the result contains
-                the document metadata in the "vertex" field and two additional fields
+                the document metadata in the "edge" field and two additional fields
                 ("new" and "old").
 
         Raises:
@@ -875,3 +875,94 @@ async def update_edge(
             return_old=return_old,
             if_match=if_match,
         )
+
+    async def replace_edge(
+        self,
+        edge: T,
+        wait_for_sync: Optional[bool] = None,
+        keep_null: Optional[bool] = None,
+        return_new: Optional[bool] = None,
+        return_old: Optional[bool] = None,
+        if_match: Optional[str] = None,
+    ) -> Result[Json]:
+        """Replace an edge in the graph.
+
+        Args:
+            edge (dict): Partial or full document with the updated values.
+                It must contain the "_key" or "_id" field, along with "_from" and
+                "_to" fields.
+            wait_for_sync (bool | None): Wait until document has been synced to disk.
+            keep_null (bool | None): If the intention is to delete existing attributes
+                with the patch command, set this parameter to `False`.
+            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.
+            if_match (str | None): You can conditionally replace a document based on a
+                target revision id by using the "if-match" HTTP header.
+
+        Returns:
+            dict: Document metadata (e.g. document id, key, revision).
+                If `return_new` or "return_old" are specified, the result contains
+                the document metadata in the "edge" field and two additional fields
+                ("new" and "old").
+
+        Raises:
+            DocumentRevisionError: If precondition was violated.
+            DocumentReplaceError: If replace fails.
+
+        References:
+            - `replace-an-edge <https://docs.arangodb.com/stable/develop/http-api/graphs/named-graphs/#replace-an-edge>`__
+        """  # noqa: E501
+        col = Collection.get_col_name(cast(Json | str, edge))
+        return await self.edge_collection(col).replace(
+            edge,
+            wait_for_sync=wait_for_sync,
+            keep_null=keep_null,
+            return_new=return_new,
+            return_old=return_old,
+            if_match=if_match,
+        )
+
+    async def delete_edge(
+        self,
+        edge: T,
+        ignore_missing: bool = False,
+        wait_for_sync: Optional[bool] = None,
+        return_old: Optional[bool] = None,
+        if_match: Optional[str] = None,
+    ) -> Result[bool | Json]:
+        """Delete an edge from the graph.
+
+        Args:
+            edge (dict): Partial or full document with the updated values.
+                It must contain the "_key" or "_id" field, along with "_from" and
+                "_to" fields.
+            ignore_missing (bool): Do not raise an exception on missing document.
+            wait_for_sync (bool | None): Wait until operation has been synced to disk.
+            return_old (bool | None): Additionally return the complete old document
+                under the attribute `old` in the result.
+            if_match (str | None): You can conditionally replace a document based on a
+                target revision id by using the "if-match" HTTP header.
+
+        Returns:
+            bool | dict: `True` if vertex was deleted successfully, `False` if vertex
+                was not found and **ignore_missing** was set to `True` (does not apply
+                in transactions). Old document is returned if **return_old** is set
+                to `True`.
+
+        Raises:
+            DocumentRevisionError: If precondition was violated.
+            DocumentDeleteError: If deletion fails.
+
+        References:
+            - `remove-an-edge <https://docs.arangodb.com/stable/develop/http-api/graphs/named-graphs/#remove-an-edge>`__
+        """  # noqa: E501
+        col = Collection.get_col_name(cast(Json | str, edge))
+        return await self.edge_collection(col).delete(
+            edge,
+            ignore_missing=ignore_missing,
+            wait_for_sync=wait_for_sync,
+            return_old=return_old,
+            if_match=if_match,
+        )

tests/test_graph.py

@@ -154,6 +154,7 @@ async def test_vertex_collections(db, docs, bad_graph):
     v1["text"] = "updated_text"
     v1_meta = await graph.update_vertex(v1, return_new=True)
     assert "new" in v1_meta
+    assert "vertex" in v1_meta
     v1 = await graph.vertex(v1_meta["vertex"])
     assert v1["text"] == "updated_text"
 
@@ -164,6 +165,7 @@ async def test_vertex_collections(db, docs, bad_graph):
     v1_meta = await graph.replace_vertex(v1, return_old=True, return_new=True)
     assert "old" in v1_meta
     assert "new" in v1_meta
+    assert "vertex" in v1_meta
     v1 = await graph.vertex(v1_meta["vertex"])
     assert v1["text"] == "replaced_text"
     assert "additional" in v1
@@ -255,16 +257,20 @@ async def test_edge_collections(db, bad_graph):
     ]
 
     # Create an edge
-    await graph.insert_vertex(teachers_col_name, teachers[0])
-    await graph.insert_vertex(students_col_name, students[0])
-    edge_meta = await graph.insert_edge(
-        edge_col_name,
-        edges[0],
-        return_new=True,
-    )
-    assert "new" in edge_meta
+    edge_metas = []
+    for idx in range(len(edges)):
+        await graph.insert_vertex(teachers_col_name, teachers[idx])
+        await graph.insert_vertex(students_col_name, students[idx])
+        edge_meta = await graph.insert_edge(
+            edge_col_name,
+            edges[0],
+            return_new=True,
+        )
+        assert "new" in edge_meta
+        edge_metas.append(edge_meta)
 
     # Check for edge existence
+    edge_meta = edge_metas[0]
     edge_id = edge_meta["new"]["_id"]
     assert await graph.has_edge(edge_id) is True
     assert await graph.has_edge(f"{edge_col_name}/bad_id") is False
@@ -276,9 +282,27 @@ async def test_edge_collections(db, bad_graph):
     updated_edge_meta = await graph.update_edge(edge, return_new=True, return_old=True)
     assert "new" in updated_edge_meta
     assert "old" in updated_edge_meta
+    assert "edge" in updated_edge_meta
     edge = await graph.edge(edge_id)
     assert edge["subject"] == "Advanced Math"
 
+    # Replace an edge
+    edge["subject"] = "Replaced Subject"
+    edge["extra_info"] = "Some additional data"
+    replaced_edge_meta = await graph.replace_edge(
+        edge, return_old=True, return_new=True
+    )
+    assert "old" in replaced_edge_meta
+    assert "new" in replaced_edge_meta
+    assert "edge" in replaced_edge_meta
+    edge = await graph.edge(edge_id)
+    assert edge["subject"] == "Replaced Subject"
+
+    # Delete the edge
+    deleted_edge = await graph.delete_edge(edge_id, return_old=True)
+    assert "_id" in deleted_edge
+    assert await graph.has_edge(edge_id) is False
+
     # Replace the edge definition
     new_from_collections = [students_col_name]
     new_to_collections = [teachers_col_name]