From e29fcae8cf6ce7f997e93ba1c61689047d9e048d Mon Sep 17 00:00:00 2001 From: Alex Petenchea Date: Sun, 4 Oct 2026 20:35:21 +0800 Subject: [PATCH 1/2] Updating starter default image --- starter.sh | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/starter.sh b/starter.sh index 6ca977c..20abd8d 100755 --- a/starter.sh +++ b/starter.sh @@ -1,7 +1,7 @@ #!/bin/bash # Starts a local ArangoDB server or cluster (community or enterprise). -# Useful for testing the python-arango driver against a local ArangoDB setup. +# Useful for testing the python-arango-async driver against a local ArangoDB setup. # Usage: # ./starter.sh [single|cluster] [community|enterprise|enterprise-preview] [version] @@ -10,9 +10,10 @@ # ./starter.sh cluster enterprise 3.12.4 # ./starter.sh single enterprise-preview 4.0-nightly # ./starter.sh single arangodb/enterprise-preview:4.0-nightly +# Defaults: single server, enterprise image, latest version. setup="${1:-single}" -image="${2:-community}" +image="${2:-enterprise}" version="${3:-latest}" extra_ports="" From dd9ce5c63cd0dd378888478b0efc1b269ddf33bf Mon Sep 17 00:00:00 2001 From: Alex Petenchea Date: Sun, 4 Oct 2026 20:36:23 +0800 Subject: [PATCH 2/2] Added AGENTS.md and removed CONTRIBUTING.md --- AGENTS.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 28 --------------- 2 files changed, 91 insertions(+), 28 deletions(-) create mode 100644 AGENTS.md delete mode 100644 CONTRIBUTING.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..08b09ab --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,91 @@ +# Quickstart + +python-arango-async is an async Python driver for ArangoDB. Run the commands below from the +repository root. + +## Repository layout + +- `arangoasync/`: 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. In this workspace, use +`/home/apetenchea/programs/pyenv/ida/bin/python` and run tests from +`/home/apetenchea/arangodb/python-arango-async`, so they exercise this driver. + +## 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=arangoasync --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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index f2899c8..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -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 --cluster --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!