Merge branch 'main' into DE-752

Author: aMahanna

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/client.py

@@ -12,7 +12,7 @@
     JwtSuperuserConnection,
 )
 from arango.database import StandardDatabase
-from arango.exceptions import ServerConnectionError
+from arango.exceptions import ArangoClientError, ServerConnectionError
 from arango.http import (
     DEFAULT_REQUEST_TIMEOUT,
     DefaultHTTPClient,
@@ -300,6 +300,6 @@ def db(
             except ServerConnectionError as err:
                 raise err
             except Exception as err:
-                raise ServerConnectionError(f"bad connection: {err}")
+                raise ArangoClientError(f"bad connection: {err}")
 
         return StandardDatabase(connection)

arango/connection.py

@@ -226,9 +226,13 @@ def ping(self) -> int:
         request = Request(method="get", endpoint="/_api/collection")
         resp = self.send_request(request)
         if resp.status_code in {401, 403}:
-            raise ServerConnectionError("bad username/password or token is expired")
+            raise ServerConnectionError(
+                resp, request, "bad username/password or token is expired"
+            )
         if not resp.is_success:  # pragma: no cover
-            raise ServerConnectionError(resp.error_message or "bad server response")
+            raise ServerConnectionError(
+                resp, request, resp.error_message or "bad server response"
+            )
         return resp.status_code
 
     @abstractmethod

arango/database.py

@@ -1442,10 +1442,11 @@ def create_collection(
         :raise arango.exceptions.CollectionCreateError: If create fails.
         """
         key_options: Json = {"type": key_generator, "allowUserKeys": user_keys}
-        if key_increment is not None:
-            key_options["increment"] = key_increment
-        if key_offset is not None:
-            key_options["offset"] = key_offset
+        if key_generator == "autoincrement":
+            if key_increment is not None:
+                key_options["increment"] = key_increment
+            if key_offset is not None:
+                key_options["offset"] = key_offset
 
         data: Json = {
             "name": name,

arango/exceptions.py

@@ -614,7 +614,7 @@ class PregelJobDeleteError(ArangoServerError):
 #####################
 
 
-class ServerConnectionError(ArangoClientError):
+class ServerConnectionError(ArangoServerError):
     """Failed to connect to ArangoDB server."""
 
 

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_client.py

@@ -8,7 +8,7 @@
 
 from arango.client import ArangoClient
 from arango.database import StandardDatabase
-from arango.exceptions import ServerConnectionError
+from arango.exceptions import ArangoClientError, ServerConnectionError
 from arango.http import DefaultHTTPClient, DeflateRequestCompression
 from arango.resolver import FallbackHostResolver, RandomHostResolver, SingleHostResolver
 from tests.helpers import (
@@ -89,7 +89,7 @@ def test_client_bad_connection(db, username, password, cluster):
 
     # Test connection with invalid host URL
     client = ArangoClient(hosts="http://127.0.0.1:8500")
-    with pytest.raises(ServerConnectionError) as err:
+    with pytest.raises(ArangoClientError) as err:
         client.db(db.name, username, password, verify=True)
     assert "bad connection" in str(err.value)
 

tests/test_collection.py

@@ -190,14 +190,21 @@ def test_collection_management(db, bad_db, cluster):
         }
     ]
 
+    col = db.create_collection(
+        name=col_name, key_generator="autoincrement", key_increment=9, key_offset=100
+    )
+    key_options = col.properties()["key_options"]
+    assert key_options["key_generator"] == "autoincrement"
+    assert key_options["key_increment"] == 9
+    assert key_options["key_offset"] == 100
+    db.delete_collection(col_name)
+
     col = db.create_collection(
         name=col_name,
         sync=True,
         system=False,
         key_generator="traditional",
         user_keys=False,
-        key_increment=9,
-        key_offset=100,
         edge=True,
         shard_count=2,
         shard_fields=["test_attr:"],

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())