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

mongo_entity_orm-0.1.3/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.3
+Name: mongo-entity-orm
+Version: 0.1.3
+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.3/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.1 → mongo_entity_orm-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "mongo-entity-orm"
-version = "0.1.1"
+version = "0.1.3"
 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.1 → mongo_entity_orm-0.1.3}/src/mongo_orm/core.py

@@ -60,18 +60,26 @@ class Repository:
         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()
@@ -301,7 +309,7 @@ class BaseEntity(BaseModel):
                 )
 
     @classmethod
-    def delete_by_id(cls, id, tenant_id: str):
+    def delete_by_id(cls, id, tenant_id: str = "*") -> bool:
 
         filter = {"_id": id}
         if tenant_id != "*":
@@ -313,7 +321,7 @@ class BaseEntity(BaseModel):
     def get(
         cls: Type[T],
         id: str,
-        tenant_id: str,
+        tenant_id: str = "*",
         namespace: str = None,
         raise_not_found: bool = False,
     ) -> T | None:
@@ -334,7 +342,7 @@ class BaseEntity(BaseModel):
     async def aget(
         cls: Type[T],
         id: str,
-        tenant_id: str,
+        tenant_id: str = "*",
         namespace: str = None,
         raise_not_found: bool = False,
     ) -> T | None:
@@ -370,7 +378,7 @@ class BaseEntity(BaseModel):
         return entity
 
     @classmethod
-    def count(cls, tenant_id: str, filter: dict = None, limit=None) -> int:
+    def count(cls, tenant_id: str = "*", filter: dict = None, limit=None) -> int:
 
         if not filter:
             _filter = {}
@@ -386,7 +394,7 @@ class BaseEntity(BaseModel):
         return cls.collection.count_documents(_filter, **extra)
 
     @classmethod
-    async def acount(cls, tenant_id: str, filter: dict = None, limit=None) -> int:
+    async def acount(cls, tenant_id: str = "*", filter: dict = None, limit=None) -> int:
 
         if not filter:
             _filter = {}
@@ -404,7 +412,7 @@ class BaseEntity(BaseModel):
     @classmethod
     async def afind(
         cls: Type[T],
-        tenant_id: str,
+        tenant_id: str = "*",
         namespace: str = None,
         skip: int = 0,
         limit: int = 100,
@@ -414,8 +422,10 @@ class BaseEntity(BaseModel):
     ) -> List[T]:
         if not filter:
             filter = {}
+        else:
+            filter = {**filter}
         if tenant_id != "*":
-            filter.update({"tenant_id": tenant_id, **additional_filters})
+            filter.update({"tenant_id": tenant_id})
 
         filter.update(additional_filters)
         if "id" in filter:
@@ -446,7 +456,7 @@ class BaseEntity(BaseModel):
     @classmethod
     def scroll_pages(
         cls: Type[T],
-        tenant_id: str,
+        tenant_id: str = "*",
         filter: dict = None,
         order_by: str = None,
         page_size: int = 100,
@@ -468,7 +478,7 @@ class BaseEntity(BaseModel):
     @classmethod
     async def ascroll_pages(
         cls: Type[T],
-        tenant_id: str,
+        tenant_id: str = "*",
         filter: dict = None,
         order_by: str = None,
         page_size: int = 100,
@@ -490,7 +500,7 @@ class BaseEntity(BaseModel):
     @classmethod
     def find(
         cls: Type[T],
-        tenant_id: str,
+        tenant_id: str = "*",
         namespace: str = None,
         skip: int = 0,
         limit: int | None = 100,
@@ -503,7 +513,7 @@ class BaseEntity(BaseModel):
         else:
             filter = {**filter}
         if tenant_id != "*":
-            filter.update({"tenant_id": tenant_id, **additional_filters})
+            filter.update({"tenant_id": tenant_id})
 
         filter.update(additional_filters)
         if "id" in filter:
@@ -536,13 +546,15 @@ class BaseEntity(BaseModel):
         return res
 
     @classmethod
-    def find_first(cls, tenant_id, filter=None, order_by=None, **kwargs):
+    def find_first(cls, tenant_id: str = "*", filter=None, order_by=None, **kwargs):
         kwargs.pop("limit", None)
         items = cls.find(tenant_id, filter=filter, order_by=order_by, limit=1, **kwargs)
         return items[0] if items else None
 
     @classmethod
-    async def afind_first(cls, tenant_id, filter=None, order_by=None, **kwargs):
+    async def afind_first(
+        cls, tenant_id: str = "*", filter=None, order_by=None, **kwargs
+    ):
         items = await cls.afind(
             tenant_id, filter=filter, order_by=order_by, limit=1, **kwargs
         )

mongo_entity_orm-0.1.1/PKG-INFO

@@ -1,94 +0,0 @@
-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

@@ -1,69 +0,0 @@
-# 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