python-arango-async 1.2.3__tar.gz → 1.2.5__tar.gz

python_arango_async-1.2.5/.circleci/config.yml

@@ -0,0 +1,207 @@
+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 (core-preview, 4.0-nightly << matrix.arangodb_config >>)
+          matrix:
+            parameters:
+              arangodb_config: [ "single", "cluster" ]
+              arangodb_image: [ "arangodb/core-preview:4.0-nightly" ]
+              arangodb_conf_version: [ "4.0" ]
+      - integration-test:
+          name: ArangoDB (enterprise-preview, 3.12-nightly << matrix.arangodb_config >>)
+          matrix:
+            parameters:
+              arangodb_config: ["single", "cluster"]
+              arangodb_image: ["arangodb/enterprise-preview:3.12-nightly"]
+              arangodb_conf_version: ["3.12"]
+
+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.3 → python_arango_async-1.2.5}/.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.3 → python_arango_async-1.2.5}/.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.3 → python_arango_async-1.2.5}/.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"
 

{python_arango_async-1.2.3 → python_arango_async-1.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-arango-async
-Version: 1.2.3
+Version: 1.2.5
 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.3.1; extra == "dev"
+Requires-Dist: black==26.5.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"

{python_arango_async-1.2.3 → python_arango_async-1.2.5}/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.3 → python_arango_async-1.2.5}/arangoasync/replication.py

@@ -2,6 +2,7 @@ __all__ = ["Replication"]
 
 
 from typing import Optional
+from warnings import warn
 
 from arangoasync.exceptions import (
     ReplicationApplierConfigError,
@@ -195,7 +196,9 @@ class Replication:
         return await self._executor.execute(request, response_handler)
 
     async def applier_config(self) -> Result[Json]:
-        """Return the configuration of the replication applier.
+        """**Removed** in ArangoDB v3.12.10.
+
+        Return the configuration of the replication applier.
 
         Returns:
             dict: Configuration of the replication applier.
@@ -206,6 +209,9 @@ class Replication:
         References:
            - `get-the-replication-applier-configuration <https://docs.arango.ai/arangodb/stable/develop/http-api/replication/replication-applier/#get-the-replication-applier-configuration>`__
         """  # noqa: E501
+        m = "/_api/replication/applier-config was removed in ArangoDB v3.12.10."
+        warn(m, DeprecationWarning, stacklevel=2)
+
         request = Request(
             method=Method.GET,
             endpoint="/_api/replication/applier-config",
@@ -220,7 +226,9 @@ class Replication:
         return await self._executor.execute(request, response_handler)
 
     async def applier_state(self) -> Result[Json]:
-        """Return the state of the replication applier.
+        """**Removed** in ArangoDB v3.12.10.
+
+        Return the state of the replication applier.
 
         Returns:
             dict: State of the replication applier.
@@ -231,6 +239,9 @@ class Replication:
         References:
             - `get-the-replication-applier-state <https://docs.arango.ai/arangodb/stable/develop/http-api/replication/replication-applier/#get-the-replication-applier-state>`__
         """  # noqa: E501
+        m = "/_api/replication/applier-state was removed in ArangoDB v3.12.10."
+        warn(m, DeprecationWarning, stacklevel=2)
+
         request = Request(
             method=Method.GET,
             endpoint="/_api/replication/applier-state",
@@ -245,7 +256,9 @@ class Replication:
         return await self._executor.execute(request, response_handler)
 
     async def server_id(self) -> Result[str]:
-        """Return the current server's ID.
+        """**Removed** in ArangoDB v3.12.10.
+
+        Return the current server's ID.
 
         Returns:
             str: Server ID.
@@ -256,6 +269,9 @@ class Replication:
         References:
             - `get-the-replication-server-id <https://docs.arango.ai/arangodb/stable/develop/http-api/replication/other-replication-commands/#get-the-replication-server-id>`__
         """  # noqa: E501
+        m = "/_api/replication/server-id was removed in ArangoDB v3.12.10."
+        warn(m, DeprecationWarning, stacklevel=2)
+
         request = Request(
             method=Method.GET,
             endpoint="/_api/replication/server-id",

{python_arango_async-1.2.3 → python_arango_async-1.2.5}/arangoasync/typings.py

@@ -1060,6 +1060,10 @@ class IndexProperties(JsonWrapper):
     def legacy_polygons(self) -> Optional[bool]:
         return self._data.get("legacyPolygons")
 
+    @property
+    def figures(self) -> Optional[Json]:
+        return self._data.get("figures")
+
     @property
     def estimates(self) -> Optional[bool]:
         return self._data.get("estimates")
@@ -1140,6 +1144,10 @@ class IndexProperties(JsonWrapper):
     def training_state(self) -> Optional[str]:
         return self._data.get("trainingState")
 
+    @property
+    def shards(self) -> Optional[Json]:
+        return self._data.get("shards")
+
     @staticmethod
     def compatibility_formatter(data: Json) -> Json:
         """python-arango compatibility formatter."""
@@ -1170,6 +1178,8 @@ class IndexProperties(JsonWrapper):
             result["storedValues"] = data["storedValues"]
         if "legacyPolygons" in data:
             result["legacyPolygons"] = data["legacyPolygons"]
+        if "figures" in data:
+            result["figures"] = data["figures"]
         if "estimates" in data:
             result["estimates"] = data["estimates"]
         if "analyzer" in data:
@@ -1202,6 +1212,8 @@ class IndexProperties(JsonWrapper):
             result["error_message"] = data["errorMessage"]
         if "trainingState" in data:
             result["training_state"] = data["trainingState"]
+        if "shards" in data:
+            result["shards"] = data["shards"]
         return result
 
     def format(self, formatter: Optional[Formatter] = None) -> Json:

python_arango_async-1.2.5/arangoasync/version.py

@@ -0,0 +1 @@
+__version__ = "1.2.5"

{python_arango_async-1.2.3 → python_arango_async-1.2.5}/docs/indexes.rst

@@ -50,4 +50,43 @@ on fields ``_from`` and ``_to``. For more information on indexes, refer to
         # Delete the last index from the collection.
         await cities.delete_index(index["id"])
 
+        # Insert documents with vector embeddings.
+        await cities.insert_many([
+            {
+                "_key": f"city{i}",
+                "continent": f"continent{i}",
+                "country": f"country{i}",
+                "population": i,
+                "coordinates": [float(i % 180), float(i % 90)],
+                "embedding": [float(i), float(i % 7), float(i % 11), 1.0],
+            }
+            for i in range(100)
+        ])
+
+        # Let ArangoDB determine the number of vector-index centroids.
+        vector_index = await cities.add_index(
+            type="vector",
+            fields=["embedding"],
+            options={
+                "name": "vector_index",
+                "params": {
+                    "metric": "cosine",
+                    "dimension": 4,
+                },
+            },
+        )
+
+        # Index creation may succeed even if vector training fails.
+        if vector_index.training_state != "ready":
+            raise RuntimeError(
+                vector_index.error_message or "Vector index is not ready"
+            )
+
+Omitted or scaling-object ``nLists``, ``numberOfDocsPerCentroid``, factory
+placeholders such as ``IVF{},Flat``, and successful-but-unusable creation
+behavior require ArangoDB 3.12.10 or later. A successful creation response
+means that the index exists, but callers should check ``training_state`` before
+using it. If training fails permanently, the state is ``"unusable"`` and
+``error_message`` describes the failure.
+
 See :class:`arangoasync.collection.StandardCollection` for API specification.

{python_arango_async-1.2.3 → python_arango_async-1.2.5}/pyproject.toml

@@ -49,7 +49,7 @@ version = { attr = "arangoasync.version.__version__" }
 [project.optional-dependencies]
 dev = [
     "aiofiles>=24.1.0",
-    "black==26.3.1",
+    "black==26.5.1",
     "flake8==7.3.0",
     "isort>=5.10.1",
     "mypy==1.15.0",

{python_arango_async-1.2.3 → python_arango_async-1.2.5}/python_arango_async.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-arango-async
-Version: 1.2.3
+Version: 1.2.5
 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.3.1; extra == "dev"
+Requires-Dist: black==26.5.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"

{python_arango_async-1.2.3 → python_arango_async-1.2.5}/python_arango_async.egg-info/SOURCES.txt

@@ -75,6 +75,8 @@ python_arango_async.egg-info/PKG-INFO
 python_arango_async.egg-info/SOURCES.txt
 python_arango_async.egg-info/dependency_links.txt
 python_arango_async.egg-info/requires.txt
+python_arango_async.egg-info/scm_file_list.json
+python_arango_async.egg-info/scm_version.json
 python_arango_async.egg-info/top_level.txt
 tests/__init__.py
 tests/conftest.py
@@ -94,6 +96,7 @@ tests/test_document.py
 tests/test_foxx.py
 tests/test_graph.py
 tests/test_http.py
+tests/test_imports.py
 tests/test_resolver.py
 tests/test_task.py
 tests/test_transaction.py

{python_arango_async-1.2.3 → python_arango_async-1.2.5}/python_arango_async.egg-info/requires.txt

@@ -5,7 +5,7 @@ pyjwt>=2.10.0
 
 [dev]
 aiofiles>=24.1.0
-black==26.3.1
+black==26.5.1
 flake8==7.3.0
 isort>=5.10.1
 mypy==1.15.0