mongoforge-odm 0.1.0__tar.gz

mongoforge_odm-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: mongoforge-odm
+Version: 0.1.0
+Summary: A Django-inspired MongoDB ODM for Python
+Author: Saurabh Singh
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Sourabh7singh/MongoForge
+Project-URL: Repository, https://github.com/Sourabh7singh/MongoForge
+Project-URL: Issues, https://github.com/Sourabh7singh/MongoForge/issues
+Keywords: mongodb,odm,orm,pymongo,django,schema,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pymongo>=4.6
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: python-slugify>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: mongomock>=4.0; extra == "dev"
+
+# 🔧 MongoForge
+
+A **Django-inspired MongoDB ODM** for Python — define document schemas as classes with typed fields, validate data automatically, and perform CRUD operations through a clean manager API.
+
+Built on [PyMongo](https://pymongo.readthedocs.io/).
+
+---
+
+## ✨ Features
+
+- **Declarative schemas** — define documents as Python classes with typed fields
+- **10 built-in field types** — `StringField`, `IntField`, `FloatField`, `BoolField`, `ListField`, `DateTimeField`, `DictField`, `ObjectIdField`, `EmbeddedField` + extensible `BaseField`
+- **Rich validation** — required, min/max length, min/max value, regex, choices, custom validators
+- **Metaclass magic** — automatic field collection, inheritance, collection naming
+- **Manager API** — `create`, `bulk_create`, `all`, `first`, `get`, `filter`, `count`, `update`, `update_one`, `update_many`, `delete_one`, `delete_many`
+- **Django-style filter operators** — `age__gte=18`, `name__in=[...]`, `status__ne="inactive"` (supports: `gt`, `gte`, `lt`, `lte`, `ne`, `in`, `nin`)
+- **Auto timestamps** — `DateTimeField(auto_now=True)` and `auto_now_add=True`
+- **Attribute access** — `user.name` instead of `user["name"]`
+- **Serialization** — `to_mongo()` and `from_mongo()` for round-trip conversion
+- **Abstract models & inheritance** — share fields across model hierarchies
+
+---
+
+## 📦 Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/MongoForge.git
+cd MongoForge
+
+# Create and activate a virtual environment
+python -m venv env
+env\Scripts\activate      # Windows
+# source env/bin/activate # macOS/Linux
+
+# Install dependencies
+pip install pymongo python-dotenv python-slugify
+
+# For running tests (no live MongoDB needed)
+pip install pytest mongomock
+```
+
+### Environment Setup
+
+Create a `.env` file in the project root:
+
+```env
+MONGO_URI=mongodb://localhost:27017/
+DATABASE_NAME=mongoforge
+```
+
+---
+
+## 🚀 Quick Start
+
+### Define a Model
+
+```python
+from mongoforge import MongoForge
+from mongoforge.fields import StringField, IntField, BoolField, DateTimeField, ListField
+
+class User(MongoForge):
+    name     = StringField(required=True, min_length=2, max_length=100)
+    email    = StringField(required=True, regex=r"^[\w.+-]+@[\w-]+\.[\w.-]+$")
+    age      = IntField(min_value=0, max_value=150)
+    is_admin = BoolField(default=False)
+    tags     = ListField(StringField())
+    created  = DateTimeField(auto_now_add=True)
+    updated  = DateTimeField(auto_now=True)
+
+    class Meta:
+        collection = "users"
+```
+
+### Create & Validate
+
+```python
+user = User(name="Saurabh", email="saurabh@example.com", age=25)
+
+# Validate before saving
+user.validate()  # raises ValidationError if invalid
+
+# Serialize to MongoDB document
+doc = user.to_mongo()
+
+# Insert into database
+User.objects.create(doc)
+```
+
+### Query
+
+```python
+# Get all documents
+User.objects.all()                        # → list[dict]
+
+# Filter with operators
+User.objects.filter(age__gte=18)          # age >= 18
+User.objects.filter(name__in=["Alice", "Bob"])
+
+# Get single document
+User.objects.get({"email": "saurabh@example.com"})
+
+# Count
+User.objects.count()
+```
+
+### Update & Delete
+
+```python
+# Update by ID
+User.objects.update(id="...", update_data={"name": "Updated Name"})
+
+# Update many
+User.objects.update_many({"age": {"$gte": 30}}, {"is_admin": True})
+
+# Delete
+User.objects.delete_one({"name": "Alice"})
+User.objects.delete_many({"age": {"$lt": 18}})
+```
+
+### Validation in Action
+
+```python
+from mongoforge.exceptions import ValidationError
+
+user = User(name="A", email="not-an-email", age=-5)
+try:
+    user.validate()
+except ValidationError as exc:
+    print(exc)
+    # Validation failed. name: Minimum length is 2; email: Value does not match regex ...; age: Minimum value is 0
+    print(exc.errors)
+    # {'name': ['Minimum length is 2'], 'email': ['Value does not match regex ...'], 'age': ['Minimum value is 0']}
+```
+
+---
+
+## 📋 Field Types
+
+| Field | Python Type | Extra Options |
+|---|---|---|
+| `StringField` | `str` | `min_length`, `max_length`, `regex` |
+| `IntField` | `int` | `min_value`, `max_value` |
+| `FloatField` | `float` | — |
+| `BoolField` | `bool` | — |
+| `ListField` | `list` | `field` (inner field for item validation) |
+| `DateTimeField` | `datetime` | `auto_now`, `auto_now_add` |
+| `DictField` | `dict` | — |
+| `ObjectIdField` | `ObjectId` | Auto-generates if `None` |
+| `EmbeddedField` | `dict` | `document_class` (stub — Phase 4) |
+
+**Common options** (all fields): `required`, `default`, `unique`, `choices`, `validators`, `null`
+
+---
+
+## 🏗️ Architecture
+
+```
+Model Class  →  MongoForgeMeta (metaclass)  →  collects fields + attaches MongoManager
+                                                          │
+                    ┌─────────────────────────────────────┘
+                    ▼
+              MongoManager (cls.objects)
+              ├── CreateMixin   →  create(), bulk_create()
+              ├── ReadMixin     →  all(), first(), get(), filter(), count()
+              ├── UpdateMixin   →  update(), update_one(), update_many()
+              └── DeleteMixin   →  delete_one(), delete_many()
+```
+
+---
+
+## 🧪 Running Tests
+
+Tests use [mongomock](https://github.com/mongomock/mongomock) — **no live MongoDB required**.
+
+```bash
+# With venv activated
+python -m pytest mongoforge/tests/ -v
+
+# Or using venv python directly
+env\Scripts\python.exe -m pytest mongoforge/tests/ -v
+```
+
+**148 tests** covering:
+- All 10 field types + validation paths
+- Model instances, attribute access, serialization
+- Metaclass, inheritance, abstract models
+- Full CRUD operations + filter operators
+- Exception hierarchy + formatting
+
+---
+
+## 🗺️ Roadmap
+
+| Phase | Description | Status |
+|---|---|---|
+| **Phase 1** | Fields & Schema | ✅ ~95% |
+| **Phase 2** | QuerySet (chainable queries) | ⬜ Not started |
+| **Phase 3** | Model Lifecycle (`save()`, `delete()`, `reload()`, dirty tracking) | 🔶 ~50% |
+| **Phase 4** | Relationships (EmbeddedDocument, ReferenceField) | ⬜ Not started |
+| **Phase 5** | Indexes, Middleware & CLI | ⬜ Not started |
+| **Phase 6** | Packaging & Developer Experience | 🔶 ~30% |
+
+See [implementation_plan.md](implementation_plan.md) for the full roadmap with target APIs.

mongoforge_odm-0.1.0/README.md

@@ -0,0 +1,204 @@
+# 🔧 MongoForge
+
+A **Django-inspired MongoDB ODM** for Python — define document schemas as classes with typed fields, validate data automatically, and perform CRUD operations through a clean manager API.
+
+Built on [PyMongo](https://pymongo.readthedocs.io/).
+
+---
+
+## ✨ Features
+
+- **Declarative schemas** — define documents as Python classes with typed fields
+- **10 built-in field types** — `StringField`, `IntField`, `FloatField`, `BoolField`, `ListField`, `DateTimeField`, `DictField`, `ObjectIdField`, `EmbeddedField` + extensible `BaseField`
+- **Rich validation** — required, min/max length, min/max value, regex, choices, custom validators
+- **Metaclass magic** — automatic field collection, inheritance, collection naming
+- **Manager API** — `create`, `bulk_create`, `all`, `first`, `get`, `filter`, `count`, `update`, `update_one`, `update_many`, `delete_one`, `delete_many`
+- **Django-style filter operators** — `age__gte=18`, `name__in=[...]`, `status__ne="inactive"` (supports: `gt`, `gte`, `lt`, `lte`, `ne`, `in`, `nin`)
+- **Auto timestamps** — `DateTimeField(auto_now=True)` and `auto_now_add=True`
+- **Attribute access** — `user.name` instead of `user["name"]`
+- **Serialization** — `to_mongo()` and `from_mongo()` for round-trip conversion
+- **Abstract models & inheritance** — share fields across model hierarchies
+
+---
+
+## 📦 Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/MongoForge.git
+cd MongoForge
+
+# Create and activate a virtual environment
+python -m venv env
+env\Scripts\activate      # Windows
+# source env/bin/activate # macOS/Linux
+
+# Install dependencies
+pip install pymongo python-dotenv python-slugify
+
+# For running tests (no live MongoDB needed)
+pip install pytest mongomock
+```
+
+### Environment Setup
+
+Create a `.env` file in the project root:
+
+```env
+MONGO_URI=mongodb://localhost:27017/
+DATABASE_NAME=mongoforge
+```
+
+---
+
+## 🚀 Quick Start
+
+### Define a Model
+
+```python
+from mongoforge import MongoForge
+from mongoforge.fields import StringField, IntField, BoolField, DateTimeField, ListField
+
+class User(MongoForge):
+    name     = StringField(required=True, min_length=2, max_length=100)
+    email    = StringField(required=True, regex=r"^[\w.+-]+@[\w-]+\.[\w.-]+$")
+    age      = IntField(min_value=0, max_value=150)
+    is_admin = BoolField(default=False)
+    tags     = ListField(StringField())
+    created  = DateTimeField(auto_now_add=True)
+    updated  = DateTimeField(auto_now=True)
+
+    class Meta:
+        collection = "users"
+```
+
+### Create & Validate
+
+```python
+user = User(name="Saurabh", email="saurabh@example.com", age=25)
+
+# Validate before saving
+user.validate()  # raises ValidationError if invalid
+
+# Serialize to MongoDB document
+doc = user.to_mongo()
+
+# Insert into database
+User.objects.create(doc)
+```
+
+### Query
+
+```python
+# Get all documents
+User.objects.all()                        # → list[dict]
+
+# Filter with operators
+User.objects.filter(age__gte=18)          # age >= 18
+User.objects.filter(name__in=["Alice", "Bob"])
+
+# Get single document
+User.objects.get({"email": "saurabh@example.com"})
+
+# Count
+User.objects.count()
+```
+
+### Update & Delete
+
+```python
+# Update by ID
+User.objects.update(id="...", update_data={"name": "Updated Name"})
+
+# Update many
+User.objects.update_many({"age": {"$gte": 30}}, {"is_admin": True})
+
+# Delete
+User.objects.delete_one({"name": "Alice"})
+User.objects.delete_many({"age": {"$lt": 18}})
+```
+
+### Validation in Action
+
+```python
+from mongoforge.exceptions import ValidationError
+
+user = User(name="A", email="not-an-email", age=-5)
+try:
+    user.validate()
+except ValidationError as exc:
+    print(exc)
+    # Validation failed. name: Minimum length is 2; email: Value does not match regex ...; age: Minimum value is 0
+    print(exc.errors)
+    # {'name': ['Minimum length is 2'], 'email': ['Value does not match regex ...'], 'age': ['Minimum value is 0']}
+```
+
+---
+
+## 📋 Field Types
+
+| Field | Python Type | Extra Options |
+|---|---|---|
+| `StringField` | `str` | `min_length`, `max_length`, `regex` |
+| `IntField` | `int` | `min_value`, `max_value` |
+| `FloatField` | `float` | — |
+| `BoolField` | `bool` | — |
+| `ListField` | `list` | `field` (inner field for item validation) |
+| `DateTimeField` | `datetime` | `auto_now`, `auto_now_add` |
+| `DictField` | `dict` | — |
+| `ObjectIdField` | `ObjectId` | Auto-generates if `None` |
+| `EmbeddedField` | `dict` | `document_class` (stub — Phase 4) |
+
+**Common options** (all fields): `required`, `default`, `unique`, `choices`, `validators`, `null`
+
+---
+
+## 🏗️ Architecture
+
+```
+Model Class  →  MongoForgeMeta (metaclass)  →  collects fields + attaches MongoManager
+                                                          │
+                    ┌─────────────────────────────────────┘
+                    ▼
+              MongoManager (cls.objects)
+              ├── CreateMixin   →  create(), bulk_create()
+              ├── ReadMixin     →  all(), first(), get(), filter(), count()
+              ├── UpdateMixin   →  update(), update_one(), update_many()
+              └── DeleteMixin   →  delete_one(), delete_many()
+```
+
+---
+
+## 🧪 Running Tests
+
+Tests use [mongomock](https://github.com/mongomock/mongomock) — **no live MongoDB required**.
+
+```bash
+# With venv activated
+python -m pytest mongoforge/tests/ -v
+
+# Or using venv python directly
+env\Scripts\python.exe -m pytest mongoforge/tests/ -v
+```
+
+**148 tests** covering:
+- All 10 field types + validation paths
+- Model instances, attribute access, serialization
+- Metaclass, inheritance, abstract models
+- Full CRUD operations + filter operators
+- Exception hierarchy + formatting
+
+---
+
+## 🗺️ Roadmap
+
+| Phase | Description | Status |
+|---|---|---|
+| **Phase 1** | Fields & Schema | ✅ ~95% |
+| **Phase 2** | QuerySet (chainable queries) | ⬜ Not started |
+| **Phase 3** | Model Lifecycle (`save()`, `delete()`, `reload()`, dirty tracking) | 🔶 ~50% |
+| **Phase 4** | Relationships (EmbeddedDocument, ReferenceField) | ⬜ Not started |
+| **Phase 5** | Indexes, Middleware & CLI | ⬜ Not started |
+| **Phase 6** | Packaging & Developer Experience | 🔶 ~30% |
+
+See [implementation_plan.md](implementation_plan.md) for the full roadmap with target APIs.

mongoforge_odm-0.1.0/mongoforge/__init__.py

@@ -0,0 +1,5 @@
+from .models import MongoForge
+
+__all__ = [
+    "MongoForge"
+]

mongoforge_odm-0.1.0/mongoforge/client.py

@@ -0,0 +1,19 @@
+from pymongo import MongoClient
+from pymongo.errors import PyMongoError
+
+from .settings import MONGO_URI
+from .exceptions import DatabaseConnectionError
+
+_client = None
+
+def get_client():
+    global _client
+    try:
+        if _client is None:
+            _client = MongoClient(MONGO_URI)
+            _client.admin.command("ping")
+        return _client
+    except PyMongoError as e:
+        raise DatabaseConnectionError(
+            f"Failed to connect to MongoDB: {e}"
+        ) from e

mongoforge_odm-0.1.0/mongoforge/exceptions.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Dict, List
+
+class MongoForgeError(Exception):
+    """Base exception for all MongoForge errors."""
+
+
+class DatabaseConnectionError(MongoForgeError):
+    """Raised when MongoForge cannot connect to MongoDB."""
+
+
+class CollectionError(MongoForgeError):
+    """Raised when a collection-related operation fails."""
+
+
+class ValidationError(MongoForgeError):
+    """
+    Raised when document validation fails.
+
+    Example:
+        raise ValidationError({
+            "email": ["This field is required"],
+            "age": ["Must be greater than 0"]
+        })
+    """
+
+    def __init__(self, errors: Dict[str, List[str]]) -> None:
+        self.errors = errors
+
+        message = self._build_message(errors)
+        super().__init__(message)
+
+    @staticmethod
+    def _build_message(errors: Dict[str, List[str]]) -> str:
+        if not errors:
+            return "Validation failed."
+
+        parts = []
+
+        for field, field_errors in errors.items():
+            if not field_errors:
+                continue
+
+            parts.append(f"{field}: {', '.join(field_errors)}")
+
+        if not parts:
+            return "Validation failed."
+
+        return f"Validation failed. {'; '.join(parts)}"
+
+
+class DocumentNotFoundError(MongoForgeError):
+    """
+    Raised when a requested document cannot be found.
+    """
+
+    def __init__(self, message: str = "Document not found.") -> None:
+        super().__init__(message)

mongoforge_odm-0.1.0/mongoforge/fields/__init__.py

@@ -0,0 +1,24 @@
+from .base import BaseField
+from .types import (
+    StringField,
+    IntField,
+    FloatField,
+    BoolField,
+    DictField,
+    ObjectIdField,
+    ListField,
+    DateTimeField,
+    EmbeddedField,
+)
+__all__ = [
+    "BaseField",
+    "StringField",
+    "IntField",
+    "FloatField",
+    "BoolField",
+    "DictField",
+    "ObjectIdField",
+    "ListField",
+    "DateTimeField",
+    "EmbeddedField",
+]

mongoforge_odm-0.1.0/mongoforge/fields/base.py

@@ -0,0 +1,63 @@
+
+
+class BaseField:
+    python_type = object
+
+    def __init__(
+        self,
+        *,
+        required=False,
+        default=None,
+        unique=False,
+        choices=None,
+        validators=None,
+        null=False,
+    ):
+        self.name = None
+        self.required = required
+        self.default = default
+        self.unique = unique
+        self.choices = choices or []
+        self.validators = validators or []
+        self.null = null
+        
+    def get_default(self):
+        if callable(self.default):
+            return self.default()
+        return self.default
+    
+    def to_python(self, value):
+        return value
+    
+    def to_mongo(self, value):
+        return value
+    
+    def validate(self, value):
+        errors = []
+
+        if value is None:
+            if self.required and not self.null:
+                errors.append("This field is required.")
+            return errors
+
+        if (
+            self.python_type is not object
+            and not isinstance(value, self.python_type)
+        ):
+            errors.append(
+                f"Expected {self.python_type.__name__}, got {type(value).__name__}"
+            )
+            return errors
+
+        if self.choices and value not in self.choices:
+            errors.append(
+                f"Value must be one of: {self.choices}"
+            )
+
+        for validator in self.validators:
+            try:
+                validator(value)
+            except ValueError as e:
+                errors.append(str(e))
+
+        return errors