mongospec 0.0.1__tar.gz

mongospec-0.0.1/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Dmitry Belozerov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

mongospec-0.0.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: mongospec
+Version: 0.0.1
+Summary: Async MongoDB ODM with msgspec integration and automatic collection binding
+Author: Diprog
+License: MIT
+Project-URL: repository, https://github.com/diprog/mongospec
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mongojet~=0.3.1
+Requires-Dist: msgspec~=0.19.0
+Dynamic: license-file
+
+# mongospec
+
+Minimal async MongoDB ODM built for **speed** and **simplicity**, featuring automatic collection binding and msgspec
+integration.
+
+## Why mongospec?
+
+- ⚡ **Blazing fast** - Uses [msgspec](https://github.com/jcrist/msgspec) (fastest Python serialization)
+  and [mongojet](https://github.com/romis2012/mongojet) (fastest async MongoDB wrapper)
+- 🧩 **Dead simple** - No complex abstractions, just clean document handling
+- 🏎️ **Zero overhead** - Optimized for performance-critical applications
+
+## Installation
+
+```bash
+pip install mongospec
+```
+
+## Quick Start
+
+```python
+import asyncio
+from datetime import datetime
+
+import mongojet
+import msgspec
+
+import mongospec
+from mongospec import MongoDocument
+
+
+class User(MongoDocument):
+    __collection_name__ = "users"
+    __indexes__ = [{"keys": [("email", 1)], "options": {"unique": True}}]
+
+    name: str
+    email: str
+    created_at: datetime = msgspec.field(default_factory=datetime.now)
+
+
+async def main():
+    mongo_client = await mongojet.create_client("mongodb://localhost:27017")
+    try:
+        await mongospec.init(mongo_client.get_database("db"), document_types=[User])
+
+        # Create and insert user
+        user = User(name="Alice", email="alice@example.com")
+        await user.insert()
+
+        # Find document
+        found = await User.find_one({"email": "alice@example.com"})
+        print(found.dump())
+    finally:
+        await mongospec.close()
+
+
+asyncio.run(main())
+```
+
+## Performance Features
+
+- 🚀 **msgspec-powered** serialization (2-10x faster than alternatives)
+- ⚡ **mongojet backend** (faster than Motor with identical API)
+- 🧬 **Compiled structs** for document models
+- 📉 **Minimal abstraction** overhead
+
+⚠️ **Early Alpha Notice**  
+Basic CRUD operations supported. Designed for rapid prototyping. Not production-ready. API will evolve.

mongospec-0.0.1/README.md

@@ -0,0 +1,68 @@
+# mongospec
+
+Minimal async MongoDB ODM built for **speed** and **simplicity**, featuring automatic collection binding and msgspec
+integration.
+
+## Why mongospec?
+
+- ⚡ **Blazing fast** - Uses [msgspec](https://github.com/jcrist/msgspec) (fastest Python serialization)
+  and [mongojet](https://github.com/romis2012/mongojet) (fastest async MongoDB wrapper)
+- 🧩 **Dead simple** - No complex abstractions, just clean document handling
+- 🏎️ **Zero overhead** - Optimized for performance-critical applications
+
+## Installation
+
+```bash
+pip install mongospec
+```
+
+## Quick Start
+
+```python
+import asyncio
+from datetime import datetime
+
+import mongojet
+import msgspec
+
+import mongospec
+from mongospec import MongoDocument
+
+
+class User(MongoDocument):
+    __collection_name__ = "users"
+    __indexes__ = [{"keys": [("email", 1)], "options": {"unique": True}}]
+
+    name: str
+    email: str
+    created_at: datetime = msgspec.field(default_factory=datetime.now)
+
+
+async def main():
+    mongo_client = await mongojet.create_client("mongodb://localhost:27017")
+    try:
+        await mongospec.init(mongo_client.get_database("db"), document_types=[User])
+
+        # Create and insert user
+        user = User(name="Alice", email="alice@example.com")
+        await user.insert()
+
+        # Find document
+        found = await User.find_one({"email": "alice@example.com"})
+        print(found.dump())
+    finally:
+        await mongospec.close()
+
+
+asyncio.run(main())
+```
+
+## Performance Features
+
+- 🚀 **msgspec-powered** serialization (2-10x faster than alternatives)
+- ⚡ **mongojet backend** (faster than Motor with identical API)
+- 🧬 **Compiled structs** for document models
+- 📉 **Minimal abstraction** overhead
+
+⚠️ **Early Alpha Notice**  
+Basic CRUD operations supported. Designed for rapid prototyping. Not production-ready. API will evolve.

mongospec-0.0.1/mongospec/document/__init__.py

@@ -0,0 +1 @@
+from .document import MongoDocument

mongospec-0.0.1/mongospec/document/document.py

@@ -0,0 +1,112 @@
+"""
+Base MongoDB document model with automatic collection binding.
+
+Provides collection name resolution and runtime collection access.
+Uses class name as fallback when __collection_name__ is not specified.
+"""
+from datetime import datetime
+from typing import Any, ClassVar, Self
+
+import mongojet
+import msgspec
+from bson import ObjectId
+from mongojet import IndexModel
+
+from .operations.find import FindOperationsMixin
+from .operations.insert import InsertOperationsMixin
+
+
+class MongoDocument(
+    msgspec.Struct,
+    InsertOperationsMixin,
+    FindOperationsMixin,
+    kw_only=True
+):
+    """
+    Abstract base document for MongoDB collections with automatic binding.
+
+    .. rubric:: Class Organization
+
+    Settings:
+        __collection_name__: ClassVar[Optional[str]] = None
+            Explicit collection name (optional).
+        __preserve_types__: ClassVar[Tuple[Type[Any], ...]] = (ObjectId, datetime)
+            Types to preserve in their original form during encoding.
+        __indexes__: ClassVar[List[Dict]] = []
+            List of MongoDB indexes to ensure on initialization.
+
+    Runtime:
+        __collection__: ClassVar[Optional[mongojet.Collection]] = None
+            Set during mongospec.init().
+
+    Document:
+        _id: Optional[ObjectId] = None
+            MongoDB document ID field.
+    """
+
+    # Configuration settings
+    __collection_name__: ClassVar[str | None] = None
+    __preserve_types__: ClassVar[tuple[type[Any], ...]] = (ObjectId, datetime)
+    __indexes__: ClassVar[list[IndexModel]] = []
+
+    # Collection initialized externally
+    __collection__: ClassVar[mongojet.Collection | None] = None
+
+    # Primary key field
+    _id: ObjectId | None = None
+
+    @staticmethod
+    def _dec_hook(type_: type[Any], obj: Any) -> Any:
+        """Decode custom types like ObjectId and datetime during conversion."""
+        if type_ is ObjectId:
+            if isinstance(obj, ObjectId):
+                return obj
+            try:
+                return ObjectId(obj)
+            except Exception as e:
+                raise ValueError(f"Invalid ObjectId: {obj}") from e
+        raise NotImplementedError(f"Unsupported type: {type_}")
+
+    @staticmethod
+    def _enc_hook(obj: Any) -> Any:
+        """Encode custom types during serialization. Override in subclasses."""
+        raise NotImplementedError(f"Type {type(obj)} not supported")
+
+    @classmethod
+    def get_collection(cls) -> mongojet.Collection:
+        """Retrieve the bound MongoDB collection."""
+        if cls.__collection__ is None:
+            raise RuntimeError(
+                f"Collection for {cls.__name__} not initialized. "
+                "Call mongospec.init() first."
+            )
+        return cls.__collection__
+
+    @classmethod
+    def get_collection_name(cls) -> str:
+        """Determine the collection name from class settings."""
+        return cls.__collection_name__ or cls.__name__
+
+    @classmethod
+    def load(cls, data: dict[str, Any]) -> Self:
+        """Deserialize a dictionary into a document instance."""
+        return msgspec.convert(
+            data,
+            cls,
+            dec_hook=cls._dec_hook,
+            from_attributes=True,
+            strict=False
+        )
+
+    def dump(self, **kwargs: Any) -> dict[str, Any]:
+        """Serialize the document into a MongoDB-compatible dictionary."""
+        data = msgspec.to_builtins(
+            self,
+            enc_hook=self._enc_hook,
+            builtin_types=self.__preserve_types__,
+            **kwargs
+        )
+        # Strip None _id to allow MongoDB to generate it
+        if data.get("_id") is None:
+            del data["_id"]
+        return data

mongospec-0.0.1/mongospec/document/operations/base.py

@@ -0,0 +1,24 @@
+"""
+Base class for MongoDB document operations.
+Handles collection validation and provides utility methods.
+"""
+from typing import Any, TypeVar
+
+TDocument = TypeVar("TDocument", bound="MongoDocument")
+
+
+class BaseOperations:
+    """Base class for MongoDB operations mixins"""
+
+    @classmethod
+    def _get_collection(cls: type[TDocument]) -> Any:
+        """Get collection with type checking"""
+        if not hasattr(cls, "get_collection"):
+            raise AttributeError("Document model must implement get_collection()")
+        return cls.get_collection()
+
+    @classmethod
+    def _validate_document_type(cls: type[TDocument], document: Any) -> None:
+        """Ensure document matches collection type"""
+        if not isinstance(document, cls):
+            raise TypeError(f"Document must be of type {cls.__name__}")

mongospec-0.0.1/mongospec/document/operations/find.py

@@ -0,0 +1,20 @@
+"""
+CRUD operations mixin for MongoDocument.
+"""
+
+from .base import BaseOperations, TDocument
+
+
+class FindOperationsMixin(BaseOperations):
+    """Mixin class for query operations"""
+
+    @classmethod
+    async def find_one(cls: type[TDocument], filter: dict | None = None) -> TDocument | None:
+        """
+        Find single document by query filter
+
+        :param filter: MongoDB query filter
+        :return: Document instance or None
+        """
+        doc = await cls._get_collection().find_one(filter or {})
+        return cls.load(doc) if doc else None

mongospec-0.0.1/mongospec/document/operations/insert.py

@@ -0,0 +1,46 @@
+from .base import BaseOperations, TDocument
+
+
+class InsertOperationsMixin(BaseOperations):
+    """Mixin class for insert operations"""
+
+    @classmethod
+    async def insert_one(cls: type[TDocument], document: TDocument) -> TDocument:
+        """
+        Insert single document into collection
+
+        :param document: Document instance to insert
+        :return: Inserted document with _id
+        """
+        cls._validate_document_type(document)
+        result = await cls._get_collection().insert_one(document.dump())
+        document._id = result["inserted_id"]
+        return document
+
+    async def insert(self: TDocument) -> TDocument:
+        """
+        Insert the document instance into collection including existing _id
+
+        :return: Inserted document with _id (newly generated or existing)
+        """
+        self._validate_document_type(self)
+        result = await self._get_collection().insert_one(self.dump())
+        self._id = result["inserted_id"]
+        return self
+
+    @classmethod
+    async def insert_many(cls: type[TDocument], documents: list[TDocument]) -> list[TDocument]:
+        """
+        Batch insert documents
+
+        :param documents: List of document instances
+        :return: List of inserted documents with _ids
+        """
+        if not all(isinstance(d, cls) for d in documents):
+            raise TypeError("All documents must match collection type")
+
+        result = await cls._get_collection().insert_many([d.dump() for d in documents])
+
+        for doc, doc_id in zip(documents, result["inserted_ids"]):
+            doc._id = doc_id
+        return documents

mongospec-0.0.1/mongospec/mongospec.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: mongospec
+Version: 0.0.1
+Summary: Async MongoDB ODM with msgspec integration and automatic collection binding
+Author: Diprog
+License: MIT
+Project-URL: repository, https://github.com/diprog/mongospec
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mongojet~=0.3.1
+Requires-Dist: msgspec~=0.19.0
+Dynamic: license-file
+
+# mongospec
+
+Minimal async MongoDB ODM built for **speed** and **simplicity**, featuring automatic collection binding and msgspec
+integration.
+
+## Why mongospec?
+
+- ⚡ **Blazing fast** - Uses [msgspec](https://github.com/jcrist/msgspec) (fastest Python serialization)
+  and [mongojet](https://github.com/romis2012/mongojet) (fastest async MongoDB wrapper)
+- 🧩 **Dead simple** - No complex abstractions, just clean document handling
+- 🏎️ **Zero overhead** - Optimized for performance-critical applications
+
+## Installation
+
+```bash
+pip install mongospec
+```
+
+## Quick Start
+
+```python
+import asyncio
+from datetime import datetime
+
+import mongojet
+import msgspec
+
+import mongospec
+from mongospec import MongoDocument
+
+
+class User(MongoDocument):
+    __collection_name__ = "users"
+    __indexes__ = [{"keys": [("email", 1)], "options": {"unique": True}}]
+
+    name: str
+    email: str
+    created_at: datetime = msgspec.field(default_factory=datetime.now)
+
+
+async def main():
+    mongo_client = await mongojet.create_client("mongodb://localhost:27017")
+    try:
+        await mongospec.init(mongo_client.get_database("db"), document_types=[User])
+
+        # Create and insert user
+        user = User(name="Alice", email="alice@example.com")
+        await user.insert()
+
+        # Find document
+        found = await User.find_one({"email": "alice@example.com"})
+        print(found.dump())
+    finally:
+        await mongospec.close()
+
+
+asyncio.run(main())
+```
+
+## Performance Features
+
+- 🚀 **msgspec-powered** serialization (2-10x faster than alternatives)
+- ⚡ **mongojet backend** (faster than Motor with identical API)
+- 🧬 **Compiled structs** for document models
+- 📉 **Minimal abstraction** overhead
+
+⚠️ **Early Alpha Notice**  
+Basic CRUD operations supported. Designed for rapid prototyping. Not production-ready. API will evolve.

mongospec-0.0.1/mongospec/mongospec.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+mongospec/document/__init__.py
+mongospec/document/document.py
+mongospec/document/operations/__init__.py
+mongospec/document/operations/base.py
+mongospec/document/operations/find.py
+mongospec/document/operations/insert.py
+mongospec/mongospec.egg-info/PKG-INFO
+mongospec/mongospec.egg-info/SOURCES.txt
+mongospec/mongospec.egg-info/dependency_links.txt
+mongospec/mongospec.egg-info/requires.txt
+mongospec/mongospec.egg-info/top_level.txt

mongospec-0.0.1/mongospec/mongospec.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mongospec-0.0.1/mongospec/mongospec.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mongojet~=0.3.1
+msgspec~=0.19.0

mongospec-0.0.1/mongospec/mongospec.egg-info/top_level.txt

@@ -0,0 +1 @@
+document

mongospec-0.0.1/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "mongospec"
+version = "0.0.1"
+authors = [{name = "Diprog"}]
+description = "Async MongoDB ODM with msgspec integration and automatic collection binding"
+readme = "README.md"
+requires-python = ">=3.13"
+license = {text = "MIT"}
+dependencies = [
+    "mongojet~=0.3.1",
+    "msgspec~=0.19.0",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Typing :: Typed"
+]
+
+[project.urls]
+repository = "https://github.com/diprog/mongospec"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["mongospec"]

mongospec-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+