From f4219bdca2cfa816f90edb9f5463dbfc2666e609 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Wed, 6 May 2026 13:28:36 -0400 Subject: [PATCH] PYTHON-5817 - Add "Project Structure and Asyncio Considerations" section to CONTRIBUTING.md (#2788) Co-authored-by: Jib --- CONTRIBUTING.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77888eb08..773c9ec0d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -505,13 +505,20 @@ python3 ./.evergreen/scripts/resync-all-specs.py Follow the [Python Driver Release Process Wiki](https://wiki.corp.mongodb.com/display/DRIVERS/Python+Driver+Release+Process). -## Asyncio considerations +## Project Structure and Asyncio Considerations -PyMongo adds asyncio capability by modifying the source files in `*/asynchronous` to `*/synchronous` using -[unasync](https://github.com/python-trio/unasync/) and some custom transforms. +This section describes the layout of the `pymongo/` package. -Where possible, edit the code in `*/asynchronous/*.py` and not the synchronous files. -You can run `pre-commit run --all-files synchro` before running tests if you are testing synchronous code. +Within `pymongo/`, the code is further divided into the `pymongo/asynchronous` and `pymongo/synchronous` subdirectories. +Files in `pymongo/synchronous` are generated from `pymongo/asynchronous` using the `synchro` pre-commit hook, which uses [unasync](https://github.com/python-trio/unasync/) and some custom transforms. + +As a result, **all modifications** within `pymongo` must be made in either the top-level `pymongo` directory when they have to exhibit differing behavior between sync and async contexts or the `pymongo/asynchronous` directory, not `pymongo/synchronous`. +Any changes made directly to files in the `pymongo/synchronous` directory will be overwritten by the `synchro` hook when it is run, which happens automatically on commit. + +Some top-level files (e.g. `pymongo/collection.py`) are re-export files for existing import compatibility and should not be modified directly. +The other top-level files (e.g. `pymongo/network_layer.py`, `pymongo/pool_shared.py`) contain either shared code used in both the asynchronous and synchronous APIs, or code that is very different between the two APIs and therefore cannot be generated from the async version using `synchro`. + +Run `pre-commit run --all-files synchro` before running tests to generate the latest version of the synchronous code. To prevent the `synchro` hook from accidentally overwriting code, it first checks to see whether a sync version of a file is changing and not its async counterpart, and will fail.