fastapi-pymongo

FastAPI integration for PyMongo:

• PyObjectId: Pydantic-native ObjectId. Validates from ObjectId or hex string, serializes to a string in JSON mode (Python-mode dumps keep the ObjectId, so documents round-trip through insert_one), correct OpenAPI/JSON schema.
• MongoSettings: pydantic-settings base class for Mongo URI and database name. Subclass to add app settings.
• mongo_lifespan / get_client / get_database: client lifecycle wired to FastAPI's lifespan, exposed via Depends().
• beanie_lifespan (optional, fastapi-pymongo[beanie]): runs Beanie's init_beanie alongside the rest of fastapi_pymongo, for an ODM on top.

Install

pip install fastapi-pymongo

Optional Beanie integration:

pip install "fastapi-pymongo[beanie]"

Examples

• examples/quickstart: minimal CRUD app, raw PyMongo.
• examples/beanie: same CRUD app on Beanie. Verified against a real MongoDB instance (create/list/get/delete).

Development

pip install -e ".[dev]"
pytest            # unit tests (integration and perf are deselected by default)
pytest -m perf    # PyObjectId overhead benchmarks
ruff check src tests examples
mypy src

Integration tests need a running MongoDB; set MONGODB_URI (default mongodb://localhost:27017). Run the full suite with a local server, for example via mongodb-runner start --topology standalone.

Documentation

Sphinx docs (furo theme) under docs/source:

pip install -e ".[docs]"
sphinx-build -b html docs/source docs/build
open docs/build/index.html

References

• INTPYTHON-1087: [SPIKE] FastAPI integration library for MongoDB. This repo is the prototype (PYTHON-3372, epic, dev complete). DoD answers:
  • Minimum setup? AsyncMongoClient via FastAPI lifespan and Depends(). See mongo_lifespan/get_client/get_database, examples/quickstart. The official-template gap this package is an alternative path around: INTPYTHON-382, blocked.
  • Leverage FastAPI/Pydantic? _id isn't a valid Python field name or a Pydantic/JSON-native type. PyObjectId fixes serialization and schema. MongoSettings reuses the same model pattern for config. This is the most common first-hour complaint in the FastAPI + MongoDB community (fastapi#9074, also requested upstream in pydantic-extra-types#133); this is the same pattern users already land on by hand, as a maintained, tested thin layer instead of copy-pasted snippets. Django-side precedent for a Pydantic-schema integration: INTPYTHON-565, backlog.
  • Thin wrapper feasible? Yes. Built and tested: PyObjectId, MongoSettings, mongo_lifespan/get_client/get_database.
  • Quickstart CRUD prototype? Done. examples/quickstart.
  • Packaging? Name fastapi-pymongo, reserved on PyPI.
  • Beanie boundary? No first-party ODM. See docs/source/reference.rst for why (MongoDB's PyMODM precedent was paused and archived). beanie_lifespan runs Beanie's init_beanie alongside this package for anyone who wants one. See examples/beanie, verified against real MongoDB. PyObjectId doesn't apply to Beanie models, since Document already provides its own ObjectId field (beanie.PydanticObjectId).
  • Client metadata? Set at client construction via AsyncMongoClient(uri, driver=DriverInfo(name="fastapi-pymongo", version=...)) in mongo_lifespan/beanie_lifespan. Verified against a real server ($currentOp.clientMetadata.driver.name).
  • Cost estimate? 0. PyObjectId, MongoSettings, mongo_lifespan/get_client/get_database, the Beanie boundary, and client metadata are already built, tested, and published as an alpha (0.1.0a0 on PyPI). No further implementation work is needed. (Pydantic/FastAPI version-compat friction at this boundary, precedent: PYTHON-5543, closed.)