mongoforge-odm 0.1.0__py3-none-any.whl

mongoforge/__init__.py

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

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/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/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/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

mongoforge/fields/types.py

@@ -0,0 +1,149 @@
+from .base import BaseField
+import re
+from bson import ObjectId
+from datetime import datetime
+
+class StringField(BaseField):
+    python_type = str
+    def __init__(
+        self,
+        *,
+        min_length=None,
+        max_length=None,
+        regex=None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.min_length = min_length
+        self.max_length = max_length
+        self.regex = regex
+        
+    def validate(self, value):
+        errors = super().validate(value)
+        if value is None:
+            return errors
+        
+        if self.min_length is not None:
+            if len(value) < self.min_length:
+                errors.append(
+                    f"Minimum length is {self.min_length}"
+                )
+    
+        if self.max_length is not None:
+            if len(value) > self.max_length:
+                errors.append(
+                    f"Maximum length is {self.max_length}"
+                )
+        
+        if self.regex:
+            if re.match(self.regex, value) is None:
+                errors.append(
+                    f"Value does not match regex {self.regex}"
+                )
+
+        return errors
+                
+class IntField(BaseField):
+    python_type = int
+    def __init__(
+        self,
+        *,
+        min_value=None,
+        max_value=None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.min_value = min_value
+        self.max_value = max_value
+
+    def validate(self, value):
+        errors = super().validate(value)
+        if value is None:
+            return errors
+
+        if self.min_value is not None:
+            if value < self.min_value:
+                errors.append(
+                    f"Minimum value is {self.min_value}"
+                )
+                
+        if self.max_value is not None:
+            if value > self.max_value:
+                errors.append(
+                    f"Maximum value is {self.max_value}"
+                )
+
+        return errors
+        
+class FloatField(BaseField):
+    python_type = float
+    
+class BoolField(BaseField):
+    python_type = bool
+    
+class DictField(BaseField):
+    python_type = dict
+    
+class ObjectIdField(BaseField):
+    python_type = ObjectId
+    
+    def to_mongo(self, value):
+        if value is None:
+            return ObjectId()
+        return value
+
+class ListField(BaseField):
+    python_type = list
+    
+    def __init__(self, field=None, **kwargs):
+        super().__init__(**kwargs)
+        self.field = field    
+
+    def validate(self, value):
+        errors = super().validate(value)
+        
+        if value is None:
+            return errors
+
+        if self.field:
+            for i, item in enumerate(value):
+                item_errors = self.field.validate(item)
+                for error in item_errors:
+                    errors.append(f"[{i}] {error}")
+
+        return errors
+                    
+class DateTimeField(BaseField):
+    python_type = datetime
+    
+    def __init__(
+        self,
+        *,
+        auto_now=False,
+        auto_now_add=False,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.auto_now = auto_now
+        self.auto_now_add = auto_now_add
+        
+    
+    def validate(self, value):
+        if (
+            value is None
+            and (self.auto_now or self.auto_now_add)
+        ):
+            return []
+
+        return super().validate(value)
+
+class EmbeddedField(BaseField):
+    python_type = dict
+
+    def __init__(
+        self,
+        document_class=None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.document_class = document_class

mongoforge/managers/__init__.py

@@ -0,0 +1,5 @@
+from .base import MongoManager
+
+__all__ = [
+    "MongoManager"
+]

mongoforge/managers/base.py

@@ -0,0 +1,16 @@
+from .helpers import ManagerHelper
+from .create import CreateMixin
+from .read import ReadMixin
+from .update import UpdateMixin
+from .delete import DeleteMixin
+
+
+class MongoManager(
+    ManagerHelper,
+    CreateMixin,
+    ReadMixin,
+    UpdateMixin,
+    DeleteMixin
+):
+    def __init__(self, collection_name: str):
+        self._initialize(collection_name)

mongoforge/managers/create.py

@@ -0,0 +1,25 @@
+from pymongo.errors import PyMongoError
+
+from ..exceptions import CollectionError
+
+
+class CreateMixin:
+    def create(self, data: dict):
+        try:
+            result = self._collection.insert_one(data)
+            return result.inserted_id
+        except PyMongoError as e:
+            raise CollectionError(
+                f"Failed to create document in "
+                f"'{self._collection_name}'"
+            ) from e
+
+    def bulk_create(self, data: list[dict]):
+        try:
+            result = self._collection.insert_many(data)
+            return result.inserted_ids
+        except PyMongoError as e:
+            raise CollectionError(
+                f"Failed to bulk create documents in "
+                f"'{self._collection_name}'"
+            ) from e

mongoforge/managers/delete.py

@@ -0,0 +1,25 @@
+from pymongo.errors import PyMongoError
+
+from ..exceptions import CollectionError
+
+
+class DeleteMixin:
+    def delete_one(self, query: dict):
+        try:
+            result = self._collection.delete_one(query)
+            return result.deleted_count
+        except PyMongoError as e:
+            raise CollectionError(
+                f"Failed to delete document from "
+                f"'{self._collection_name}'"
+            ) from e
+
+    def delete_many(self, query: dict):
+        try:
+            result = self._collection.delete_many(query)
+            return result.deleted_count
+        except PyMongoError as e:
+            raise CollectionError(
+                f"Failed to delete documents from "
+                f"'{self._collection_name}'"
+            ) from e

mongoforge/managers/helpers.py

@@ -0,0 +1,20 @@
+
+from slugify import slugify
+
+from ..client import get_client
+from ..settings import DATABASE_NAME
+
+
+class ManagerHelper:
+    def _initialize(self, collection_name: str):
+        self._client = get_client()
+        self._database = self._client[DATABASE_NAME]
+
+        self._collection_name = slugify(
+            collection_name,
+            separator="_"
+        )
+
+        self._collection = self._database[
+            self._collection_name
+        ]   

mongoforge/managers/read.py

@@ -0,0 +1,73 @@
+from typing import List
+from pymongo.errors import PyMongoError
+
+from ..exceptions import CollectionError
+
+
+class ReadMixin:
+
+    OPERATORS = {
+        "gt": "$gt",
+        "gte": "$gte",
+        "lt": "$lt",
+        "lte": "$lte",
+        "ne": "$ne",
+        "in": "$in",
+        "nin": "$nin",
+    }
+
+    def all(self) -> List[dict]:
+        try:
+            return list(self._collection.find())
+        except PyMongoError as e:
+            raise CollectionError(
+                f"Failed to fetch documents from "
+                f"'{self._collection_name}'"
+            ) from e
+
+    def first(self):
+        try:
+            return self._collection.find_one()
+        except PyMongoError as e:
+            raise CollectionError(
+                f"Failed to fetch document from "
+                f"'{self._collection_name}'"
+            ) from e
+
+    def get(self, query: dict):
+        try:
+            return self._collection.find_one(query)
+        except PyMongoError as e:
+            raise CollectionError(
+                f"Failed to fetch document from "
+                f"'{self._collection_name}'"
+            ) from e
+
+    def filter(self, **kwargs):
+        query = {}
+
+        for key, value in kwargs.items():
+            if "__" in key:
+                field, op = key.split("__", 1)
+                mongo_op = self.OPERATORS.get(op)
+
+                if not mongo_op:
+                    raise ValueError(
+                        f"Unsupported operator: {op}"
+                    )
+
+                query[field] = {mongo_op: value}
+            else:
+                query[key] = value
+
+
+        return list(self._collection.find(query))
+    
+    def count(self):
+        try:
+            return self._collection.count_documents({})
+        except PyMongoError as e:
+            raise CollectionError(
+                f"Failed to count documents in "
+                f"'{self._collection_name}'"
+            ) from e

mongoforge/managers/update.py

@@ -0,0 +1,56 @@
+from pymongo.errors import PyMongoError
+from bson.objectid import ObjectId
+from ..exceptions import CollectionError
+
+
+class UpdateMixin:
+    def update(
+        self,
+        id:int,
+        update_data:dict
+    ):
+        try:
+            result = self._collection.update_one(
+                {"_id":ObjectId(id)},
+                {"$set": update_data}
+            )
+            return result.modified_count
+        except PyMongoError as e:
+            raise CollectionError(
+                f"Failed to update document in "
+                f"'{self._collection_name}'"
+            ) from e
+    
+    def update_one(
+        self,
+        filter_query: dict,
+        update_data: dict
+    ):
+        try:
+            result = self._collection.update_one(
+                filter_query,
+                {"$set": update_data}
+            )
+            return result.modified_count
+        except PyMongoError as e:
+            raise CollectionError(
+                f"Failed to update document in "
+                f"'{self._collection_name}'"
+            ) from e
+
+    def update_many(
+        self,
+        filter_query: dict,
+        update_data: dict
+    ):
+        try:
+            result = self._collection.update_many(
+                filter_query,
+                {"$set": update_data}
+            )
+            return result.modified_count
+        except PyMongoError as e:
+            raise CollectionError(
+                f"Failed to update documents in "
+                f"'{self._collection_name}'"
+            ) from e

mongoforge/meta.py

@@ -0,0 +1,114 @@
+from slugify import slugify
+
+from .fields.base import BaseField
+from .managers import MongoManager
+
+
+class Options:
+    def __init__(self):
+        self.collection = None
+        self.indexes = []
+        self.ordering = []
+        self.abstract = False
+
+
+class MongoForgeMeta(type):
+    """
+    Metaclass responsible for:
+
+    - Collecting fields
+    - Handling inheritance
+    - Building model metadata
+    - Attaching MongoManager
+    """
+
+    def __new__(mcls, name, bases, attrs):
+        # -------------------------
+        # 1. Inherit parent fields
+        # -------------------------
+        fields = {}
+
+        for base in bases:
+            if hasattr(base, "_fields"):
+                fields.update(base._fields)
+
+        # -------------------------
+        # 2. Collect declared fields
+        # -------------------------
+        for attr_name, value in list(attrs.items()):
+            if isinstance(value, BaseField):
+                value.name = attr_name
+                fields[attr_name] = value
+
+                # Prevent class attribute shadowing
+                attrs.pop(attr_name)
+
+        # -------------------------
+        # 3. Create class
+        # -------------------------
+        cls = super().__new__(mcls, name, bases, attrs)
+
+        cls._fields = fields
+
+        # -------------------------
+        # 4. Build Meta options
+        # -------------------------
+        options = Options()
+
+        # inherit parent meta
+        for base in bases:
+            if hasattr(base, "_meta"):
+                parent = base._meta
+
+                options.collection = parent.collection
+                options.indexes = list(parent.indexes)
+                options.ordering = list(parent.ordering)
+                options.abstract = parent.abstract
+
+                break
+
+        meta = attrs.get("Meta")
+
+        if meta:
+            options.collection = getattr(
+                meta,
+                "collection",
+                options.collection,
+            )
+
+            options.indexes = getattr(
+                meta,
+                "indexes",
+                options.indexes,
+            )
+
+            options.ordering = getattr(
+                meta,
+                "ordering",
+                options.ordering,
+            )
+
+            options.abstract = getattr(
+                meta,
+                "abstract",
+                options.abstract,
+            )
+
+        # -------------------------
+        # 5. Default collection name
+        # -------------------------
+        if not options.collection:
+            options.collection = slugify(name)
+
+        cls._meta = options
+
+        # -------------------------
+        # 6. Attach manager
+        # -------------------------
+        if (
+            name != "MongoForge"
+            and not options.abstract
+        ):
+            cls.objects = MongoManager(options.collection)
+
+        return cls

mongoforge/models.py

@@ -0,0 +1,132 @@
+from datetime import datetime
+
+from .exceptions import ValidationError
+from .fields.types import DateTimeField
+from .meta import MongoForgeMeta
+
+
+class MongoForge(metaclass=MongoForgeMeta):
+    """
+    Base class for all MongoForge models.
+    """
+
+    def __init__(self, **kwargs):
+        # Internal state
+        super().__setattr__("_data", {})
+        super().__setattr__("_is_new", True)
+
+        # Populate declared fields
+        for field_name, field in self._fields.items():
+            if field_name in kwargs:
+                value = kwargs.pop(field_name)
+            else:
+                value = field.get_default()
+
+            self._data[field_name] = value
+
+        # Store unknown fields (strict=False)
+        for key, value in kwargs.items():
+            self._data[key] = value
+
+    def __getattr__(self, name):
+        """
+        Return declared field values from _data.
+        """
+        if name in self._fields:
+            return self._data.get(name)
+
+        raise AttributeError(
+            f"{self.__class__.__name__!r} object has no attribute {name!r}"
+        )
+
+    def __setattr__(self, name, value):
+        """
+        Store declared fields inside _data.
+        """
+        # Internal/private attributes
+        if name.startswith("_"):
+            super().__setattr__(name, value)
+            return
+
+        # Model fields
+        if hasattr(self, "_fields") and name in self._fields:
+            self._data[name] = value
+            return
+
+        # Normal Python attribute
+        super().__setattr__(name, value)
+
+    def __repr__(self):
+        values = ", ".join(
+            f"{field}={self._data.get(field)!r}"
+            for field in self._fields
+        )
+
+        return f"<{self.__class__.__name__} {values}>"
+
+    def validate(self):
+        """
+        Validate every declared field.
+        """
+        errors = {}
+
+        for field_name, field in self._fields.items():
+            field_errors = field.validate(
+                self._data.get(field_name)
+            )
+
+            if field_errors:
+                errors[field_name] = field_errors
+
+        if errors:
+            raise ValidationError(errors)
+
+    def to_mongo(self):
+        """
+        Serialize model into a MongoDB document.
+        """
+        document = {}
+
+        for field_name, field in self._fields.items():
+            value = self._data.get(field_name)
+
+            # Handle DateTime auto fields
+            if isinstance(field, DateTimeField):
+
+                if field.auto_now:
+                    value = datetime.utcnow()
+                    self._data[field_name] = value
+
+                elif field.auto_now_add and value is None:
+                    value = datetime.utcnow()
+                    self._data[field_name] = value
+
+            document[field_name] = field.to_mongo(value)
+
+        # Preserve MongoDB ObjectId
+        if "_id" in self._data:
+            document["_id"] = self._data["_id"]
+
+        return document
+
+    @classmethod
+    def from_mongo(cls, raw_doc):
+        """
+        Create a model instance from a MongoDB document.
+        """
+        instance = cls()
+
+        instance._data = {}
+
+        for field_name, field in cls._fields.items():
+            raw_value = raw_doc.get(field_name)
+
+            instance._data[field_name] = field.to_python(raw_value)
+
+        # Preserve _id
+        if "_id" in raw_doc:
+            instance._data["_id"] = raw_doc["_id"]
+
+        instance._is_new = False
+
+        return instance

mongoforge/settings.py

@@ -0,0 +1,7 @@
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+MONGO_URI = os.getenv("MONGO_URI")
+DATABASE_NAME = os.getenv("DATABASE_NAME")

mongoforge/utils/__init__.py

@@ -0,0 +1,8 @@
+from .dates import utcnow
+from .validation import validate_regex
+
+
+__all__ = [
+    "utcnow",
+    "validate_regex",
+]

mongoforge/utils/dates.py

@@ -0,0 +1,4 @@
+from datetime import datetime
+
+def utcnow():
+    return datetime.utcnow()

mongoforge/utils/validation.py

@@ -0,0 +1,4 @@
+import re
+
+def validate_regex(value, pattern):
+    return re.match(pattern, value) is not None

mongoforge_odm-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,25 @@
+mongoforge/__init__.py,sha256=0qHH5iKrjQvEFacaXUDwYAyg1S91WBedPP17oTJx_Z0,66
+mongoforge/client.py,sha256=WSpyvQOdjBLG6FouAByhPvFijp8LF0b_E_8qK6Qewys,506
+mongoforge/exceptions.py,sha256=5n6e6xqqTX4bOhMQtHbRQKaQjx1-lZfC9P_oP9FUCd8,1529
+mongoforge/meta.py,sha256=DZaCan-L76W_YIU19bxiGr5aMp8dVCgSO-mnb9FI1RY,3015
+mongoforge/models.py,sha256=oFGbw0ZN-FmCcBhRvTWfRt6bt4pImSThZH6Jo0434Hk,3628
+mongoforge/settings.py,sha256=x1WXE4TRh69Ez0q4bo9kHOo1HUOHkQH3J_OKSojLsJ8,140
+mongoforge/fields/__init__.py,sha256=vWLGCTLysk1DyOV0KtR6DnQlZOGVZd1H6WP_8DMFl7M,420
+mongoforge/fields/base.py,sha256=HXvbIGscKyjk03k0wTe_0yUV8K0yvxBtOPP3t8C21ks,1594
+mongoforge/fields/types.py,sha256=nnucR4nzr8Xsk9YdJAxlxICcbQ286ns1Ot5L7_uCl5o,3784
+mongoforge/fields/utils.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mongoforge/managers/__init__.py,sha256=fQVnl-ccLPoNMXZma_FyGhfJZ43N-qOaFr4lzr3b9S0,68
+mongoforge/managers/base.py,sha256=jm7UyuEqkiwbHWZaCy2goMLIPLY4kFJlo8UiliIpUTY,370
+mongoforge/managers/create.py,sha256=R6mMF4ZIRzR31AH-vG7zrAfTHJkZga2rBX0raEisEOE,794
+mongoforge/managers/delete.py,sha256=e1zQCbBdiwkPFMnE8nIkTj3dTezUTC4PzNusvqbFGy4,798
+mongoforge/managers/helpers.py,sha256=w590l0pwxlmk9tzFe34gF2jIhT9NjVie76LoJtGgCRU,476
+mongoforge/managers/read.py,sha256=1bqAalJBnT9KFrjQE_JOmPyuncW7vzzE4kvt6PLdMQA,2008
+mongoforge/managers/update.py,sha256=2xKpXOqRC9aZj_F3JEExaHT_0K6E09gdA0GnyX-wdQQ,1586
+mongoforge/utils/__init__.py,sha256=2zJezdz2lUsVW_6XlRD4pHwGHtSl910pzQ3SNENFSnI,123
+mongoforge/utils/collections.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mongoforge/utils/dates.py,sha256=Au689mG57fkOVpyrw9WnqsPYyiID2Pqaa8SXfov10FA,76
+mongoforge/utils/validation.py,sha256=xHTtaSCXfgccrQGjMUqbHvjsr1kP6ITdC0nSWKV6WpE,97
+mongoforge_odm-0.1.0.dist-info/METADATA,sha256=vo_mxVDEfUqmQtEIMlIjFfM33JpRKIerv2o0ZcUPBQg,7756
+mongoforge_odm-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+mongoforge_odm-0.1.0.dist-info/top_level.txt,sha256=n8InB-9S-tZoTZEPR7n0-BPP5hHGULkAP7Xfq-uV8jE,11
+mongoforge_odm-0.1.0.dist-info/RECORD,,

mongoforge_odm-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mongoforge_odm-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mongoforge