Metadata-Version: 2.3
Name: gdmongolite
Version: 0.1.2
Summary: gdmongolite is a zero-boilerplate, schema-first, multi-driver MongoDB toolkit that unifies synchronous and asynchronous drivers, Pydantic-powered validation, automatic migrations, telemetry hooks, and a full CLI—all in one package. You write only your data models and queries; gdmongolite handles the rest.
License: MIT
Author: Ganesh Datta Padamata
Author-email: ganeshdattapadamata@gmail.com
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: aioconsole (>=0.6.1,<0.7.0)
Requires-Dist: click (>=8.0,<9.0)
Requires-Dist: motor (>=3.3.2,<4.0.0)
Requires-Dist: pydantic[email] (>=2.5.3,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
Description-Content-Type: text/markdown

# gdmongolite Documentation
**gdmongolite** is a zero-boilerplate, schema-first, multi-driver MongoDB toolkit that unifies synchronous and asynchronous drivers, Pydantic-powered validation, automatic migrations, telemetry hooks, and a full CLI—all in one package. You write only your data models and queries; gdmongolite handles the rest.

## Table of Contents
1. Installation
2. Configuration
3. Defining Schemas
4. Connecting to MongoDB
5. CRUD Operations
6. Automatic Migrations
7. Interactive Shell
8. Model Generation
9. Telemetry Hooks
10. CLI Reference
11. Testing
12. Project Layout
13. Best Practices
14. FAQ

## 1. Installation
Install the latest release from PyPI:
```bash
pip install gdmongolite
```
For development tools (linters, test frameworks):
```bash
pip install gdmongolite[dev]
```

## 2. Configuration
gdmongolite loads MongoDB connection settings from a `.env` file or environment variables. Create `.env` in your project root:
```dotenv
MONGO_URI="mongodb://localhost:27017"
MONGO_DB="myapp"
MONGO_MAX_POOL=50
MONGO_MIN_POOL=5
MONGO_TIMEOUT_MS=30000
```
Alternatively, set environment variables directly:
```bash
export MONGO_URI="mongodb://db.example.com:27017"
```
gdmongolite uses these settings automatically—no additional code required.

## 3. Defining Schemas
All your data models inherit from `Schema`. Collections are named automatically (snake_case of the class name).
```python
# src/gdmongolite/schema/__init__.py
from gdmongolite import DB, Schema, Email, Positive

# Create or reuse the default DB instance
db = DB()

class User(Schema):
    """User document with validation"""
    name: str               # any non-empty string
    email: Email            # must match email format
    age: Positive()         # must be > 0
    tags: list[str] = []    # default to empty list

# After definition, db.User refers to this class
assert db.User is User
```
Behind the scenes, gdmongolite:
- Inherits Pydantic’s validation
- Binds `User` to the `user` collection
- Adds built-in CRUD methods

## 4. Connecting to MongoDB
Import and instantiate the singleton façade:
```python
from gdmongolite import DB

# Uses .env or env vars; auto-detects sync/async context
db = DB()

# Or explicitly sync or async:
db_sync = DB(mode="sync")
db_async = DB(mode="async")

# Manually specify URI:
db_custom = DB("mongodb://localhost:27017", database="testdb")
```
Close connections when done:
```python
await db.close()         # async
db_sync.close_sync()     # sync
```

## 5. CRUD Operations
gdmongolite exposes simple, consistent methods on each `Schema` subclass.
| Operation        | Async Example                                                 | Sync Example                                              |
|------------------|---------------------------------------------------------------|-----------------------------------------------------------|
| Insert one       | `await db.User.insert({"name":"Alice","email":"a@b.com","age":30})` | `db.User.insert_sync({...})`                              |
| Find many        | `await db.User.find(age__gte=18).to_list()`                   | `db.User.find(age__gte=18).to_list_sync()`                |
| Update one       | `await db.User.update({"_id": id}, {"age":31})`               | `db.User.update_sync({...}, {...})`                       |
| Delete many      | `await db.User.delete(age__lt=13)`                            | `db.User.delete_sync(age__lt=13)`                         |
Every operation returns a `QueryResponse`:
```python
{
  "success": True,
  "data": [...],       # inserted IDs or found documents
  "count": 3,
  "message": "Found 3 documents"
}
```

## 6. Automatic Migrations
When your schemas change (add/remove fields or indexes), generate migration scripts:
```bash
gdmongolite migrate
```
- Compares current schema definitions to the live database
- Creates timestamped Python scripts in `migrations/`
- Apply migrations automatically at startup or manually:
```python
await db.migrate_all()
```

## 7. Interactive Shell
Launch a REPL pre-loaded with `db` and your schemas:
```bash
gdmongolite shell
```
Inside:
```python
>>> await db.User.insert({"name":"Bob","email":"bob@x.com","age":25})
>>> users = await db.User.find().to_list()
>>> print(users)
```

## 8. Model Generation
Scaffold a Python schema from an existing collection:
```bash
gdmongolite gen-model \
  --collection products \
  --out src/models/product.py
```
- Samples document fields and types
- Generates a `Product(Schema)` class with inferred attributes

## 9. Telemetry Hooks
Monitor or instrument queries by registering hooks:
```python
from gdmongolite import DB

@DB.on("pre_query")
def before_query(collection, filt, opts):
    print(f"Querying {collection}: {filt}")

@DB.on("post_query")
def after_query(collection, result):
    print(f"{collection} returned {result.count} docs in {result.duration}ms")
```
Supported events: `pre_query`, `post_query`, `pre_insert`, `post_insert`, etc. Integrate with any metrics or logging system.

## 10. CLI Reference
```bash
gdmongolite --help
```
| Command           | Description                                      |
|-------------------|--------------------------------------------------|
| migrate           | Generate and apply migration scripts             |
| shell             | Launch interactive REPL                          |
| gen-model         | Scaffold a schema from an existing collection    |
| test              | Run the test suite                               |
Use `gdmongolite  --help` for command-specific options.

## 11. Testing
Install development dependencies:
```bash
pip install gdmongolite[dev]
pytest --maxfail=1 --disable-warnings -q
```
- Uses `pytest-asyncio` for async tests
- Aim for ≥ 95% code coverage

## 12. Project Layout
```
gdmongolite/
├── src/gdmongolite/
│   ├── __init__.py
│   ├── core.py            # DB façade and connection logic
│   ├── schema.py          # Schema metaclass and built-in types
│   ├── query.py           # Filter parser and Cursor class
│   ├── migrate.py         # Migration engine
│   ├── telemetry.py       # Hook registry
│   ├── cli.py             # Click-based CLI commands
│   ├── config.py          # Pydantic BaseSettings
│   └── utils.py           # Internal helpers
├── migrations/            # Auto-generated migration scripts
├── tests/                 # Unit and integration tests
├── README.md
├── LICENSE
├── pyproject.toml
└── .env
```

## 13. Best Practices
- **Keep schemas focused**: One schema per document type
- **Commit migrations**: Ensure your database schema changes are versioned
- **Use telemetry**: Capture performance and error metrics early
- **Test across modes**: Run tests in both sync and async contexts
- **Leverage CLI**: Automate repetitive tasks (shell, migrations, model generation)

## 14. FAQ
**Q: How to handle large datasets?**
A: Use cursor batching:
```python
cursor = db.User.find().batch_size(100)
for batch in await cursor.to_list():
    process(batch)
```
**Q: Can I integrate with FastAPI?**
A: Yes. Initialize `db` in your startup event and import schemas into routers.
**Q: Are transactions supported?**
A: Use:
```python
async with db.transaction():
    await db.Order.insert({...})
    await db.Inventory.update({...})
```
gdmongolite empowers everyone—from beginners to experts—to build MongoDB-backed applications with minimal boilerplate, robust validation, and comprehensive tooling. Start coding and let gdmongolite handle the rest

## Author
**Ganesh Datta Padamata**
Email: ganeshdattapadamata@gmail.com
PyPI: ganeshdatta999
