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

mongo_entity_orm-0.1.2/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.3
+Name: mongo-entity-orm
+Version: 0.1.2
+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-orm#readme
+Project-URL: Homepage, https://github.com/ju-bezdek/mongo-orm
+Project-URL: Repository, https://github.com/ju-bezdek/mongo-orm
+Description-Content-Type: text/markdown
+
+# mongo-orm
+
+A MongoDB ORM for Python
+
+## Installation
+
+```
+pip install mongo-entity-orm
+```
+
+or
+
+```
+uv add mongo-entity-orm
+```
+
+## Configuration
+
+Set the following environment variables before using the ORM:
+
+| Variable | Description |
+|---|---|
+| `MONGODB_URI` | MongoDB connection string |
+| `MONGO_DATABASE_NAME` | Name of the database |
+
+## 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(collection_name="users")
+class User(BaseEntity):
+    name: str
+    email: str
+```
+
+Every entity automatically has an `id` field (UUID string) and a `tenant_id` field (defaults to `"-"`).
+
+### CRUD Operations
+
+All operations are available in both async (`a`-prefixed) and sync variants.
+
+#### Get by ID
+
+```python
+# async
+user = await User.aget(id=user_id, tenant_id=tenant_id)
+
+# sync
+user = User.get(id=user_id, tenant_id=tenant_id)
+```
+
+Pass `raise_not_found=True` to raise an exception instead of returning `None` when the entity is not found.
+
+#### Save
+
+```python
+user = User(name="Alice", email="alice@example.com", tenant_id="acme")
+
+# async
+await user.asave()
+
+# sync
+user.save()
+```
+
+`save()` / `asave()` performs an upsert based on `id`, so it works for both creating and updating.
+
+#### Update fields
+
+```python
+# Update in-memory only
+user.update(name="Bob")
+
+# Update and immediately save (async)
+await user.aupdate(name="Bob", auto_save=True)
+
+# Update and immediately save (sync)
+user.update(name="Bob", auto_save=True)
+```
+
+#### Delete
+
+```python
+# Delete an entity instance
+user.delete()
+
+# Delete by ID
+User.delete_by_id(id=user_id, tenant_id=tenant_id)
+```
+
+Pass `ignore_not_found=True` to suppress an exception when the entity does not exist.
+
+### Querying
+
+#### Find (filter)
+
+`filter` accepts a standard MongoDB query dict.
+
+```python
+# async
+users = await User.afind(tenant_id=tenant_id, filter={"name": "Alice"})
+
+# sync
+users = User.find(tenant_id=tenant_id, filter={"name": "Alice"})
+```
+
+MongoDB operators work as expected:
+
+```python
+users = await User.afind(
+    tenant_id=tenant_id,
+    filter={"name": {"$in": ["Alice", "Bob"]}, "email": {"$regex": "@example.com$"}},
+)
+```
+
+Use `tenant_id="*"` to query across all tenants.
+
+#### Pagination
+
+```python
+users = await User.afind(tenant_id=tenant_id, filter={}, skip=0, limit=20)
+```
+
+#### Sorting
+
+```python
+# Ascending
+users = await User.afind(tenant_id=tenant_id, order_by="name")
+
+# Descending (prefix with "-")
+users = await User.afind(tenant_id=tenant_id, order_by="-name")
+
+# Multiple sort fields
+users = await User.afind(tenant_id=tenant_id, order_by=["-created_at", "name"])
+```
+
+#### Find first
+
+```python
+user = await User.afind_first(tenant_id=tenant_id, filter={"email": "alice@example.com"})
+```
+
+Returns `None` if no match is found.
+
+#### Count
+
+```python
+# async
+total = await User.acount(tenant_id=tenant_id, filter={"name": "Alice"})
+
+# sync
+total = User.count(tenant_id=tenant_id, filter={"name": "Alice"})
+```
+
+#### Scroll pages (batch iteration)
+
+```python
+# async
+async for page in User.ascroll_pages(tenant_id=tenant_id, page_size=50):
+    for user in page:
+        ...
+
+# sync
+for page in User.scroll_pages(tenant_id=tenant_id, page_size=50):
+    for user in page:
+        ...
+```
+
+#### Bulk save
+
+```python
+await User.bulk_save([user1, user2, user3])
+```
+
+### Index Management
+
+Define indexes on the entity class using `__indexes__`:
+
+```python
+@entity(collection_name="users")
+class User(BaseEntity):
+    name: str
+    email: str
+
+    __indexes__ = [
+        {"keys": [("email", 1)], "unique": True},
+        {"keys": [("name", 1)]},
+        {"keys": [("tenant_id", 1), ("name", 1)]},
+    ]
+```
+
+Index management is controlled by the `MONGODB_INDEX_AUTOAPPLY` environment variable:
+
+| Value | Behaviour |
+|---|---|
+| `never` (default) | No automatic index management |
+| `always` | Checks and applies indexes on every startup |
+| `auto-lock` | Applies indexes once; writes a hash to `mongo-orm.lock` and skips on subsequent startups |
+
+#### Manual application
+
+```python
+from mongo_orm.utils import apply_all_indexes
+
+# Respects MONGODB_INDEX_AUTOAPPLY
+apply_all_indexes()
+
+# 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.2/README.md

@@ -0,0 +1,236 @@
+# mongo-orm
+
+A MongoDB ORM for Python
+
+## Installation
+
+```
+pip install mongo-entity-orm
+```
+
+or
+
+```
+uv add mongo-entity-orm
+```
+
+## Configuration
+
+Set the following environment variables before using the ORM:
+
+| Variable | Description |
+|---|---|
+| `MONGODB_URI` | MongoDB connection string |
+| `MONGO_DATABASE_NAME` | Name of the database |
+
+## 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(collection_name="users")
+class User(BaseEntity):
+    name: str
+    email: str
+```
+
+Every entity automatically has an `id` field (UUID string) and a `tenant_id` field (defaults to `"-"`).
+
+### CRUD Operations
+
+All operations are available in both async (`a`-prefixed) and sync variants.
+
+#### Get by ID
+
+```python
+# async
+user = await User.aget(id=user_id, tenant_id=tenant_id)
+
+# sync
+user = User.get(id=user_id, tenant_id=tenant_id)
+```
+
+Pass `raise_not_found=True` to raise an exception instead of returning `None` when the entity is not found.
+
+#### Save
+
+```python
+user = User(name="Alice", email="alice@example.com", tenant_id="acme")
+
+# async
+await user.asave()
+
+# sync
+user.save()
+```
+
+`save()` / `asave()` performs an upsert based on `id`, so it works for both creating and updating.
+
+#### Update fields
+
+```python
+# Update in-memory only
+user.update(name="Bob")
+
+# Update and immediately save (async)
+await user.aupdate(name="Bob", auto_save=True)
+
+# Update and immediately save (sync)
+user.update(name="Bob", auto_save=True)
+```
+
+#### Delete
+
+```python
+# Delete an entity instance
+user.delete()
+
+# Delete by ID
+User.delete_by_id(id=user_id, tenant_id=tenant_id)
+```
+
+Pass `ignore_not_found=True` to suppress an exception when the entity does not exist.
+
+### Querying
+
+#### Find (filter)
+
+`filter` accepts a standard MongoDB query dict.
+
+```python
+# async
+users = await User.afind(tenant_id=tenant_id, filter={"name": "Alice"})
+
+# sync
+users = User.find(tenant_id=tenant_id, filter={"name": "Alice"})
+```
+
+MongoDB operators work as expected:
+
+```python
+users = await User.afind(
+    tenant_id=tenant_id,
+    filter={"name": {"$in": ["Alice", "Bob"]}, "email": {"$regex": "@example.com$"}},
+)
+```
+
+Use `tenant_id="*"` to query across all tenants.
+
+#### Pagination
+
+```python
+users = await User.afind(tenant_id=tenant_id, filter={}, skip=0, limit=20)
+```
+
+#### Sorting
+
+```python
+# Ascending
+users = await User.afind(tenant_id=tenant_id, order_by="name")
+
+# Descending (prefix with "-")
+users = await User.afind(tenant_id=tenant_id, order_by="-name")
+
+# Multiple sort fields
+users = await User.afind(tenant_id=tenant_id, order_by=["-created_at", "name"])
+```
+
+#### Find first
+
+```python
+user = await User.afind_first(tenant_id=tenant_id, filter={"email": "alice@example.com"})
+```
+
+Returns `None` if no match is found.
+
+#### Count
+
+```python
+# async
+total = await User.acount(tenant_id=tenant_id, filter={"name": "Alice"})
+
+# sync
+total = User.count(tenant_id=tenant_id, filter={"name": "Alice"})
+```
+
+#### Scroll pages (batch iteration)
+
+```python
+# async
+async for page in User.ascroll_pages(tenant_id=tenant_id, page_size=50):
+    for user in page:
+        ...
+
+# sync
+for page in User.scroll_pages(tenant_id=tenant_id, page_size=50):
+    for user in page:
+        ...
+```
+
+#### Bulk save
+
+```python
+await User.bulk_save([user1, user2, user3])
+```
+
+### Index Management
+
+Define indexes on the entity class using `__indexes__`:
+
+```python
+@entity(collection_name="users")
+class User(BaseEntity):
+    name: str
+    email: str
+
+    __indexes__ = [
+        {"keys": [("email", 1)], "unique": True},
+        {"keys": [("name", 1)]},
+        {"keys": [("tenant_id", 1), ("name", 1)]},
+    ]
+```
+
+Index management is controlled by the `MONGODB_INDEX_AUTOAPPLY` environment variable:
+
+| Value | Behaviour |
+|---|---|
+| `never` (default) | No automatic index management |
+| `always` | Checks and applies indexes on every startup |
+| `auto-lock` | Applies indexes once; writes a hash to `mongo-orm.lock` and skips on subsequent startups |
+
+#### Manual application
+
+```python
+from mongo_orm.utils import apply_all_indexes
+
+# Respects MONGODB_INDEX_AUTOAPPLY
+apply_all_indexes()
+
+# 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.2}/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.2"
 description = "A MongoDB ORM for Python"
 readme = "README.md"
 authors = ["Juraj Bezdek <juraj.bezdek@gmail.com>"]
@@ -12,7 +12,7 @@ license = "MIT"
 packages = [{include = "mongo_orm", from = "src"}]
 keywords = ["mongodb", "orm", "mongo", "async"]
 homepage = "https://github.com/ju-bezdek/mongo-orm"
-repository = "https://github.com/ju-bezdek/mongo"
+repository = "https://github.com/ju-bezdek/mongo-orm"
 
 classifiers = [
   "Programming Language :: Python :: 3",
@@ -25,8 +25,8 @@ classifiers = [
 ]
 
 [tool.poetry.urls]
-Repository = "https://github.com/ju-bezdek/mongo"
-Documentation = "https://github.com/ju-bezdek/mongo#readme"
+Repository = "https://github.com/ju-bezdek/mongo-orm"
+Documentation = "https://github.com/ju-bezdek/mongo-orm#readme"
 
 [tool.poetry.dependencies]
 python = ">=3.9,<4.0"

{mongo_entity_orm-0.1.0 → mongo_entity_orm-0.1.2}/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,29 +54,65 @@ class SaveResult(TypedDict):
 
 
 class Repository:
+    all_entities: List[Type["BaseEntity"]] = []
 
     def __init__(self, mongo_db: MongoDatabase = None) -> None:
         if mongo_db:
             self.mongo_db = mongo_db
         else:
+            mongodb_uri = Config.MONGODB_URI()
+            mongo_db_name = Config.MONGO_DATABASE_NAME()
+            if not mongodb_uri and not mongo_db_name:
+                raise ValueError(
+                    "MONGODB_URI and MONGO_DATABASE_NAME environment variables are not set"
+                )
+            if not mongodb_uri:
+                raise ValueError("MONGODB_URI environment variable is not set")
+            if not mongo_db_name:
+                raise ValueError("MONGO_DATABASE_NAME environment variable is not set")
 
             self.mongo_client = MongoClient(
-                Config.MONGODB_URI(), tlsAllowInvalidCertificates=True
+                mongodb_uri, tlsAllowInvalidCertificates=True
             )
             self.async_mongo_client = AsyncIOMotorClient(
-                Config.MONGODB_URI(), tls=True, tlsAllowInvalidCertificates=True
+                mongodb_uri, tls=True, tlsAllowInvalidCertificates=True
             )
             self.mongo_client.admin.command("ping")
-            self.mongo_db = self.mongo_client[str(Config.MONGO_DATABASE_NAME())]
-            self.async_mongo_db = self.async_mongo_client[
-                str(Config.MONGO_DATABASE_NAME())
-            ]
+            self.mongo_db = self.mongo_client[str(mongo_db_name)]
+            self.async_mongo_db = self.async_mongo_client[str(mongo_db_name)]
 
 
 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 +126,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 +604,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.2/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