mongo-entity-orm 0.1.0__tar.gz → 0.1.1__tar.gz

mongo_entity_orm-0.1.1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.3
+Name: mongo-entity-orm
+Version: 0.1.1
+Summary: A MongoDB ORM for Python
+License: MIT
+Keywords: mongodb,orm,mongo,async
+Author: Juraj Bezdek
+Author-email: juraj.bezdek@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Dist: motor (>=3.7.1,<4.0.0)
+Requires-Dist: pymongo (>=4.13.2,<5.0.0)
+Project-URL: Documentation, https://github.com/ju-bezdek/mongo#readme
+Project-URL: Homepage, https://github.com/ju-bezdek/mongo-orm
+Project-URL: Repository, https://github.com/ju-bezdek/mongo
+Description-Content-Type: text/markdown
+
+# mongo-orm
+
+A MongoDB ORM for Python
+
+## Usage
+
+### Defining an Entity
+
+Use the `@entity` decorator to map a class to a MongoDB collection. Your class should inherit from `BaseEntity`.
+
+```python
+from mongo_orm import BaseEntity, entity
+
+@entity("users")
+class User(BaseEntity):
+    name: str
+    email: str
+    
+    # Define indexes
+    __indexes__ = [
+        {"keys": [("email", 1)], "unique": True},
+        {"keys": [("name", 1)]}
+    ]
+```
+
+### Index Management
+
+The ORM can automatically manage your MongoDB indexes based on the `__indexes__` attribute. This behavior is controlled by the `MONGODB_INDEX_AUTOAPPLY` environment variable.
+
+#### Configuration (`MONGODB_INDEX_AUTOAPPLY`)
+
+- `never` (default): No automatic index management.
+- `always`: Checks and applies indexes every time an entity class is initialized (on startup).
+- `auto-lock`: Checks and applies indexes once. After a successful check, it writes a hash of the index to `mongo-orm.lock`. Subsequent startups will skip the check if the hash is present in the lock file.
+
+#### Manual Index Application
+
+You can also trigger index application manually for all registered entities:
+
+```python
+from mongo_orm.utils import apply_all_indexes
+
+# Apply indexes using the current environment configuration
+apply_all_indexes()
+
+# Or force a specific mode
+apply_all_indexes(mode="always")
+```
+
+## Development
+
+```bash
+# Install dependencies
+poetry install
+
+# Run tests
+poetry run pytest
+
+# Format code
+poetry run black .
+poetry run isort .
+
+# Type checking
+poetry run mypy src/
+```
+
+## License
+
+MIT

mongo_entity_orm-0.1.1/README.md

@@ -0,0 +1,69 @@
+# mongo-orm
+
+A MongoDB ORM for Python
+
+## Usage
+
+### Defining an Entity
+
+Use the `@entity` decorator to map a class to a MongoDB collection. Your class should inherit from `BaseEntity`.
+
+```python
+from mongo_orm import BaseEntity, entity
+
+@entity("users")
+class User(BaseEntity):
+    name: str
+    email: str
+    
+    # Define indexes
+    __indexes__ = [
+        {"keys": [("email", 1)], "unique": True},
+        {"keys": [("name", 1)]}
+    ]
+```
+
+### Index Management
+
+The ORM can automatically manage your MongoDB indexes based on the `__indexes__` attribute. This behavior is controlled by the `MONGODB_INDEX_AUTOAPPLY` environment variable.
+
+#### Configuration (`MONGODB_INDEX_AUTOAPPLY`)
+
+- `never` (default): No automatic index management.
+- `always`: Checks and applies indexes every time an entity class is initialized (on startup).
+- `auto-lock`: Checks and applies indexes once. After a successful check, it writes a hash of the index to `mongo-orm.lock`. Subsequent startups will skip the check if the hash is present in the lock file.
+
+#### Manual Index Application
+
+You can also trigger index application manually for all registered entities:
+
+```python
+from mongo_orm.utils import apply_all_indexes
+
+# Apply indexes using the current environment configuration
+apply_all_indexes()
+
+# Or force a specific mode
+apply_all_indexes(mode="always")
+```
+
+## Development
+
+```bash
+# Install dependencies
+poetry install
+
+# Run tests
+poetry run pytest
+
+# Format code
+poetry run black .
+poetry run isort .
+
+# Type checking
+poetry run mypy src/
+```
+
+## License
+
+MIT

{mongo_entity_orm-0.1.0 → mongo_entity_orm-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "mongo-entity-orm"
-version = "0.1.0"
+version = "0.1.1"
 description = "A MongoDB ORM for Python"
 readme = "README.md"
 authors = ["Juraj Bezdek <juraj.bezdek@gmail.com>"]

{mongo_entity_orm-0.1.0 → mongo_entity_orm-0.1.1}/src/mongo_orm/core.py

@@ -6,15 +6,20 @@ import logging
 from collections import deque
 import os
 from typing import (
+    Any,
     AsyncIterator,
     Awaitable,
     Callable,
+    Dict,
     Generator,
     Iterable,
     List,
+    Optional,
+    Tuple,
     Type,
     TypeVar,
     TypedDict,
+    Union,
 )
 from uuid import NAMESPACE_URL, uuid4, uuid5
 from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorCollection
@@ -34,6 +39,10 @@ class Config:
     def MONGO_DATABASE_NAME():
         return os.environ.get("MONGO_DATABASE_NAME", None)
 
+    @staticmethod
+    def MONGODB_INDEX_AUTOAPPLY():
+        return os.environ.get("MONGODB_INDEX_AUTOAPPLY", "never")
+
 
 def encode_tenant_id(tenant_id, id):
     return str(uuid5(NAMESPACE_URL, f"{id}/{tenant_id}"))
@@ -45,6 +54,7 @@ class SaveResult(TypedDict):
 
 
 class Repository:
+    all_entities: List[Type["BaseEntity"]] = []
 
     def __init__(self, mongo_db: MongoDatabase = None) -> None:
         if mongo_db:
@@ -68,6 +78,33 @@ REPOSITORY = Repository()
 
 
 T = TypeVar("T", bound="BaseEntity")
+Keys = Union[
+    str,
+    List[Union[str, Tuple[str, int]]],
+    Dict[str, int],
+]
+
+
+class IndexSpec(TypedDict, total=False):
+    """
+    Typed dict describing a MongoDB index.
+
+    Examples:
+      {"keys": "email", "unique": True}
+      {"keys": [("tenant_id", 1), ("created_at", -1)], "name": "tenant_created_idx"}
+      {"keys": {"email": 1}, "unique": True}
+    """
+
+    keys: Keys
+    # Optional index options
+    unique: bool
+    sparse: bool
+    background: bool
+    name: str
+    expireAfterSeconds: int
+    expire_after_seconds: int  # alias
+    partialFilterExpression: Dict[str, Any]
+    weights: Dict[str, int]
 
 
 class BaseEntity(BaseModel):
@@ -81,6 +118,8 @@ class BaseEntity(BaseModel):
     _loaded_at: datetime.datetime | None = PrivateAttr(None)
     _tracked_fields_state: dict | None = PrivateAttr(None)
 
+    __indexes__: Optional[List[IndexSpec]] = None
+
     def __init__(self, **data) -> None:
         if not hasattr(self.__class__, "collection"):
             raise Exception(
@@ -557,6 +596,13 @@ def entity(
 
         cls.version_field = version_field
 
+        if cls not in REPOSITORY.all_entities:
+            REPOSITORY.all_entities.append(cls)
+
+        from .utils import apply_indexes
+
+        apply_indexes(cls)
+
         return cls
 
     return decorator

mongo_entity_orm-0.1.1/src/mongo_orm/utils.py

@@ -0,0 +1,137 @@
+import hashlib
+import logging
+import os
+from typing import TYPE_CHECKING, List, Literal, Type
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorCollection
+from pymongo.collection import Collection
+
+if TYPE_CHECKING:
+    from .core import BaseEntity, IndexSpec
+
+LOCK_FILE = "mongo-orm.lock"
+
+
+def _get_index_hash(collection_name: str, spec: "IndexSpec") -> str:
+    """Generate a stable hash for a collection + index specification."""
+    keys = spec.get("keys") or spec.get("key")
+    # Normalize keys to a stable tuple representation
+    if isinstance(keys, dict):
+        # Keep order as provided in dict
+        norm_keys = tuple((str(k), float(v)) for k, v in keys.items())
+    elif isinstance(keys, list):
+        norm_keys = tuple((str(k), float(v)) for k, v in keys)
+    else:
+        norm_keys = ((str(keys), 1.0),)
+
+    # Create a stable representation of the spec including important options
+    relevant_parts = {
+        "collection": collection_name,
+        "keys": norm_keys,
+        "unique": spec.get("unique", False),
+        "sparse": spec.get("sparse", False),
+        "partialFilterExpression": spec.get("partialFilterExpression"),
+        "expireAfterSeconds": spec.get("expireAfterSeconds")
+        or spec.get("expire_after_seconds"),
+    }
+    # Sort top-level keys of relevant_parts to ensure stable string representation
+    spec_str = str(sorted(relevant_parts.items(), key=lambda x: x[0]))
+    return hashlib.sha256(spec_str.encode()).hexdigest()
+
+
+def index_exists(collection: Collection, spec: "IndexSpec") -> bool:
+    """Return True if an equivalent index already exists in `collection` (sync)."""
+
+    # Normalize target keys to a list of tuples
+    keys = spec.get("keys") or spec.get("key")
+    if isinstance(keys, dict):
+        target_key = list(keys.items())
+    elif isinstance(keys, list):
+        target_key = keys
+    else:
+        target_key = [(keys, 1)]
+
+    # Normalize values to floats for comparison
+    target_key = [(str(k), float(v)) for k, v in target_key]
+
+    existing_indexes = collection.index_information()
+
+    for name, info in existing_indexes.items():
+        # info['key'] can be a list of tuples or a SON/dict object
+        raw_existing_key = info["key"]
+        if hasattr(raw_existing_key, "items"):
+            existing_key = [(str(k), float(v)) for k, v in raw_existing_key.items()]
+        else:
+            existing_key = [(str(k), float(v)) for k, v in raw_existing_key]
+
+        if existing_key == target_key:
+            return True
+    return False
+
+
+def apply_indexes(cls: Type["BaseEntity"], mode: Literal["auto-lock", "always"] = None):
+    """Check and apply indexes for a specific entity class."""
+    from .core import Config
+
+    mode = mode or Config.MONGODB_INDEX_AUTOAPPLY()
+    if not mode or mode == "never":
+        return
+
+    indexes = getattr(cls, "__indexes__", None)
+    if not indexes:
+        return
+
+    collection = cls.get_collection()
+    collection_name = cls.__collection_name__
+
+    applied_hashes = set()
+    if mode == "auto-lock" and os.path.exists(LOCK_FILE):
+        with open(LOCK_FILE, "r") as f:
+            applied_hashes = {line.strip() for line in f if line.strip()}
+
+    new_hashes = []
+
+    for spec in indexes:
+        idx_hash = _get_index_hash(collection_name, spec)
+
+        if mode == "auto-lock" and idx_hash in applied_hashes:
+            continue
+
+        if not index_exists(collection, spec):
+            # Create index
+            keys = spec.get("keys") or spec.get("key")
+            options = {
+                k: v
+                for k, v in spec.items()
+                if k not in ("keys", "key", "expire_after_seconds")
+            }
+            if "expire_after_seconds" in spec:
+                options["expireAfterSeconds"] = spec["expire_after_seconds"]
+
+            try:
+                collection.create_index(keys, **options)
+            except Exception as e:
+                logging.error(
+                    f"Failed to create index {keys} on {collection_name}: {e}"
+                )
+
+        if mode == "auto-lock":
+            new_hashes.append(idx_hash)
+
+    if new_hashes:
+        with open(LOCK_FILE, "a") as f:
+            for h in new_hashes:
+                f.write(f"{h}\n")
+
+
+def apply_all_indexes(mode: str = None):
+    """Apply indexes for all registered entity classes."""
+    from .core import Config, Repository
+
+    if mode is None:
+        mode = Config.MONGODB_INDEX_AUTOAPPLY()
+
+    if not mode or mode == "never":
+        return
+
+    for cls in Repository.all_entities:
+        apply_indexes(cls, mode)

mongo_entity_orm-0.1.0/PKG-INFO

@@ -1,55 +0,0 @@
-Metadata-Version: 2.3
-Name: mongo-entity-orm
-Version: 0.1.0
-Summary: A MongoDB ORM for Python
-License: MIT
-Keywords: mongodb,orm,mongo,async
-Author: Juraj Bezdek
-Author-email: juraj.bezdek@gmail.com
-Requires-Python: >=3.9,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-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
-Classifier: Programming Language :: Python :: 3 :: Only
-Requires-Dist: motor (>=3.7.1,<4.0.0)
-Requires-Dist: pymongo (>=4.13.2,<5.0.0)
-Project-URL: Documentation, https://github.com/ju-bezdek/mongo#readme
-Project-URL: Homepage, https://github.com/ju-bezdek/mongo-orm
-Project-URL: Repository, https://github.com/ju-bezdek/mongo
-Description-Content-Type: text/markdown
-
-# mongo-orm
-
-A MongoDB ORM for Python
-
-## Installation
-
-```bash
-pip install mongo-orm
-```
-
-## Development
-
-```bash
-# Install dependencies
-poetry install
-
-# Run tests
-poetry run pytest
-
-# Format code
-poetry run black .
-poetry run isort .
-
-# Type checking
-poetry run mypy src/
-```
-
-## License
-
-MIT

mongo_entity_orm-0.1.0/README.md

@@ -1,30 +0,0 @@
-# mongo-orm
-
-A MongoDB ORM for Python
-
-## Installation
-
-```bash
-pip install mongo-orm
-```
-
-## Development
-
-```bash
-# Install dependencies
-poetry install
-
-# Run tests
-poetry run pytest
-
-# Format code
-poetry run black .
-poetry run isort .
-
-# Type checking
-poetry run mypy src/
-```
-
-## License
-
-MIT