Skip to main content
Archived

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:

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)

Source distribution for pygoose-odm 0.3.1
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)

Table of built distributions (wheels) for pygoose-odm 0.3.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page