Traversal API no longer available in 3.12 (#335)

* Emitting warning on graph traversals

* Changed docs example

* Changing readme example

* Skipping traversal test on newer versions

Author: apetenchea

README.md

@@ -113,12 +113,13 @@ edges.insert({"_from": "students/02", "_to": "lectures/MAT101"})
 edges.insert({"_from": "students/02", "_to": "lectures/STA101"})
 edges.insert({"_from": "students/03", "_to": "lectures/CSC101"})
 
-# Traverse the graph in outbound direction, breadth-first.
-result = graph.traverse(
-    start_vertex="students/01",
-    direction="outbound",
-    strategy="breadthfirst"
-)
+# Traverse the graph in outbound direction, breath-first.
+query = """
+    FOR v, e, p IN 1..3 OUTBOUND 'students/01' GRAPH 'school'
+    OPTIONS { bfs: true, uniqueVertices: 'global' }
+    RETURN {vertex: v, edge: e, path: p}
+    """
+cursor = db.aql.execute(query)
 ```
 
 Please see the [documentation](https://docs.python-arango.com) for more details.

arango/graph.py

@@ -1,6 +1,7 @@
 __all__ = ["Graph"]
 
 from typing import List, Optional, Sequence, Union
+from warnings import warn
 
 from arango.api import ApiGroup
 from arango.collection import EdgeCollection, VertexCollection
@@ -384,6 +385,11 @@ def traverse(
     ) -> Result[Json]:
         """Traverse the graph and return the visited vertices and edges.
 
+        .. warning::
+
+            This method is deprecated and no longer works since ArangoDB 3.12.
+            The preferred way to traverse graphs is via AQL.
+
         :param start_vertex: Start vertex document ID or body with "_id" field.
         :type start_vertex: str | dict
         :param direction: Traversal direction. Allowed values are "outbound"
@@ -441,6 +447,9 @@ def traverse(
         :rtype: dict
         :raise arango.exceptions.GraphTraverseError: If traversal fails.
         """
+        m = "The HTTP traversal API is deprecated since version 3.4.0. The preferred way to traverse graphs is via AQL."  # noqa: E501
+        warn(m, DeprecationWarning, stacklevel=2)
+
         if strategy is not None:
             if strategy.lower() == "dfs":
                 strategy = "depthfirst"

docs/graph.rst

@@ -318,8 +318,10 @@ See :ref:`Graph` and :ref:`EdgeCollection` for API specification.
 Graph Traversals
 ================
 
-**Graph traversals** are executed via the :func:`arango.graph.Graph.traverse`
-method. Each traversal can span across multiple vertex collections, and walk
+**Graph traversals** are executed via AQL. The old
+:func:`arango.graph.Graph.traverse` has been deprecated and can no longer be
+used with ArangoDB 3.12 or later.
+Each traversal can span across multiple vertex collections, and walk
 over edges and vertices using various algorithms.
 
 **Example:**
@@ -371,13 +373,12 @@ over edges and vertices using various algorithms.
     teach.insert({'_from': 'teachers/jon', '_to': 'lectures/STA201'})
     teach.insert({'_from': 'teachers/jon', '_to': 'lectures/MAT223'})
 
-    # Traverse the graph in outbound direction, breath-first.
-    school.traverse(
-        start_vertex='teachers/jon',
-        direction='outbound',
-        strategy='bfs',
-        edge_uniqueness='global',
-        vertex_uniqueness='global',
-    )
+    # AQL to perform a graph traversal
+    query = """
+    FOR v, e, p IN 1..3 OUTBOUND 'teachers/jon' GRAPH 'school'
+    OPTIONS { bfs: true, uniqueVertices: 'global' }
+    RETURN {vertex: v, edge: e, path: p}
+    """
 
-See :func:`arango.graph.Graph.traverse` for API specification.
+    # Traverse the graph in outbound direction, breath-first.
+    cursor = db.aql.execute(query)

tests/test_graph.py

@@ -1,3 +1,6 @@
+import pytest
+from packaging import version
+
 from arango.collection import EdgeCollection
 from arango.exceptions import (
     DocumentDeleteError,
@@ -1071,7 +1074,10 @@ def test_edge_management_via_graph(graph, ecol, fvcol, fvdocs, tvcol, tvdocs):
     assert len(ecol) == 1
 
 
-def test_traverse(db):
+def test_traverse(db, db_version):
+    if db_version >= version.parse("3.12.0"):
+        pytest.skip("Traversal API is no longer available for ArangoDB 3.12+")
+
     # Create test graph, vertex and edge collections
     school = db.create_graph(generate_graph_name())
     profs = school.create_vertex_collection(generate_col_name())