Skip to content

AGENTS.md

Latest commit

 

History

History
56 lines (42 loc) · 2.47 KB

AGENTS.md

File metadata and controls

56 lines (42 loc) · 2.47 KB

AGENTS.md - PyMongo (mongo-python-driver)

Overview

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)
  • Docs: Sphinx / reStructuredText; use Sphinx docstring format for all docstrings

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/
  • bson/ — BSON implementation
  • gridfs/ — GridFS API
  • test/ — sync test suite
  • test/asynchronous/ — async test suite, mirrors test/
  • test/unified_format/ — cross-driver spec tests (Unified Test Format)
  • tools/convert_test_to_async.py — generates async test stubs from sync tests

Commands

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

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.

Commit and PR Conventions

  • Prefix commits and PR titles with the JIRA ticket: PYTHON-1234 Fix retryable write on mongos
  • Backport PRs: append the target branch in brackets — PYTHON-1234 [v4.9] Fix retryable write
  • Merge via Squash and Merge only

See .github/copilot-instructions.md for more details.