Metadata-Version: 2.4
Name: fastapi-pymongo
Version: 0.1.0a3
Summary: FastAPI integration for PyMongo: Pydantic-native BSON types, client lifespan/DI, settings helpers.
License: Apache-2.0
Project-URL: Homepage, https://github.com/aclark4life/fastapi-pymongo
Project-URL: Issues, https://github.com/aclark4life/fastapi-pymongo/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: pydantic>=2.10
Requires-Dist: pydantic-settings>=2.12
Requires-Dist: pymongo>=4.9
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Provides-Extra: beanie
Requires-Dist: beanie>=1.26; extra == "beanie"
Dynamic: license-file

# 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](https://github.com/BeanieODM/beanie)'s `init_beanie` alongside the rest of `fastapi_pymongo`, for an ODM on top.

## Install

```bash
pip install fastapi-pymongo
```

Optional Beanie integration:

```bash
pip install "fastapi-pymongo[beanie]"
```

## Examples

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

## Development

```bash
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`:

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

## References

- [INTPYTHON-1087](https://jira.mongodb.org/browse/INTPYTHON-1087): [SPIKE] FastAPI integration library for MongoDB. This repo is the prototype ([PYTHON-3372](https://jira.mongodb.org/browse/PYTHON-3372), epic, dev complete). DoD answers:
  - **Minimum setup?** `AsyncMongoClient` via FastAPI `lifespan` and `Depends()`. See `mongo_lifespan`/`get_client`/`get_database`, [`examples/quickstart`](examples/quickstart). The official-template gap this package is an alternative path around: [INTPYTHON-382](https://jira.mongodb.org/browse/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](https://github.com/fastapi/fastapi/discussions/9074), also requested upstream in [pydantic-extra-types#133](https://github.com/pydantic/pydantic-extra-types/issues/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](https://jira.mongodb.org/browse/INTPYTHON-565), backlog.
  - **Thin wrapper feasible?** Yes. Built and tested: `PyObjectId`, `MongoSettings`, `mongo_lifespan`/`get_client`/`get_database`.
  - **Quickstart CRUD prototype?** Done. [`examples/quickstart`](examples/quickstart).
  - **Packaging?** Name `fastapi-pymongo`, [reserved on PyPI](https://pypi.org/project/fastapi-pymongo/).
  - **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`](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](https://jira.mongodb.org/browse/PYTHON-5543), closed.)
