Circleci project setup

.circleci/config.yml

@@ -0,0 +1,113 @@
+version: 2.1
+
+# orbs:
+#   coveralls: coveralls/[email protected]
+
+workflows:
+  ci:
+    jobs:
+      - lint
+      - test:
+          matrix:
+            parameters:
+              # TODO: Revisit why pyenv doesn't recognize 3.12
+              python_version: ["3.8", "3.9", "3.10", "3.11"] # "3.12"
+              arangodb_config: ["single", "cluster"]
+              arangodb_license: ["community", "enterprise"]
+              arangodb_version: ["3.10.10", "3.11.4", "latest"]
+
+jobs:
+  lint:
+    docker:
+      - image: python:latest
+    steps:
+      - checkout
+      - run:
+          name: Install Dependencies
+          command: pip install .[dev]
+
+      - run:
+          name: Run black
+          command: black --check --verbose --diff --color --config=pyproject.toml ./arango ./tests/
+
+      - run:
+          name: Run flake8
+          command: flake8 ./arango ./tests
+
+      - run:
+          name: Run isort
+          command: isort --check ./arango ./tests
+
+      - run:
+          name: Run mypy
+          command: mypy ./arango
+
+  test:
+    parameters:
+      python_version:
+        type: string
+      arangodb_config:
+        type: string
+      arangodb_license:
+        type: string
+      arangodb_version:
+        type: string
+    # TODO: Reconsider using a docker image instead of a machine
+    # i.e cimg/python:<< parameters.python_version >>
+    machine:
+      image: ubuntu-2204:current
+    steps:
+      - checkout
+
+      - run:
+          name: Set Up ArangoDB
+          command: |
+            chmod +x starter.sh
+            ./starter.sh << parameters.arangodb_config >> << parameters.arangodb_license >> << parameters.arangodb_version >>
+
+      - restore_cache:
+          key: pip-and-local-cache
+
+      # TODO: Revisit this bottleneck
+      - run:
+          name: Setup Python
+          command: |
+            pyenv --version
+            pyenv install -f << parameters.python_version >>
+            pyenv global << parameters.python_version >>
+
+      - run:
+          name: "Install Dependencies"
+          command: pip install -e .[dev]
+
+      - run: docker ps -a
+
+      - run:
+          name: "Run pytest"
+          command: |
+            mkdir test-results
+
+            args=("--junitxml=test-results/junit.xml" "--log-cli-level=DEBUG" "--host" "localhost" "--port=8529")
+            if [ << parameters.arangodb_config >> = "cluster" ]; then
+              args+=("--cluster" "--port=8539" "--port=8549")
+            fi
+
+            if [ << parameters.arangodb_license >> = "enterprise" ]; then
+              args+=("--enterprise")
+            fi
+
+            echo "Running pytest with args: ${args[@]}"
+            pytest --cov=arango --cov-report=xml "${args[@]}"
+
+      - store_artifacts:
+          path: test-results
+
+      - store_test_results:
+          path: test-results
+
+      # - run:
+      #     name: Upload to Coveralls
+      #     command: |
+      #       if [ "<< parameters.python_version >>" = "3.11" && "<< parameters.arangodb_config >>" = "single" && "<< parameters.arangodb_license >>" = "community" && "<< parameters.arangodb_version >>" = "latest"  ]; then
+      #         coveralls/upload
+      #       fi

.github/workflows/codeql.yaml

@@ -2,7 +2,7 @@ name: CodeQL
 
 on:
   pull_request:
-    branches: [main, dev]
+    branches: [main]
   schedule:
     - cron: '21 2 * * 3'
 

.github/workflows/docs.yaml

@@ -0,0 +1,102 @@
+name: Docs
+
+on:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        type: boolean
+        description: Debug with tmate
+        required: false
+        default: false
+
+jobs:
+  # This has been migrated to CircleCI
+  # test:
+  #   runs-on: ubuntu-latest
+
+  #   strategy:
+  #     fail-fast: false
+  #     matrix:
+  #       python_version: ["3.10"] #["3.8", "3.9", "3.10", "3.11", "3.12"]
+  #       arangodb_config: ["single", "cluster"]
+  #       arangodb_license: ["community", "enterprise"]
+  #       arangodb_version: ["3.10.10", "3.11.4", "latest"]
+
+  #   name: Test (${{ matrix.python_version }}:${{ matrix.arangodb_config }}:${{ matrix.arangodb_license }}:${{ matrix.arangodb_version }})
+
+  #   steps:
+  #     - name: Checkout code
+  #       uses: actions/checkout@v4
+
+  #     - name: Set up Python
+  #       uses: actions/setup-python@v4
+  #       with:
+  #         python-version: ${{ matrix.python_version }}
+
+  #     - name: Setup ArangoDB
+  #       run: |
+  #         chmod +x starter.sh
+  #         ./starter.sh ${{ matrix.arangodb_config }} ${{ matrix.arangodb_license }} ${{ matrix.arangodb_version }}
+
+  #     - name: Install Dependencies
+  #       run: pip install -e .[dev]
+
+  #     - name: List Docker Containers
+  #       run: docker ps -a
+
+  #     - name: Pytest
+  #       run: |
+  #         args=("--host" "localhost" "--port=8529")
+
+  #         if [ ${{ matrix.arangodb_config }} = "cluster" ]; then
+  #           args+=("--cluster" "--port=8539" "--port=8549")
+  #         fi
+
+  #         if [ ${{ matrix.arangodb_license }} = "enterprise" ]; then
+  #           args+=("--enterprise")
+  #         fi
+
+  #         echo "Running pytest with args: ${args[@]}"
+  #         pytest --cov=arango --cov-report=xml "${args[@]}"
+
+  docs:
+    runs-on: ubuntu-latest
+
+    name: Docs
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Fetch all tags and branches
+        run: git fetch --prune --unshallow
+
+      - name: Create ArangoDB Docker container
+        run: >
+          docker create --name arango -p 8529:8529 -e ARANGO_ROOT_PASSWORD=passwd -v "$(pwd)/tests/static/":/tests/static
+          arangodb/arangodb:latest --server.jwt-secret-keyfile=/tests/static/keyfile
+
+      - name: Start ArangoDB Docker container
+        run: docker start arango
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Debug with tmate
+        uses: mxschmitt/action-tmate@v3
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
+
+      - name: Run pre-commit checks
+        uses: pre-commit/[email protected]
+
+      - name: Install dependencies
+        run: pip install .[dev]
+
+      - name: Run Sphinx doctest
+        run: python -m sphinx -b doctest docs docs/_build
+
+      - name: Generate Sphinx HTML
+        run: python -m sphinx -b html -W docs docs/_build

CONTRIBUTING.md

@@ -13,10 +13,10 @@ Run unit tests with coverage:
 py.test --cov=arango --cov-report=html  # Open htmlcov/index.html in your browser
 ```
 
-For a more comprehensive test suite, run:
+To start and ArangoDB instance locally, run:
 
 ```shell
-./tester.sh  # Requires docker
+./starter.sh  # Requires docker
 ```
 
 Build and test documentation:

arango/client.py

@@ -15,7 +15,9 @@
 from arango.exceptions import ServerConnectionError
 from arango.http import DEFAULT_REQUEST_TIMEOUT, DefaultHTTPClient, HTTPClient
 from arango.resolver import (
+    FallbackHostResolver,
     HostResolver,
+    PeriodicHostResolver,
     RandomHostResolver,
     RoundRobinHostResolver,
     SingleHostResolver,
@@ -52,9 +54,9 @@ class ArangoClient:
     :param hosts: Host URL or list of URLs (coordinators in a cluster).
     :type hosts: str | [str]
     :param host_resolver: Host resolver. This parameter used for clusters (when
-        multiple host URLs are provided). Accepted values are "roundrobin" and
-        "random". Any other value defaults to round robin.
-    :type host_resolver: str
+        multiple host URLs are provided). Accepted values are "fallback",
+        "roundrobin", "random" and "periodic". The default value is "fallback".
+    :type host_resolver: str | arango.resolver.HostResolver
     :param resolver_max_tries: Number of attempts to process an HTTP request
         before throwing a ConnectionAbortedError. Must not be lower than the
         number of hosts.
@@ -88,7 +90,7 @@ class ArangoClient:
     def __init__(
         self,
         hosts: Union[str, Sequence[str]] = "http://127.0.0.1:8529",
-        host_resolver: str = "roundrobin",
+        host_resolver: Union[str, HostResolver] = "fallback",
         resolver_max_tries: Optional[int] = None,
         http_client: Optional[HTTPClient] = None,
         serializer: Callable[..., str] = default_serializer,
@@ -106,10 +108,18 @@ def __init__(
 
         if host_count == 1:
             self._host_resolver = SingleHostResolver(1, resolver_max_tries)
+        elif host_resolver == "fallback":
+            self._host_resolver = FallbackHostResolver(host_count, resolver_max_tries)
         elif host_resolver == "random":
             self._host_resolver = RandomHostResolver(host_count, resolver_max_tries)
-        else:
+        elif host_resolver == "roundrobin":
             self._host_resolver = RoundRobinHostResolver(host_count, resolver_max_tries)
+        elif host_resolver == "periodic":
+            self._host_resolver = PeriodicHostResolver(host_count, resolver_max_tries)
+        else:
+            if not isinstance(host_resolver, HostResolver):
+                raise ValueError("Invalid host resolver")
+            self._host_resolver = host_resolver
 
         # Initializes the http client
         self._http = http_client or DefaultHTTPClient(request_timeout=request_timeout)

arango/formatter.py

@@ -1194,6 +1194,12 @@ def format_pregel_job_data(body: Json) -> Json:
     if "useMemoryMaps" in body:
         result["use_memory_maps"] = body["useMemoryMaps"]
 
+    # Introduced in 3.11
+    if "user" in body:
+        result["user"] = body["user"]
+    if "graphLoaded" in body:
+        result["graph_loaded"] = body["graphLoaded"]
+
     return verify_format(body, result)