From 4d03d7c26ffb0afaf6839cf183687cc6eab85f7d Mon Sep 17 00:00:00 2001 From: Alex Petenchea Date: Sun, 1 Nov 2026 19:34:09 +0800 Subject: [PATCH 1/2] Driver development skills --- .../skills/python-arango-development/SKILL.md | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 .agents/skills/python-arango-development/SKILL.md diff --git a/.agents/skills/python-arango-development/SKILL.md b/.agents/skills/python-arango-development/SKILL.md new file mode 100644 index 00000000..4acb931b --- /dev/null +++ b/.agents/skills/python-arango-development/SKILL.md @@ -0,0 +1,53 @@ +--- +name: python-arango-development +description: >- + Maintain and extend python-arango, the ArangoDB Python driver. Use for + driver features, bug fixes, refactoring, and related tests or documentation, + rather than application code that uses the driver. +--- + +# Python driver development + +Follow the repository's [AGENTS.md](../../../AGENTS.md) for setup, validation +commands, and contribution rules. + +Before changing an operation, trace a neighboring method with a similar +request and response shape. Public API methods usually construct a `Request`, +define a response handler, and call `self._execute(request, response_handler)`. +See `arango/api.py`, `arango/request.py`, and the API group being changed. +Keep request construction and response conversion at the same layer as the +neighboring operations. + +Preserve execution through `_execute` when following this pattern. It delegates +to the configured executor in `arango/executor.py`, supporting default, async, +batch, and transaction contexts. Calling the connection directly can bypass +that behavior. Preserve `Result[T]` annotations where applicable: an operation +can return a value, an async or batch job, or `None`, depending on its context. +See `arango/result.py` for the shared type. + +Follow the neighboring handler's success checks, response formatting, and +operation-specific exceptions from `arango/exceptions.py`. Preserve existing +return shapes and error contracts when fixing a bug. + +Add focused regression coverage in the relevant `tests/test_*.py` module, +reusing fixtures and helpers from `tests/conftest.py` and `tests/helpers.py`. +Check the affected request mapping, result, or error behavior; exercise related +execution contexts when the change affects them. + +For test selection, inspect fixture dependencies in `tests/conftest.py`. +Pytest normally connects to ArangoDB and creates test resources during +configuration, even for database-free tests or collection. Use +`--skip-arango-setup` only for tests that need no configured database fixtures, +for example: + +```sh +python -m pytest tests/test_request.py --skip-arango-setup +``` + +This flag bypasses setup; it does not make integration tests run offline. +For server behavior, run the relevant test against a disposable ArangoDB +instance using AGENTS.md. Match the actual topology: pass `--cluster` for a +cluster, omit it for a single server. The flag does not start a cluster. +Check version and capability skips in the selected tests; skipped cases do +not validate the change. Start with the affected test, expand for changed +contracts, and report any unverified behavior. From 6a6707295db0033b59cc852aa708bc49c7af954e Mon Sep 17 00:00:00 2001 From: Alex Petenchea Date: Sun, 1 Nov 2026 19:36:37 +0800 Subject: [PATCH 2/2] updating development skill --- .../skills/python-arango-development/SKILL.md | 22 ++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/.agents/skills/python-arango-development/SKILL.md b/.agents/skills/python-arango-development/SKILL.md index 4acb931b..dc068600 100644 --- a/.agents/skills/python-arango-development/SKILL.md +++ b/.agents/skills/python-arango-development/SKILL.md @@ -25,9 +25,25 @@ that behavior. Preserve `Result[T]` annotations where applicable: an operation can return a value, an async or batch job, or `None`, depending on its context. See `arango/result.py` for the shared type. -Follow the neighboring handler's success checks, response formatting, and -operation-specific exceptions from `arango/exceptions.py`. Preserve existing -return shapes and error contracts when fixing a bug. +For endpoint or option changes, verify the server HTTP API for the targeted +ArangoDB versions. Map Python option names to the specified wire names and +locations: endpoint path, `params` for query parameters, `headers`, or `data` +for the body. Preserve existing defaults and distinguish omitted options from +explicit `False`, `0`, or empty values. Where `None` means omission, use +`is not None` rather than a truthiness check. `normalize_params` in `arango/request.py` +stringifies supplied values, including `None`; omit such query entries before +constructing the request. Keep explicit JSON nulls where the body contract +requires them. + +Follow the neighboring handler's success checks and response formatting; +reuse helpers in `arango/formatter.py` where applicable. Preserve Python-facing +field names, return shapes, and silent-operation results. Handle special +statuses before the general failure check where required, such as revision +conflicts. Raise the operation-specific exception from `arango/exceptions.py` +with `(resp, request)` to retain HTTP and ArangoDB error details. Keep signatures, +annotations, and Sphinx parameter and return documentation aligned. Cover +omitted and explicit option values, result conversion, and affected error +paths in regression tests. Add focused regression coverage in the relevant `tests/test_*.py` module, reusing fixtures and helpers from `tests/conftest.py` and `tests/helpers.py`.