From b613a9c55042fdebad007dcb38d06f0499d86fb3 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Fri, 1 May 2026 15:42:05 -0400 Subject: [PATCH 1/5] PYTHON-5817 - Add repository layout guide to CONTRIBUTING.md --- CONTRIBUTING.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77888eb087..c4ef3cae11 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -505,13 +505,18 @@ 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. +PyMongo's source code is located in the `pymongo` directory and is further divided into the `pymongo/asynchronous` and `pymongo/synchronous` subdirectories. +All files in the `synchronous` subdirectory are generated from the `asynchronous` subdirectory using the `synchro` pre-commit hook, which uses [unasync](https://github.com/python-trio/unasync/) and some custom transforms. -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. +As a result, **all modifications** must be made in the top-level `pymongo` directory or the `pymongo/asynchronous` directory. +Any changes made 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`. + +You can 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. From ccbd10f799652bf6fede6cb689c2e18ad48f2646 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Fri, 1 May 2026 15:53:34 -0400 Subject: [PATCH 2/5] CP review --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c4ef3cae11..18b24ef460 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -510,8 +510,8 @@ Follow the [Python Driver Release Process Wiki](https://wiki.corp.mongodb.com/di PyMongo's source code is located in the `pymongo` directory and is further divided into the `pymongo/asynchronous` and `pymongo/synchronous` subdirectories. All files in the `synchronous` subdirectory are generated from the `asynchronous` subdirectory using the `synchro` pre-commit hook, which uses [unasync](https://github.com/python-trio/unasync/) and some custom transforms. -As a result, **all modifications** must be made in the top-level `pymongo` directory or the `pymongo/asynchronous` directory. -Any changes made to files in the `pymongo/synchronous` directory will be overwritten by the `synchro` hook when it is run, which happens automatically on commit. +As a result, **all modifications** within `pymongo` must be made in the top-level `pymongo` directory 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`. From b4ad1caaa2ea8993fb19ebf05cbd8820797325b8 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Mon, 4 May 2026 11:15:55 -0400 Subject: [PATCH 3/5] Update CONTRIBUTING.md Co-authored-by: Jib --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 18b24ef460..97e66ac2ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -510,7 +510,7 @@ Follow the [Python Driver Release Process Wiki](https://wiki.corp.mongodb.com/di PyMongo's source code is located in the `pymongo` directory and is further divided into the `pymongo/asynchronous` and `pymongo/synchronous` subdirectories. All files in the `synchronous` subdirectory are generated from the `asynchronous` subdirectory 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 the top-level `pymongo` directory or the `pymongo/asynchronous` directory, not `pymongo/synchronous`. +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. From 085c2190fea65ac56c67c5099af087f27f31186b Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Mon, 4 May 2026 11:16:04 -0400 Subject: [PATCH 4/5] Update CONTRIBUTING.md Co-authored-by: Jib --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 97e66ac2ac..a7414a471c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -516,7 +516,7 @@ Any changes made directly to files in the `pymongo/synchronous` directory will b 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`. -You can run `pre-commit run --all-files synchro` before running tests to generate the latest version of the synchronous code. +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. From 8760b07e897682422078e6a0ba707a5a93137367 Mon Sep 17 00:00:00 2001 From: Noah Stapp Date: Mon, 4 May 2026 11:25:29 -0400 Subject: [PATCH 5/5] JA review --- CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a7414a471c..773c9ec0d8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -507,8 +507,10 @@ Follow the [Python Driver Release Process Wiki](https://wiki.corp.mongodb.com/di ## Project Structure and Asyncio Considerations -PyMongo's source code is located in the `pymongo` directory and is further divided into the `pymongo/asynchronous` and `pymongo/synchronous` subdirectories. -All files in the `synchronous` subdirectory are generated from the `asynchronous` subdirectory using the `synchro` pre-commit hook, which uses [unasync](https://github.com/python-trio/unasync/) and some custom transforms. +This section describes the layout of the `pymongo/` package. + +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.