python-arango 8.3.5__tar.gz → 8.3.6__tar.gz

{python_arango-8.3.5 → python_arango-8.3.6}/.circleci/config.yml

@@ -30,11 +30,18 @@ workflows:
             parameters:
               python_version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
       - integration-test:
-          name: ArangoDB (enterprise, 3.12 << matrix.arangodb_config >>)
+          name: ArangoDB (enterprise, 3.12.10 << matrix.arangodb_config >>)
           matrix:
             parameters:
               arangodb_config: ["single", "cluster"]
-              arangodb_image: ["arangodb/enterprise:3.12"]
+              arangodb_image: ["arangodb/enterprise:3.12.10"]
+              arangodb_conf_version: ["3.12"]
+      - integration-test:
+          name: ArangoDB (enterprise, 3.12.9 << matrix.arangodb_config >>)
+          matrix:
+            parameters:
+              arangodb_config: ["single", "cluster"]
+              arangodb_image: ["arangodb/enterprise:3.12.9"]
               arangodb_conf_version: ["3.12"]
       - integration-test:
           name: ArangoDB (core-preview, 4.0-nightly << matrix.arangodb_config >>)

python_arango-8.3.6/.github/workflows/pypi.yaml

@@ -0,0 +1,66 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+          persist-credentials: false
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: python -m pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    needs: testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

python_arango-8.3.6/AGENTS.md

@@ -0,0 +1,89 @@
+# Quickstart
+
+python-arango is a Python driver for ArangoDB. Run the commands below from the
+repository root.
+
+## Repository layout
+
+- `arango/`: driver implementation, public APIs, and type annotations.
+- `tests/`: pytest tests; `conftest.py` defines database fixtures and CLI options.
+- `tests/static/`: server configurations and test data used by `starter.sh`.
+- `docs/`: Sphinx documentation in reStructuredText.
+- `pyproject.toml`, `setup.cfg`, `.pre-commit-config.yaml`: packaging and tooling.
+- `.circleci/`, `.github/workflows/`: CI checks, documentation, and publishing.
+
+## Development setup
+
+Use Python 3.10 or newer. Create a virtual environment, or use an existing one:
+
+```bash
+python3 -m venv .venv               # Create an isolated Python environment.
+source .venv/bin/activate           # Use its interpreter and tools.
+python -m pip install -e '.[dev]'   # Install the editable driver and dev tools.
+pre-commit install                  # Enable checks before each commit.
+```
+
+Examples use `python` from the activated environment. If it is unavailable on
+PATH, invoke your environment's interpreter directly.
+
+## Local cluster and tests
+
+The starter requires Docker, Bash, `wget`, and `jq`. To replace an existing test
+container, run `docker stop arango` and `docker rm arango` first.
+
+```bash
+version="latest"  # Or pin a supported version, such as 3.12.10.
+./starter.sh cluster enterprise "$version"  # Start a local test cluster.
+python -m pytest --cluster  # Run the full suite against the cluster.
+# Run one test while developing a document change.
+python -m pytest --cluster tests/test_document.py::test_document_insert
+# Generate an HTML coverage report.
+python -m pytest --cluster --cov=arango --cov-report=html
+```
+
+Defaults are `127.0.0.1:8529`, user `root`, password `passwd`, and JWT secret
+`secret`, matching the starter configuration. Override them with `--host`,
+`--port`, `--root`, `--password`, and `--secret`. Use a disposable development
+database: tests create and delete databases, users, jobs, and backups. If a
+sandbox blocks localhost access, rerun with the required sandbox permission.
+
+For a single server, use `./starter.sh single enterprise "$version"` and omit
+`--cluster`. Import tests can run without ArangoDB:
+
+```bash
+python -m pytest tests/test_imports.py --skip-arango-setup  # Check imports offline.
+```
+
+## Style and documentation
+
+Run the configured hooks for formatting, import ordering, linting, and type
+checks. Build and test documentation separately:
+
+```bash
+pre-commit run --all-files  # Run hooks; formatters may modify files.
+python -m sphinx -b html docs docs/_build  # Build the HTML documentation.
+python -m sphinx -b doctest docs docs/_build  # Test documentation examples.
+```
+
+The Sphinx doctests require a running ArangoDB server. Open
+`docs/_build/index.html` for the HTML documentation or `htmlcov/index.html` for
+the coverage report.
+
+## Changes and pull requests
+
+- Agents must work on a branch other than `main`; never commit directly to `main`.
+  Check the current branch before editing or committing. If on `main` or a
+  detached HEAD, create a branch first:
+
+  ```bash
+  git branch --show-current  # Check the current branch.
+  git switch -c fix/describe-change  # Choose a descriptive branch name.
+  ```
+
+- Preserve public API compatibility unless a breaking change is intentional.
+- Follow existing code patterns, type annotations, and Sphinx docstrings.
+- Add regression tests for fixes and tests for new behavior; update user documentation.
+- Run relevant tests and checks; report anything skipped and why.
+- Keep test coverage up and squash changes into one commit for submission.
+- Use present-tense commit messages, such as `Fix cursor retry`.
+- Explain what changed, why, and any compatibility impact in the pull request.

{python_arango-8.3.5/python_arango.egg-info → python_arango-8.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-arango
-Version: 8.3.5
+Version: 8.3.6
 Summary: Python Driver for ArangoDB
 Author-email: Joohwan Oh <joohwan.oh@outlook.com>
 Maintainer-email: Joohwan Oh <joohwan.oh@outlook.com>, Alexandru Petenchea <alex.petenchea@gmail.com>, Anthony Mahanna <anthony.mahanna@arangodb.com>

python_arango-8.3.6/arango/version.py

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

{python_arango-8.3.5 → python_arango-8.3.6}/docs/index.rst

@@ -94,7 +94,6 @@ Development
 .. toctree::
     :maxdepth: 1
 
-    contributing
     specs
 
 .. _ArangoDB: https://www.arangodb.com

{python_arango-8.3.5 → python_arango-8.3.6}/docs/indexes.rst

@@ -88,7 +88,7 @@ on fields ``_from`` and ``_to``. For more information on indexes, refer to
         },
     })
 
-    # Index creation may succeed even if vector training fails.
+    # Index creation may succeed even if there is insufficient training data.
     if vector_index.get('trainingState') != 'ready':
         raise RuntimeError(
             vector_index.get('errorMessage', 'Vector index is not ready')
@@ -98,7 +98,10 @@ 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 ``trainingState`` before
-using it. If training fails permanently, the state is ``"unusable"`` and
-``errorMessage`` describes the failure.
+using it. If there is insufficient data to train the index, the state is
+``"unusable"`` and ``errorMessage`` describes the failure. Invalid index
+definitions, such as an ``nLists`` value that disagrees with the number of
+centroids in the factory string, are rejected during creation with
+``IndexCreateError`` and no index is created.
 
 See :ref:`StandardCollection` for API specification.

{python_arango-8.3.5 → python_arango-8.3.6/python_arango.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-arango
-Version: 8.3.5
+Version: 8.3.6
 Summary: Python Driver for ArangoDB
 Author-email: Joohwan Oh <joohwan.oh@outlook.com>
 Maintainer-email: Joohwan Oh <joohwan.oh@outlook.com>, Alexandru Petenchea <alex.petenchea@gmail.com>, Anthony Mahanna <anthony.mahanna@arangodb.com>

{python_arango-8.3.5 → python_arango-8.3.6}/python_arango.egg-info/SOURCES.txt

@@ -1,7 +1,7 @@
 .gitignore
 .pre-commit-config.yaml
 .readthedocs.yaml
-CONTRIBUTING.md
+AGENTS.md
 LICENSE
 MANIFEST.in
 README.md
@@ -9,6 +9,7 @@ pyproject.toml
 setup.cfg
 setup.py
 starter.sh
+todo.md
 .circleci/config.yml
 .github/workflows/codeql.yaml
 .github/workflows/docs.yaml
@@ -55,7 +56,6 @@ docs/cluster.rst
 docs/collection.rst
 docs/compression.rst
 docs/conf.py
-docs/contributing.rst
 docs/cursor.rst
 docs/database.rst
 docs/document.rst

{python_arango-8.3.5 → python_arango-8.3.6}/python_arango.egg-info/scm_file_list.json

@@ -7,7 +7,7 @@
     ".gitignore",
     ".pre-commit-config.yaml",
     ".readthedocs.yaml",
-    "CONTRIBUTING.md",
+    "AGENTS.md",
     "LICENSE",
     "MANIFEST.in",
     "README.md",
@@ -53,7 +53,6 @@
     "docs/collection.rst",
     "docs/compression.rst",
     "docs/conf.py",
-    "docs/contributing.rst",
     "docs/cursor.rst",
     "docs/database.rst",
     "docs/document.rst",
@@ -124,6 +123,7 @@
     "tests/test_transaction.py",
     "tests/test_user.py",
     "tests/test_view.py",
-    "tests/test_wal.py"
+    "tests/test_wal.py",
+    "todo.md"
   ]
 }

python_arango-8.3.6/python_arango.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "8.3.6",
+  "distance": 0,
+  "node": "gc019d8643272db4621ffd7d20795a387618705a8",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-04"
+}

{python_arango-8.3.5 → python_arango-8.3.6}/starter.sh

@@ -4,15 +4,16 @@
 # Useful for testing the python-arango driver against a local ArangoDB setup.
 
 # Usage:
-#   ./starter.sh [single|cluster] [community|enterprise|enterprise-preview] [version]
+#   ./starter.sh [single|cluster] [core-preview|enterprise|enterprise-preview] [version]
 #   ./starter.sh [single|cluster] [image[:tag]]
 # Example:
 #   ./starter.sh cluster enterprise 3.12.4
 #   ./starter.sh single core-preview 4.0-nightly
 #   ./starter.sh single arangodb/enterprise-preview:3.12-nightly
+# Defaults: single server, enterprise image, latest version.
 
 setup="${1:-single}"
-image="${2:-community}"
+image="${2:-enterprise}"
 version="${3:-latest}"
 
 extra_ports=""
@@ -35,14 +36,14 @@ if [[ "$image" == */* ]]; then
     else
         image_ref="$image:$version"
     fi
-elif [ "$image" == "community" ]; then
-    image_ref="arangodb/arangodb:$version"
+elif [ "$image" == "core-preview" ]; then
+    image_ref="arangodb/core-preview:$version"
 elif [ "$image" == "enterprise" ]; then
     image_ref="arangodb/enterprise:$version"
 elif [ "$image" == "enterprise-preview" ]; then
     image_ref="arangodb/enterprise-preview:$version"
 else
-    echo "Invalid argument. Please provide 'community', 'enterprise', 'enterprise-preview', or a full image reference."
+    echo "Invalid argument. Please provide 'core-preview', 'enterprise', 'enterprise-preview', or a full image reference."
     exit 1
 fi
 

python_arango-8.3.6/todo.md

@@ -0,0 +1,397 @@
+# Painpoints to address with the next major release
+
+## JWT authentication
+
+The driver supports JWTs, but renewal is reactive, unsynchronized, and can fail for expired tokens. Application-managed
+tokens can incorrectly enter credential-based refresh. Reliable renewal needs clearer authentication ownership, while
+changing the Basic authentication default requires a migration path.
+
+a. Define disabled, driver-managed, and application-managed authentication modes. Make JWT the default, allow an initial
+   JWT alongside credentials in driver-managed mode, and document migration.
+
+b. Add proactive renewal with bounded retries and one acquisition shared by concurrent requests. Define renewal worker
+   ownership and cleanup.
+
+c. Fix expired-token recovery and retry rejected requests once. Reuse newer tokens after delayed 401s, and never refresh
+   application-managed tokens using credentials.
+
+d. Test expiration, concurrent renewal, failed acquisition, and application-managed replacement. Correct the expiry test
+   to update both the token and its recorded expiration.
+
+e. Add `db.update_jwt(token)` for application-managed tokens, delegating to the connection's token replacement. Scope
+   updates to that authentication context, not the entire ArangoClient: separate database connections can use different
+   credentials. Make replacement safe during concurrent requests, without recreating connections or triggering renewal.
+   Subsequent requests through the database and its existing collection wrappers must use the replacement token;
+   requests already in progress may finish with the previous token. Other authentication contexts remain unaffected.
+
+f. Keep renewal state per authentication context. Track contexts created by the client so `client.close()` stops all
+   associated renewal activity, including preventing in-progress renewals from scheduling new tasks after shutdown.
+
+`alice_db.update_jwt(new_alice_token)` is a proposed public API; the current equivalent is
+`alice_db.conn.set_token(new_alice_token)`. A separate `bob_db` connection remains unaffected, even when both were
+created through the same client. The specification's "root instance" should therefore mean the authentication context
+for this operation, rather than requiring a single client-wide token.
+
+## Concurrency
+
+Using the driver across threads lacks clear guarantees around shared sessions, mutable connection state, and JWT
+renewal. Both a shared ArangoClient and separate clients per thread should support parallel requests. Stateful cursors
+also need explicit ownership rules to prevent overlapping fetches and inconsistent iteration.
+
+a. Support both client usage patterns and document which database and collection wrappers can be shared. Define session
+   ownership without serializing all requests.
+
+b. Make pool sizing and acquisition timeouts predictable. Verify and fix the suspected pool_timeout wiring issue, then
+   test pool exhaustion.
+
+c. Synchronize shared resolver and JWT state, and define shutdown behavior during active requests. Keep separate clients
+   independent.
+
+d. Support independent cursors for concurrent queries. Document each cursor as having one consumer, including iteration,
+   fetching, batch access, and closing.
+
+e. Test both client usage patterns with overlapping requests, independent cursors, JWT renewal, and shutdown. Check for
+   deadlocks and blocked threads after failures.
+
+## API versioning
+
+Versioned APIs can change accepted parameters, response fields, and endpoint behavior. Supporting them requires more
+than changing URL prefixes: the driver must preserve existing Python calls while exposing incompatible contracts through
+clear method signatures and accurate type hints.
+
+a. Add optional API version selection to client.db(), retaining legacy behavior when omitted. Keep the selected policy
+   fixed on the connection and propagate it through cursors and execution contexts.
+
+b. Group operation-specific request builders and response decoders into adapters selected by each version policy. Reuse
+   unchanged adapters and keep authentication, transport, and retries separate.
+
+c. Preserve StandardCollection as the legacy interface. Share unchanged methods through a common base and introduce
+   sibling version-specific wrappers where signatures or result contracts differ.
+
+d. Use Literal overloads to select typed database and collection wrappers, and TypedDict definitions for
+   version-specific results. Preserve missing legacy fields only when they can be derived accurately.
+
+e. Validate version support and reject unsupported operations explicitly. Test legacy compatibility, version-specific
+   requests and results, type inference, and version propagation across execution contexts.
+
+### Examples
+
+These sketches describe proposed interfaces, not current driver features. The index parameters and result fields are
+hypothetical; omitted implementations use `...`.
+
+Existing calls retain their behavior, while callers explicitly opt into a new contract:
+
+```python
+legacy = client.db("example", **credentials)
+modern = client.db("example", api_version="v1", **credentials)
+
+legacy.collection("docs").index(foo="bar")
+result = modern.collection("docs").index(foo={"bar": "bar"})
+```
+
+Each policy groups adapters for its contract. Adapters build complete requests and decode successful responses;
+existing response handlers retain operation-specific exceptions and use `_execute()` to preserve execution contexts.
+
+```python
+legacy_policy = ApiPolicy(
+    indexes=LegacyIndexAdapter(),
+    aql=LegacyAqlAdapter(),
+    cursors=LegacyCursorAdapter(),
+)
+v1_policy = ApiPolicy(
+    indexes=V1IndexAdapter(),
+    aql=V1AqlAdapter(),
+    cursors=V1CursorAdapter(),
+)
+
+class V1IndexAdapter:
+    def build_create_request(self, collection, definition) -> Request:
+        ...
+
+    def decode_create_response(self, body) -> dict:
+        ...
+```
+
+Unchanged public methods share a base implementation. Incompatible methods belong to sibling classes, with separate
+parameter and result types. Here, StandardCollection retains the legacy role discussed as V0Collection.
+
+```python
+from typing import TypedDict
+
+from arango.api import ApiGroup
+from arango.result import Result
+
+
+class V1IndexOptions(TypedDict):
+    bar: str
+
+
+class V0IndexResult(TypedDict):
+    id: str
+    legacy_field: str
+
+
+class V1IndexResult(TypedDict):
+    id: str
+
+
+class CommonCollection(ApiGroup):
+    def count(self) -> Result[int]:
+        ...
+
+
+class StandardCollection(CommonCollection):
+    def index(self, *, foo: str) -> Result[V0IndexResult]:
+        ...
+
+
+class V1Collection(CommonCollection):
+    def index(self, *, foo: V1IndexOptions) -> Result[V1IndexResult]:
+        ...
+```
+
+Both collection classes inherit `count()`. Their `index()` implementations delegate to version-specific adapters;
+V1Collection does not override StandardCollection with an incompatible signature. V1IndexResult has no legacy_field.
+
+Overloads connect version selection to the returned wrapper type. This sketch abbreviates existing arguments;
+the actual signatures must preserve them and append `api_version` as a keyword-only parameter.
+
+```python
+from typing import Literal, overload
+
+
+class ArangoClient:
+    @overload
+    def db(self, name: str, *, api_version: None = None) -> StandardDatabase: ...
+
+    @overload
+    def db(self, name: str, *, api_version: Literal["v1"]) -> V1Database: ...
+
+    def db(self, name: str, *, api_version: str | None = None):
+        ...
+```
+
+StandardDatabase.collection() returns StandardCollection; V1Database.collection() returns V1Collection.
+This lets type checkers reject a string passed to the v1 index method without widening both signatures to a union.
+
+## Types
+
+Generic dictionaries and long parameter lists make driver APIs difficult to discover and check statically. Typed inputs,
+results, and query configuration objects should provide clearer signatures and property access while preserving existing
+dictionary operations, JSON serialization, and method calls.
+
+a. Add dictionary-based input and result models with typed constructors and explicit properties. Keep dictionary storage
+   authoritative, preserve existing keys, and retain unknown fields where current behavior does.
+
+b. Accept typed index definitions alongside existing dictionaries. Return models such as Result[ServerVersion], wrapping
+   existing formatted responses and preserving asynchronous and batch execution behavior.
+
+c. Add a Query object accepted by AQL.execute() alongside the full existing signature. Normalize both forms through one
+   execution path without mutating reusable query configuration.
+
+d. Describe both execute() forms with overloads and one runtime implementation. Capture extra arguments to reject mixed
+   configuration, preserving existing defaults and positional arguments for string calls.
+
+e. Test dictionary operations, properties, JSON serialization, custom serializers, and both query forms. Document
+   mutation limits and use opt-in typed responses where exact dictionary types must remain compatible.
+
+### Examples
+
+These are proposed interfaces and abbreviated implementation sketches. Models are instances passed to methods, not
+classes. The earlier TypedDict examples describe schemas; dictionary subclasses additionally provide runtime accessors.
+
+Typed index definitions supplement existing dictionary inputs. Request definitions and returned index descriptions
+should use separate models because their required fields differ.
+
+```python
+collection.add_index(VectorIndex(fields=["embedding"], params=vector_params))
+collection.add_index(InvertedIndex(fields=["title"]))
+collection.add_index({"type": "inverted", "fields": ["title"]})
+```
+
+A response model keeps property and dictionary access consistent, without storing a second copy of each value:
+
+```python
+import json
+from typing import Any, cast
+
+
+class ServerVersion(dict[str, Any]):
+    @property
+    def version(self) -> str:
+        return cast(str, self["version"])
+
+    @version.setter
+    def version(self, value: str) -> None:
+        self["version"] = value
+
+
+result = ServerVersion(version="3.12.11", server="arango")
+assert result.version == result["version"]
+result.version = "3.12.12"
+assert result["version"] == "3.12.12"
+plain = dict(result)
+encoded = json.dumps(result)
+```
+
+server_version() would return Result[ServerVersion], wrapping format_body(resp.body) in ServerVersion on success.
+Keep existing formatting before wrapping; version adapters select different models when needed.
+
+dict(result) makes a shallow copy. Nested values must also be JSON-compatible; a recursive to_dict() can provide plain
+nested dictionaries if required. Unknown keys remain accessible through dictionary syntax.
+
+Dictionary subclasses pass isinstance(result, dict), but not type(result) is dict. Custom serializers need compatibility
+checks. Explicit properties avoid collisions with dictionary methods such as items() and keys().
+
+cast() provides a static hint, not runtime validation. Direct dictionary mutation can still introduce invalid values or
+remove required fields. Validate typed constructors or provide explicit validation without restricting legacy dictionary
+operations; optional accessors should not insert absent fields into the response.
+
+A Query object groups the text, bind variables, and execution options without replacing the existing call form:
+
+```python
+text = "FOR doc IN documents FILTER doc.active == @active RETURN doc"
+
+cursor = db.aql.execute(text, bind_vars={"active": True}, batch_size=100)
+
+query = Query(text=text, bind_vars={"active": True}, batch_size=100)
+cursor = db.aql.execute(query=query)
+```
+
+Overloads describe the accepted forms to type checkers. One implementation dispatches on the query type; two ordinary
+execute() definitions would replace one another. This sketch shows only count and batch_size; retain all existing
+parameters in the actual string overload and the helper handling legacy calls.
+
+```python
+from typing import overload
+
+
+class AQL:
+    @overload
+    def execute(self, query: Query) -> Result[Cursor]: ...
+
+    @overload
+    def execute(
+        self, query: str, count: bool = False, batch_size: int | None = None
+    ) -> Result[Cursor]: ...
+
+    def execute(self, query: str | Query, *args, **kwargs) -> Result[Cursor]:
+        if isinstance(query, Query):
+            if args or kwargs:
+                raise TypeError("A Query object cannot be combined with other arguments")
+            return self._execute_query(query)
+        return self._execute_legacy(query, *args, **kwargs)
+```
+
+The _execute_legacy() helper retains the full existing signature and defaults, then normalizes its arguments into the
+same execution path as _execute_query(). Capturing arguments before defaults are applied distinguishes every explicit
+extra argument, including None and False, without sentinels.
+
+```python
+db.aql.execute(query)                   # Accepted.
+db.aql.execute(query=query)             # Accepted.
+db.aql.execute(query, batch_size=None)  # TypeError: explicit extra keyword argument.
+db.aql.execute(query, False)            # TypeError: explicit extra positional argument.
+```
+
+The existing Sphinx autodoc configuration rendered both overloads, including their defaults and type hints, in a
+temporary build with Sphinx 8.2.3. No additional extension or configuration was needed. Keep overloads complete for IDEs
+and generated API documentation; documentation dependencies currently do not pin Sphinx.
+
+Runtime inspect.signature() still exposes (self, query, *args, **kwargs). Overloads improve static tooling and this
+project's generated documentation, but do not change runtime argument binding or enforce the mixed-argument rule.
+
+The shared execution path must preserve more than the JSON body: allow_dirty_read controls a request header, while
+allow_retry also configures the returned cursor. Keep cursor state separate and snapshot mutable query configuration
+as needed so executing a Query does not change it.
+
+## Response format
+
+Response formatting inconsistently renames keys, drops unknown fields, and changes values such as index identifiers.
+Disabling formatting does not reliably preserve server data. Responses need predictable dictionary representations and
+stable snake_case properties, with a compatibility mode for applications relying on historical transformations.
+
+a. Add fixed server and legacy response formats per database wrapper, independently of API version. Make server the
+   next major release's default and retain legacy indefinitely.
+
+b. Preserve server resource keys, values, and unknown fields in server mode. Isolate historical transformations in
+   legacy adapters; define unchanged server names for new fields without historical mappings.
+
+c. Implement response models as dict subclasses with explicit snake_case properties. Store only the selected
+   representation, and use sibling legacy implementations where property mappings differ.
+
+d. Separate envelope extraction from resource formatting. Avoid mutating input dictionaries or renaming user data;
+   document copying, optional properties, and value differences between representations.
+
+e. Audit formatter.py and inline cursor transformations. Test both formats, property synchronization, serialization, and
+   execution contexts; document migration, existing formatter options, and exact-dict compatibility limits.
+
+### Examples
+
+These are proposed interfaces. Select the format once; collections, cursors, and asynchronous or batch results inherit
+that selection. API version and response format remain independent choices.
+
+```python
+modern = client.db("example", response_format="server", **credentials)
+legacy = client.db("example", response_format="legacy", **credentials)
+```
+
+Both representations offer the same snake_case property names. Dictionary access and JSON serialization use the selected
+keys, without storing duplicate aliases. This simplified model illustrates a required field of a TTL index:
+
+```python
+import json
+from typing import Any, ClassVar, cast
+
+
+class IndexInfo(dict[str, Any]):
+    _expiry_key: ClassVar[str] = "expireAfter"
+
+    @property
+    def expire_after(self) -> int:
+        return cast(int, self[self._expiry_key])
+
+    @expire_after.setter
+    def expire_after(self, value: int) -> None:
+        self[self._expiry_key] = value
+
+
+class LegacyIndexInfo(IndexInfo):
+    _expiry_key = "expiry_time"
+
+
+server = IndexInfo({"expireAfter": 60})
+legacy = LegacyIndexInfo({"expiry_time": 60})
+assert server.expire_after == legacy.expire_after
+
+legacy.expire_after = 120
+assert legacy["expiry_time"] == 120
+assert dict(server) == {"expireAfter": 60}
+assert json.loads(json.dumps(legacy)) == {"expiry_time": 120}
+```
+
+The response adapter prepares the selected representation and constructs its model. Actual models must reflect the
+field's numeric range and optionality. Properties read dictionary storage directly, including changes made through
+update() or item assignment; unrestricted dictionary mutation still cannot guarantee valid field types.
+
+Keep legacy value and structure conversions explicit: shortening an index ID is not a key alias. Document whether
+properties expose the selected stored value or a separately derived value. Do not reconstruct lost information from
+legacy data or retain a second mutable dictionary that can drift out of sync.
+
+Use the async driver's JsonWrapper properties as a reference, but inherit standard dictionary behavior instead of
+reimplementing it. Its current wrapper lacks several dictionary methods, cannot be serialized directly by json.dumps(),
+mutates constructor input, and exposes internal storage through to_dict().
+
+Copy input mappings during construction. dict(model) and a basic to_dict() should return shallow copies; document nested
+sharing or provide explicit recursive conversion. Envelope removal belongs in endpoint response handling, not the model
+base class. Never apply generic recursive key conversion to documents, bind variables, or user-defined names.
+
+Retaining legacy indefinitely requires permanent compatibility tests. Freeze historical mappings and document handling
+of new fields; preserve existing formatter options in legacy mode and reject conflicting options in server mode.
+Dictionary subclasses preserve isinstance(result, dict), but change type(result) is dict; include this and custom
+serializer compatibility in the major-release migration notes.
+
+
+## Documentation tests
+
+This could be done better, especially for the async driver.

python_arango-8.3.5/.github/workflows/pypi.yaml

@@ -1,40 +0,0 @@
-name: Upload to PyPI
-
-on:
-  release:
-    types: [published]
-
-jobs:
-  upload:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v7
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-
-      - uses: actions/setup-python@v7
-        with:
-          python-version: "3.12"
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install build twine
-
-      - name: Build distribution
-        run: python -m build
-
-      - name: Publish to PyPI Test
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_TEST_TOKEN }}
-        run: twine upload --verbose --repository testpypi dist/*
-
-      - name: Publish to PyPI
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
-        run: twine upload --verbose --repository pypi dist/*

python_arango-8.3.5/CONTRIBUTING.md

@@ -1,28 +0,0 @@
-# Contributing
-
-Set up dev environment:
-```shell
-cd ~/your/repository/fork  # Activate venv if you have one (recommended)
-pip install -e .[dev]      # Install dev dependencies (e.g. black, mypy, pre-commit)
-pre-commit install         # Install git pre-commit hooks
-```
-
-Run unit tests with coverage:
-
-```shell
-pytest --cov=arango --cov-report=html  # Open htmlcov/index.html in your browser
-```
-
-To start and ArangoDB instance locally, run:
-
-```shell
-./starter.sh  # Requires docker
-```
-
-Build and test documentation:
-
-```shell
-python -m sphinx docs docs/_build  # Open docs/_build/index.html in your browser
-```
-
-Thank you for your contribution!

python_arango-8.3.5/arango/version.py

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

python_arango-8.3.5/docs/contributing.rst

@@ -1,99 +0,0 @@
-Contributing
-------------
-
-Requirements
-============
-
-Before submitting a pull request on GitHub_, please make sure you meet the
-following requirements:
-
-* The pull request points to main_ branch.
-* Changes are squashed into a single commit. I like to use git rebase for this.
-* Commit message is in present tense. For example, "Fix bug" is good while
-  "Fixed bug" is not.
-* Sphinx_-compatible docstrings.
-* PEP8_ compliance.
-* No missing docstrings or commented-out lines.
-* Test coverage remains at %100. If a piece of code is trivial and does not
-  need unit tests, use this_ to exclude it from coverage.
-* No build failures. Builds automatically trigger on pull
-  request submissions.
-* Documentation is kept up-to-date with the new changes (see below).
-
-.. warning::
-    The dev branch is occasionally rebased, and its commit history may be
-    overwritten in the process. Before you begin your feature work, git fetch
-    or pull to ensure that your local branch has not diverged. If you see git
-    conflicts and want to start with a clean slate, run the following commands:
-
-    .. code-block:: bash
-
-        ~$ git checkout dev
-        ~$ git fetch origin
-        ~$ git reset --hard origin/dev  # THIS WILL WIPE ALL LOCAL CHANGES
-
-Style
-=====
-
-To ensure PEP8_ compliance, run flake8_:
-
-.. code-block:: bash
-
-    ~$ pip install flake8
-    ~$ git clone https://github.com/arangodb/python-arango.git
-    ~$ cd python-arango
-    ~$ flake8
-
-If there is a good reason to ignore a warning, see here_ on how to exclude it.
-
-Testing
-=======
-
-To test your changes, you can run the integration test suite that comes with
-**python-arango**. It uses pytest_ and requires an actual ArangoDB instance.
-
-To run the test suite (use your own host, port and root password):
-
-.. code-block:: bash
-
-    ~$ pip install pytest
-    ~$ git clone https://github.com/arangodb/python-arango.git
-    ~$ cd python-arango
-    ~$ pytest --cluster --host=127.0.0.1 --port=8529 --password=passwd
-
-To run the test suite with coverage report:
-
-.. code-block:: bash
-
-    ~$ pip install coverage pytest pytest-cov
-    ~$ git clone https://github.com/arangodb/python-arango.git
-    ~$ cd python-arango
-    ~$ pytest --cluster --host=127.0.0.1 --port=8529 --password=passwd --cov=kq
-
-As the test suite creates real databases and jobs, it should only be run in
-development environments.
-
-Documentation
-=============
-
-The documentation including the README is written in reStructuredText_ and uses
-Sphinx_. To build an HTML version on your local machine:
-
-.. code-block:: bash
-
-    ~$ pip install sphinx sphinx_rtd_theme
-    ~$ git clone https://github.com/arangodb/python-arango.git
-    ~$ cd python-arango
-    ~$ python -m sphinx -b html -W docs docs/_build/  # Open build/index.html in a browser
-
-As always, thank you for your contribution!
-
-.. _main: https://github.com/arangodb/python-arango/tree/main
-.. _GitHub: https://github.com/arangodb/python-arango
-.. _PEP8: https://www.python.org/dev/peps/pep-0008/
-.. _this: http://coverage.readthedocs.io/en/latest/excluding.html
-.. _Sphinx: https://github.com/sphinx-doc/sphinx
-.. _flake8: http://flake8.pycqa.org
-.. _here: http://flake8.pycqa.org/en/latest/user/violations.html#in-line-ignoring-errors
-.. _pytest: https://github.com/pytest-dev/pytest
-.. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText

python_arango-8.3.5/python_arango.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "8.3.5",
-  "distance": 0,
-  "node": "ga90d0b72830ee6a7db388833e77110a53fe59708",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-08-31"
-}