Skip to content

AGENTS.md

Latest commit

 

History

History
49 lines (38 loc) · 2.12 KB

AGENTS.md

File metadata and controls

49 lines (38 loc) · 2.12 KB
Raw

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

Overview

Official Python driver for MongoDB.

Tech Stack

  • 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/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/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)

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

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).

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.