This project has been archived by its maintainers, and is no longer receiving any updates.
Pygoose
An async-first MongoDB object-document mapper (ODM) for Python, inspired by Mongoose. Pygoose provides a clean, Pydantic-native API for working with MongoDB collections as typed Python classes.
Features
- Async-first: Built for async/await from the ground up using PyMongo's async client
- Pydantic-native: Use Pydantic v2 models directly as your documents
- Type-safe: Full type hints for queries, documents, and relationships
- QuerySet: Fluent, lazy query builder inspired by Django ORM
- References: Type-safe document references with automatic population
- Lifecycle hooks: Pre/post validation, save, delete, and update hooks
- Encryption: Field-level encryption for sensitive data
- Plugins: Built-in plugins for timestamps, soft delete, and audit trails
- FastAPI: First-class FastAPI integration with exception handlers and schema generation
Installation
pip install pygoose
Optional dependencies:
# For field-level encryption
pip install pygoose[encryption]
# For FastAPI integration
pip install pygoose[fastapi]
# For development
pip install pygoose[dev]
Quick start
Define your documents as Pydantic models:
from pygoose import Document
from typing import Optional
class User(Document):
name: str
email: str
age: Optional[int] = None
Connect to MongoDB and perform CRUD operations:
import asyncio
from pygoose import connect, disconnect
async def main():
# Connect to MongoDB
await connect("mongodb://localhost:27017/my_database")
# Create
user = User(name="Alice", email="alice@example.com", age=30)
await user.save()
# Read
user = await User.find_one({"email": "alice@example.com"})
# Update
user.age = 31
await user.save()
# Delete
await user.delete()
# Cleanup
await disconnect()
asyncio.run(main())
Use the fluent QuerySet API:
# Find multiple documents
users = await User.find(age={"$gte": 18}).sort("name").limit(10).all()
# Count documents
count = await User.find(age={"$gte": 18}).count()
# Check existence
exists = await User.find({"email": "alice@example.com"}).exists()
FastAPI integration
Pygoose works seamlessly with FastAPI:
from fastapi import FastAPI
from pygoose import connect, disconnect, init_app
app = FastAPI()
init_app(app)
@app.on_event("startup")
async def startup():
await connect("mongodb://localhost:27017/my_database")
@app.on_event("shutdown")
async def shutdown():
await disconnect()
@app.post("/users")
async def create_user(user: User):
await user.save()
return user
@app.get("/users/{user_id}")
async def get_user(user_id: str):
from bson import ObjectId
user = await User.find_one({"_id": ObjectId(user_id)})
return user
Documentation
Complete documentation is available in the /docs directory:
- Getting started — Installation and basic usage
- Core concepts — Documents, QuerySet, and references
- Advanced features — Hooks, encryption, and plugins
- API reference — Complete method documentation
- FastAPI integration — Building REST APIs
- Examples — Real-world patterns and use cases
Requirements
- Python 3.11 or higher
- MongoDB 4.4 or higher
- PyMongo 4.8 or higher (async driver)
- Pydantic v2 or higher
License
MIT
Metadata
Release files for pygoose-odm 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pygoose_odm-0.3.1.tar.gz | 76.1 kB | Without provenance | Details for pygoose_odm-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pygoose_odm-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for pygoose_odm-0.3.1-py3-none-any.whl |
Total release size: 107.7 kB
Release files / pygoose_odm-0.3.1.tar.gz
| Download URL | pygoose_odm-0.3.1.tar.gz |
|---|---|
| Size | 76.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1f9d696e3879820b4a92df485783b5ae84f319bfdc250b0a30a1089b0aa4bc03
|
|
BLAKE2b-256 checksum How to use checksums |
b71b5edc6a3960fd5f81aafa6b642f4ef93caefaef847aeef67160e76be66ce5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.17
|
Release files / pygoose_odm-0.3.1-py3-none-any.whl
| Download URL | pygoose_odm-0.3.1-py3-none-any.whl |
|---|---|
| Size | 31.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4c7b6195cc546131b91cdf16ccd0fc068fc08de162c40533df8065f0e4dd3dc1
|
|
BLAKE2b-256 checksum How to use checksums |
84332bdf0845721a863229677cd1f451c6c304aa89f61a663b74ef65aefb92f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.17
|
Security for pygoose-odm 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.