python-arango-async 1.2.2__tar.gz → 1.2.4__tar.gz

python_arango_async-1.2.4/.circleci/config.yml

@@ -0,0 +1,200 @@
+version: 2.1
+
+executors:
+  python-container:  # used by lint and import-test jobs
+    parameters:
+      python_version:
+        type: string
+        default: "3.14"
+    docker:
+      - image: cimg/python:<< parameters.python_version >>
+    resource_class: arangodb/small-amd64
+  arangodb-container:  # runs integration tests
+    parameters:
+      arangodb_image:
+        type: string
+    docker:
+      - image: << parameters.arangodb_image >>
+        entrypoint: /bin/sh
+        command: -c "while true; do sleep 10; done"
+        user: root
+    resource_class: arangodb/medium-amd64
+
+workflows:
+  ci:
+    jobs:
+      - lint
+      - import-test:
+          name: Imports (Python << matrix.python_version >>)
+          matrix:
+            parameters:
+              python_version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+      - integration-test:
+          name: ArangoDB (enterprise, 3.12 << matrix.arangodb_config >>)
+          matrix:
+            parameters:
+              arangodb_config: ["single", "cluster"]
+              arangodb_image: ["arangodb/enterprise:3.12"]
+              arangodb_conf_version: ["3.12"]
+      - integration-test:
+          name: ArangoDB (enterprise-preview, 4.0-nightly << matrix.arangodb_config >>)
+          matrix:
+            parameters:
+              arangodb_config: ["single", "cluster"]
+              arangodb_image: ["arangodb/enterprise-preview:4.0-nightly"]
+              arangodb_conf_version: ["4.0"]
+
+jobs:
+  lint:
+    executor: python-container
+    steps:
+      - checkout
+      - run:
+          name: Install Dependencies
+          command: python -m pip install .[dev]
+      - run:
+            name: Run black
+            command: black --check --verbose --diff --color --config=pyproject.toml ./arangoasync ./tests/
+      - run:
+          name: Run flake8
+          command: flake8 ./arangoasync ./tests
+      - run:
+          name: Run isort
+          command: isort --check ./arangoasync ./tests
+      - run:
+          name: Run mypy
+          command: mypy ./arangoasync
+  import-test:
+    parameters:
+      python_version:
+        type: string
+    executor:
+      name: python-container
+      python_version: << parameters.python_version >>
+    steps:
+      - checkout
+      - run:
+          name: Install Dependencies
+          command: |
+            python --version
+            python -m pip install .[dev]
+      - run:
+          name: Run Import Tests
+          command: python -m pytest tests/test_imports.py --skip-arango-setup --color=yes --code-highlight=yes
+  integration-test:
+    parameters:
+        arangodb_config:
+            type: string
+        arangodb_image:
+            type: string
+        arangodb_conf_version:
+            type: string
+    executor:
+      name: arangodb-container
+      arangodb_image: << parameters.arangodb_image >>
+    steps:
+      - run:
+          name: Bootstrap CI Tools
+          command: |
+            apk add --no-cache \
+              bash \
+              build-base \
+              ca-certificates \
+              curl \
+              git \
+              jq \
+              openssh-client \
+              openssl-dev \
+              py3-pip \
+              py3-virtualenv \
+              python3 \
+              python3-dev
+      - checkout
+      - run:
+          name: Setup ArangoDB
+          command: |
+            mkdir -p /tests
+            if [ ! -e /tests/static ]; then
+              ln -s "$PWD/tests/static" /tests/static
+            fi
+
+            conf_file="/tests/static/<< parameters.arangodb_config >>-<< parameters.arangodb_conf_version >>.conf"
+            if [ ! -f "$conf_file" ]; then
+              echo "Missing configuration file: $conf_file"
+              exit 1
+            fi
+
+            arangodb --configuration="$conf_file" > arangodb.log 2>&1 &
+            echo "$!" > arangodb.pid
+
+            ports="8529"
+            if [ << parameters.arangodb_config >> = "cluster" ]; then
+              ports="$ports 8539 8549"
+            fi
+
+            for port in $ports; do
+              echo "Waiting for ArangoDB at http://localhost:$port/_api/version"
+              for attempt in $(seq 1 120); do
+                if curl --fail --silent --show-error \
+                    --user root:passwd \
+                    "http://localhost:$port/_api/version" | jq; then
+                  break
+                fi
+
+                if ! kill -0 "$(cat arangodb.pid)" 2>/dev/null; then
+                  echo "ArangoDB process exited before port $port became ready"
+                  exit 1
+                fi
+
+                if [ "$attempt" -eq 120 ]; then
+                  echo "Timed out waiting for ArangoDB on port $port"
+                  exit 1
+                fi
+
+                sleep 1
+              done
+            done
+      - run:
+          name: Show ArangoDB Logs
+          command: tail -n 1000 arangodb.log
+          when: always
+      - run:
+          name: Setup Python
+          shell: /bin/bash -eo pipefail
+          command: |
+            python3 --version
+            python3 -m virtualenv .venv
+            source .venv/bin/activate
+            python --version
+            python -m pip --version
+      - run:
+          name: Install Dependencies
+          shell: /bin/bash -eo pipefail
+          command: |
+            source .venv/bin/activate
+            python -m pip install -e .[dev]
+      - run:
+          name: Run pytest
+          shell: /bin/bash -eo pipefail
+          command: |
+            mkdir test-results
+            mkdir htmlcov
+
+            source .venv/bin/activate
+
+            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
+
+            echo "Running pytest with args: ${args[@]}"
+            pytest tests --cov=arangoasync --cov-report=html:htmlcov --color=yes --code-highlight=yes "${args[@]}"
+      - store_artifacts:
+          path: htmlcov
+          destination: coverage-report
+      - store_artifacts:
+          path: test-results
+      - store_artifacts:
+          path: arangodb.log
+      - store_test_results:
+          path: test-results

{python_arango_async-1.2.2 → python_arango_async-1.2.4}/.github/workflows/codeql.yaml

@@ -14,10 +14,10 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v4
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v4

{python_arango_async-1.2.2 → python_arango_async-1.2.4}/.github/workflows/docs.yaml

@@ -11,13 +11,13 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Fetch all tags and branches
         run: git fetch --prune --unshallow
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v7
         with:
           python-version: '3.12'
 

{python_arango_async-1.2.2 → python_arango_async-1.2.4}/.github/workflows/pypi.yaml

@@ -10,12 +10,12 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
           fetch-tags: true
 
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 
@@ -31,10 +31,10 @@ jobs:
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_TEST_TOKEN }}
-        run: twine upload --repository testpypi dist/*
+        run: twine upload --verbose --repository testpypi dist/*
 
       - name: Publish to PyPI
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
-        run: twine upload --repository pypi dist/*
+        run: twine upload --verbose --repository pypi dist/*

{python_arango_async-1.2.2 → python_arango_async-1.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-arango-async
-Version: 1.2.2
+Version: 1.2.4
 Summary: Async Python Driver for ArangoDB
 Author-email: Alexandru Petenchea <alexandru.petenchea@arangodb.com>, Anthony Mahanna <anthony.mahanna@arangodb.com>
 Maintainer-email: Alexandru Petenchea <alexandru.petenchea@arangodb.com>, Anthony Mahanna <anthony.mahanna@arangodb.com>
@@ -26,7 +26,7 @@ Requires-Dist: multidict>=6.0
 Requires-Dist: pyjwt>=2.10.0
 Provides-Extra: dev
 Requires-Dist: aiofiles>=24.1.0; extra == "dev"
-Requires-Dist: black==26.1.0; extra == "dev"
+Requires-Dist: black==26.3.1; extra == "dev"
 Requires-Dist: flake8==7.3.0; extra == "dev"
 Requires-Dist: isort>=5.10.1; extra == "dev"
 Requires-Dist: mypy==1.15.0; extra == "dev"
@@ -169,7 +169,7 @@ async def main():
         # 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' }
+            OPTIONS { order: 'bfs', uniqueVertices: 'global' }
             RETURN {vertex: v, edge: e, path: p}
             """
 

{python_arango_async-1.2.2 → python_arango_async-1.2.4}/README.md

@@ -127,7 +127,7 @@ async def main():
         # 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' }
+            OPTIONS { order: 'bfs', uniqueVertices: 'global' }
             RETURN {vertex: v, edge: e, path: p}
             """
 

{python_arango_async-1.2.2 → python_arango_async-1.2.4}/arangoasync/aql.py

@@ -678,6 +678,9 @@ class AQL:
     async def functions(self, namespace: Optional[str] = None) -> Result[Jsons]:
         """List the registered used-defined AQL functions.
 
+        Warning:
+            AQL User Functions are no longer available in ArangoDB 4.0.
+
         Args:
             namespace (str | None): Returns all registered AQL user functions from
                 the specified namespace.
@@ -718,6 +721,9 @@ class AQL:
     ) -> Result[Json]:
         """Registers a user-defined AQL function (UDF) written in JavaScript.
 
+        Warning:
+            AQL User Functions are no longer available in ArangoDB 4.0.
+
         Args:
             name (str): Name of the function.
             code (str): JavaScript code of the function.
@@ -756,6 +762,9 @@ class AQL:
     ) -> Result[Json]:
         """Remove a user-defined AQL function.
 
+        Warning:
+            AQL User Functions are no longer available in ArangoDB 4.0.
+
         Args:
             name (str): Name of the function.
             group (bool | None): If set to `True`, the function name is treated

{python_arango_async-1.2.2 → python_arango_async-1.2.4}/arangoasync/cluster.py

@@ -64,6 +64,10 @@ class Cluster:
     async def statistics(self, db_server: str) -> Result[Json]:
         """Queries the statistics of the given DB-Server.
 
+        Warning:
+            DB-Server statistics are no longer available in ArangoDB 4.0.
+            Use :meth:`arangoasync.database.Database.metrics` instead.
+
         Args:
             db_server (str): The ID of the DB-Server.
 

{python_arango_async-1.2.2 → python_arango_async-1.2.4}/arangoasync/collection.py

@@ -194,24 +194,49 @@ class Collection(Generic[T, U, V]):
 
         return doc_id
 
-    def _build_filter_conditions(self, filters: Optional[Json]) -> str:
+    @staticmethod
+    def _build_attribute_expression(field: str, prefix: str, bind_vars: Json) -> str:
+        """Build a bind-safe AQL document attribute expression."""
+        bind_vars[prefix] = field
+        field_access = f"doc[@{prefix}]"
+
+        if "." not in field:
+            return field_access
+
+        nested_access = "doc"
+        for field_index, field_part in enumerate(field.split(".")):
+            field_var = f"{prefix}_{field_index}"
+            bind_vars[field_var] = field_part
+            nested_access += f"[@{field_var}]"
+
+        return f"(HAS(doc, @{prefix}) ? {field_access} : {nested_access})"
+
+    def _build_filter_conditions(self, filters: Optional[Json]) -> tuple[str, Json]:
         """Build filter conditions for an AQL query.
 
         Args:
             filters (dict | None): Document filters.
 
         Returns:
-            str: The complete AQL filter condition.
+            tuple: The complete AQL filter condition and its bind variables.
         """
         if not filters:
-            return ""
+            return "", {}
 
         conditions = []
-        for k, v in filters.items():
-            field = k if "." in k else f"`{k}`"
-            conditions.append(f"doc.{field} == {self.serializer.dumps(v)}")
+        bind_vars: Json = {}
+        for filter_index, (field, value) in enumerate(filters.items()):
+            field_access = self._build_attribute_expression(
+                field,
+                f"filter_field_{filter_index}",
+                bind_vars,
+            )
 
-        return "FILTER " + " AND ".join(conditions)
+            value_var = f"filter_value_{filter_index}"
+            bind_vars[value_var] = value
+            conditions.append(f"{field_access} == @{value_var}")
+
+        return "FILTER " + " AND ".join(conditions), bind_vars
 
     @staticmethod
     def _is_none_or_int(obj: Any) -> bool:
@@ -259,24 +284,30 @@ class Collection(Generic[T, U, V]):
                 raise SortValidationError("'sort_order' must be either 'ASC' or 'DESC'")
 
     @staticmethod
-    def _build_sort_expression(sort: Optional[Jsons]) -> str:
+    def _build_sort_expression(sort: Optional[Jsons]) -> tuple[str, Json]:
         """Build a sort condition for an AQL query.
 
         Args:
             sort (list | None): Document sort parameters.
 
         Returns:
-            str: The complete AQL sort condition.
+            tuple: The complete AQL sort condition and its bind variables.
         """
         if not sort:
-            return ""
+            return "", {}
 
         sort_chunks = []
-        for sort_param in sort:
-            chunk = f"doc.{sort_param['sort_by']} {sort_param['sort_order']}"
+        bind_vars: Json = {}
+        for sort_index, sort_param in enumerate(sort):
+            field_access = Collection._build_attribute_expression(
+                sort_param["sort_by"],
+                f"sort_field_{sort_index}",
+                bind_vars,
+            )
+            chunk = f"{field_access} {sort_param['sort_order'].upper()}"
             sort_chunks.append(chunk)
 
-        return "SORT " + ", ".join(sort_chunks)
+        return "SORT " + ", ".join(sort_chunks), bind_vars
 
     @property
     def name(self) -> str:
@@ -1025,14 +1056,20 @@ class Collection(Generic[T, U, V]):
 
         skip = skip if skip is not None else 0
         limit = limit if limit is not None else "null"
+        filter_conditions, filter_bind_vars = self._build_filter_conditions(filters)
+        sort_expression, sort_bind_vars = self._build_sort_expression(sort)
         query = f"""
             FOR doc IN @@collection
-                {self._build_filter_conditions(filters)}
+                {filter_conditions}
                 LIMIT {skip}, {limit}
-                {self._build_sort_expression(sort)}
+                {sort_expression}
                 RETURN doc
         """
-        bind_vars = {"@collection": self.name}
+        bind_vars = {
+            "@collection": self.name,
+            **filter_bind_vars,
+            **sort_bind_vars,
+        }
         data: Json = {"query": query, "bindVars": bind_vars, "count": True}
         headers: RequestHeaders = {}
         if allow_dirty_read is not None:
@@ -1095,9 +1132,10 @@ class Collection(Generic[T, U, V]):
             raise ValueError("limit parameter must be a non-negative int")
 
         sync = f", waitForSync: {wait_for_sync}" if wait_for_sync is not None else ""
+        filter_conditions, filter_bind_vars = self._build_filter_conditions(filters)
         query = f"""
             FOR doc IN @@collection
-                {self._build_filter_conditions(filters)}
+                {filter_conditions}
                 {f"LIMIT {limit}" if limit is not None else ""}
                 UPDATE doc WITH @body IN @@collection
                 OPTIONS {{ keepNull: @keep_none, mergeObjects: @merge {sync} }}
@@ -1107,6 +1145,7 @@ class Collection(Generic[T, U, V]):
             "body": body,
             "keep_none": keep_none,
             "merge": merge_objects,
+            **filter_bind_vars,
         }
         data = {"query": query, "bindVars": bind_vars}
 
@@ -1151,9 +1190,10 @@ class Collection(Generic[T, U, V]):
             raise ValueError("limit parameter must be a non-negative int")
 
         sync = f"waitForSync: {wait_for_sync}" if wait_for_sync is not None else ""
+        filter_conditions, filter_bind_vars = self._build_filter_conditions(filters)
         query = f"""
             FOR doc IN @@collection
-                {self._build_filter_conditions(filters)}
+                {filter_conditions}
                 {f"LIMIT {limit}" if limit is not None else ""}
                 REPLACE doc WITH @body IN @@collection
                 {f"OPTIONS {{ {sync} }}" if sync else ""}
@@ -1161,6 +1201,7 @@ class Collection(Generic[T, U, V]):
         bind_vars = {
             "@collection": self.name,
             "body": body,
+            **filter_bind_vars,
         }
         data = {"query": query, "bindVars": bind_vars}
 
@@ -1203,14 +1244,15 @@ class Collection(Generic[T, U, V]):
             raise ValueError("limit parameter must be a non-negative int")
 
         sync = f"waitForSync: {wait_for_sync}" if wait_for_sync is not None else ""
+        filter_conditions, filter_bind_vars = self._build_filter_conditions(filters)
         query = f"""
             FOR doc IN @@collection
-                {self._build_filter_conditions(filters)}
+                {filter_conditions}
                 {f"LIMIT {limit}" if limit is not None else ""}
                 REMOVE doc IN @@collection
                 {f"OPTIONS {{ {sync} }}" if sync else ""}
         """  # noqa: E201 E202
-        bind_vars = {"@collection": self.name}
+        bind_vars = {"@collection": self.name, **filter_bind_vars}
         data = {"query": query, "bindVars": bind_vars}
 
         request = Request(

{python_arango_async-1.2.2 → python_arango_async-1.2.4}/arangoasync/database.py

@@ -234,6 +234,9 @@ class Database:
     def foxx(self) -> Foxx:
         """Return Foxx API wrapper.
 
+        Warning:
+            Foxx microservice features are no longer available in ArangoDB 4.0.
+
         Returns:
             arangoasync.foxx.Foxx: Foxx API wrapper.
         """
@@ -2429,6 +2432,9 @@ class Database:
     async def tasks(self) -> Result[Jsons]:
         """Fetches all existing tasks from the server.
 
+        Warning:
+            Tasks are no longer available in ArangoDB 4.0.
+
         Returns:
             list: List of currently active server tasks.
 
@@ -2451,6 +2457,9 @@ class Database:
     async def task(self, task_id: str) -> Result[Json]:
         """Return the details of an active server task.
 
+        Warning:
+            Tasks are no longer available in ArangoDB 4.0.
+
         Args:
             task_id (str) -> Server task ID.
 
@@ -2484,6 +2493,9 @@ class Database:
     ) -> Result[Json]:
         """Create a new task.
 
+        Warning:
+            Tasks are no longer available in ArangoDB 4.0.
+
         Args:
             command (str): The JavaScript code to be executed.
             task_id (str | None): Optional task ID. If not provided, the server will
@@ -2542,6 +2554,9 @@ class Database:
     ) -> Result[bool]:
         """Delete a server task.
 
+        Warning:
+            Tasks are no longer available in ArangoDB 4.0.
+
         Args:
             task_id (str): Task ID.
             ignore_missing (bool): If `True`, do not raise an exception if the
@@ -2909,6 +2924,9 @@ class Database:
     async def reload_routing(self) -> None:
         """Reload the routing information.
 
+        Warning:
+            Route reloading is no longer available in ArangoDB 4.0.
+
         Raises:
             ServerReloadRoutingError: If the operation fails.
 
@@ -2926,6 +2944,9 @@ class Database:
     async def echo(self, body: Optional[Json] = None) -> Result[Json]:
         """Return an object with the servers request information.
 
+        Warning:
+            Request echoing is no longer available in ArangoDB 4.0.
+
         Args:
             body (dict | None): Optional body of the request.
 
@@ -2952,6 +2973,9 @@ class Database:
     async def execute(self, command: str) -> Result[Any]:
         """Execute raw Javascript command on the server.
 
+        Warning:
+            Javascript command execution is no longer available in ArangoDB 4.0.
+
         Args:
             command (str): Javascript command to execute.
 
@@ -3004,7 +3028,7 @@ class Database:
             ServerMetricsError: If the operation fails.
 
         References:
-            - `metrics-api-v2 <https://docs.arango.ai/arangodb/stable/develop/http-api/monitoring/metrics/#metrics-api-v2>`__
+            - `metrics-api <https://docs.arango.ai/arangodb/stable/develop/http-api/monitoring/metrics/#metrics-api>`__
         """  # noqa: E501
         params: Params = {}
         if server_id is not None:
@@ -3012,7 +3036,7 @@ class Database:
 
         request = Request(
             method=Method.GET,
-            endpoint="/_admin/metrics/v2",
+            endpoint="/_admin/metrics",
             params=params,
         )
 

{python_arango_async-1.2.2 → python_arango_async-1.2.4}/arangoasync/foxx.py

@@ -34,7 +34,11 @@ from arangoasync.typings import Json, Jsons, Params, RequestHeaders
 
 
 class Foxx:
-    """Foxx API wrapper."""
+    """Foxx API wrapper.
+
+    Warning:
+        Foxx microservice features are no longer available in ArangoDB 4.0.
+    """
 
     def __init__(self, executor: ApiExecutor) -> None:
         self._executor = executor