From 36643f960625dd2a88c7a8a8e35b13d5ea19c2e0 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 1 Jul 2026 11:21:58 -0400 Subject: [PATCH 1/2] PYTHON-5889 - Clean up AGENTS.md instructions --- AGENTS.md | 35 ++++++++++++++--------------------- justfile | 5 +++++ 2 files changed, 19 insertions(+), 21 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8417c2cd3e..ac1d33ec59 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,6 @@ Official Python driver for MongoDB. ## Tech Stack -- **Build/env:** `hatch` — use `hatch run test:test` and `hatch run test:test-async`, not `pytest` directly - **Task runner:** `just` (Justfile at repo root) - **Linter/formatter:** `ruff` via pre-commit - **Type checker:** `mypy` (strict) @@ -13,37 +12,31 @@ Official Python driver for MongoDB. > **Never** run `pip install bson`. PyMongo ships its own `bson`; the PyPI `bson` package silently breaks things. ## Project Structure -- `pymongo/synchronous/` — sync driver (MongoClient, Collection, Database, etc.) generated from `pymongo/asynchronous/` using unasync -- `pymongo/asynchronous/` — async API, mirrors `pymongo/synchronous/` +- `pymongo/asynchronous/` — async driver (AsyncMongoClient, AsyncCollection, etc.) +- `pymongo/synchronous/` — sync driver (MongoClient, Collection, etc.) generated from `pymongo/asynchronous/` using `just synchro` - `bson/` — BSON implementation - `gridfs/` — GridFS API -- `test/` — sync test suite -- `test/asynchronous/` — async test suite, mirrors `test/` +- `test/asynchronous/` — async test suite +- `test/` — sync test suite (generated from `test/asynchronous/` by `just synchro`) and shared test suite - `test/unified_format/` — cross-driver spec tests (Unified Test Format) -- `tools/convert_test_to_async.py` — generates async test stubs from sync tests + +Do not edit files in `pymongo/synchronous/` or mirrored files in `test/` directly: they are generated by `just synchro` from `pymongo/asynchronous/` and `test/asynchronous/`. +A file in `test/` is mirrored if a file of the same name exists in `test/asynchronous/`. ## Commands ```bash -just install # set up venv + pre-commit hook -just typing-mypy # type check -just run lint-manual # ruff linter - -hatch run test:test # run sync tests -hatch run test:test-async # run async tests - -MONGODB_VERSION=8.0 just run-server # start a local MongoDB server +just install # set up venv + pre-commit hooks +just typing # type check +just lint-manual # pre-commit linting and synchro +just synchro # generate synchronous driver and mirrored tests +just test # run all tests +just test test/asynchronous # run async tests +MONGODB_VERSION=8.0 just run-server # start a local MongoDB 8.0 server ``` ## Testing Tests require a live MongoDB server (`just run-server` above). -Never modify pymongo/synchronous code first; update the async counterpart and run our `tools/synchro.py` script: -1. Make changes in `pymongo/asynchronous` or top-level `pymongo/` files and `test/`. -2. Run `tools/convert_test_to_async.py` on the sync test file to generate a starting-point async version. -3. Manually complete the async version in `test/asynchronous/`. - -Do not edit files in `pymongo/synchronous/` or mirrored files in `test/` directly — they are auto-generated by `tools/synchro.py` from `pymongo/asynchronous/` and `test/asynchronous/`. Only edit them if the change includes a `_IS_SYNC` statement. - Async functions must not call blocking I/O. New features need integration tests. Bug fixes need regression tests. diff --git a/justfile b/justfile index 55ff9e74dd..336797e487 100644 --- a/justfile +++ b/justfile @@ -64,6 +64,11 @@ lint *args="": && resync lint-manual *args="": && resync uvx pre-commit run --all-files --hook-stage manual {{args}} +# Run synchro +[group('lint')] +synchro *args="": && resync + uvx pre-commit run --all-files synchro + # Run pytest (e.g. just test test/test_uri_parser.py) [group('test')] test *args="-v --durations=5 --maxfail=10": && resync From e15518087198343663e8d2fb61c2678161ba8ed2 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 1 Jul 2026 11:33:40 -0400 Subject: [PATCH 2/2] CP review --- justfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/justfile b/justfile index 336797e487..df678cdbac 100644 --- a/justfile +++ b/justfile @@ -66,7 +66,7 @@ lint-manual *args="": && resync # Run synchro [group('lint')] -synchro *args="": && resync +synchro: && resync uvx pre-commit run --all-files synchro # Run pytest (e.g. just test test/test_uri_parser.py)