Metadata-Version: 2.4
Name: pygoose-odm
Version: 0.2.0
Summary: Async-first MongoDB ODM for Python, powered by Pydantic v2
Author-email: Bhargav Andhe <bhargavandhe2310@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bhargavandhe/pygoose
Project-URL: Documentation, https://github.com/bhargavandhe/pygoose/tree/main/docs
Project-URL: Repository, https://github.com/bhargavandhe/pygoose.git
Project-URL: Bug Tracker, https://github.com/bhargavandhe/pygoose/issues
Project-URL: Changelog, https://github.com/bhargavandhe/pygoose/blob/main/CHANGELOG.md
Keywords: mongodb,odm,async,pydantic,asyncio,motor,mongoose,database,orm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Framework :: AsyncIO
Classifier: Framework :: FastAPI
Classifier: Framework :: Pydantic
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pymongo>=4.8
Requires-Dist: pydantic>=2.4
Requires-Dist: fastapi>=0.128.4
Requires-Dist: uvicorn>=0.40.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: cryptography>=46.0.4
Provides-Extra: encryption
Requires-Dist: cryptography>=42.0; extra == "encryption"
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == "fastapi"
Requires-Dist: uvicorn>=0.40; extra == "fastapi"
Dynamic: license-file

# 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

```bash
pip install pygoose
```

Optional dependencies:

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

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

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

```python
# 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:

```python
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](docs/GETTING_STARTED.md) — Installation and basic usage
- [Core concepts](docs/CORE_CONCEPTS.md) — Documents, QuerySet, and references
- [Advanced features](docs/ADVANCED_FEATURES.md) — Hooks, encryption, and
  plugins
- [API reference](docs/API_REFERENCE.md) — Complete method documentation
- [FastAPI integration](docs/FASTAPI_INTEGRATION.md) — Building REST APIs
- [Examples](docs/EXAMPLES.md) — 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
