PYTHON-5817 - Add "Project Structure and Asyncio Considerations" section to CONTRIBUTING.md#2788
Open
NoahStapp wants to merge 6 commits intomongodb:masterfrom
Open
PYTHON-5817 - Add "Project Structure and Asyncio Considerations" section to CONTRIBUTING.md#2788NoahStapp wants to merge 6 commits intomongodb:masterfrom
NoahStapp wants to merge 6 commits intomongodb:masterfrom
Conversation
NoahStapp
requested review from
aclark4life and
sophiayangDB
and removed request for
sophiayangDB
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the contributor documentation to better explain how the PyMongo codebase is organized around generated synchronous code and the asyncio-first source tree.
Changes:
- Renames and expands the “Asyncio considerations” section into “Project Structure and Asyncio Considerations”.
- Documents the
synchropre-commit hook workflow and where contributors should make changes to avoid overwrites. - Adds guidance on top-level re-export modules and shared vs non-generated modules.
Comment on lines
+510
to
+511
| 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. |
There was a problem hiding this comment.
The statement that “PyMongo's source code is located in the pymongo directory” is misleading in this repo: there is also source under bson/ and gridfs/, and synchro also generates gridfs/synchronous (and synced test files) from async sources. Consider clarifying that this paragraph is specifically about the pymongo/ package layout, or expand it to mention the other generated async/sync trees as well.
Suggested change
| 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. The repository also contains source code in top-level directories such as `bson/` and `gridfs/`. | |
| 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. `synchro` also generates other synchronous trees, such as `gridfs/synchronous`, as well as synced test files. |
Contributor
There was a problem hiding this comment.
I agree with this suggestion minus the additional context of gridfs and bson.
Jibola
requested changes
May 4, 2026
Comment on lines
+510
to
+511
| 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. |
Contributor
There was a problem hiding this comment.
I agree with this suggestion minus the additional context of gridfs and bson.
Co-authored-by: Jib <Jibzade@gmail.com>
Co-authored-by: Jib <Jibzade@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PYTHON-5817
Changes in this PR
Update the existing "Asyncio considerations" section with a more detailed and expanded "Project Structure and Asyncio Considerations" section.
Test Plan
N/A. Documentation changes only.
Checklist
Checklist for Author
[ ] Did you update the changelog (if necessary)?[ ] Is there test coverage?[ ] Is any followup work tracked in a JIRA ticket? If so, add link(s).Checklist for Reviewer