lightodm 0.1.0__tar.gz → 0.2.0__tar.gz

{lightodm-0.1.0 → lightodm-0.2.0}/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-02-05
+
+### Added
+- **Composite key support** for deterministic ID generation
+  - New `composite_key` setting in `Settings` class
+  - IDs computed as MD5 hash of concatenated field values
+  - Enables multi-tenant applications with predictable document IDs
+  - New `generate_composite_id()` helper function exported from package
+- Comprehensive integration tests for composite key functionality
+- `CLAUDE.md` project guidance file for AI-assisted development
+- Additional edge case tests improving code coverage
+
+### Changed
+- Improved API documentation formatting and clarity
+- Updated test organization with clear unit/integration separation
+
+### Fixed
+- Pydantic v2.11+ deprecation warning for `model_fields` access on instances
+
 ## [0.1.0] - 2026-01-17
 
 ### Added

{lightodm-0.1.0 → lightodm-0.2.0}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: lightodm
-Version: 0.1.0
+Version: 0.2.0
 Summary: Lightweight MongoDB ODM - Simple async/sync Object-Document Mapper for MongoDB
 Project-URL: Homepage, https://github.com/Aprova-GmbH/lightodm
 Project-URL: Repository, https://github.com/Aprova-GmbH/lightodm
-Project-URL: Documentation, https://github.com/Aprova-GmbH/lightodm#readme
+Project-URL: Documentation, https://lightodm.readthedocs.io
 Project-URL: Issues, https://github.com/Aprova-GmbH/lightodm/issues
+Project-URL: Changelog, https://github.com/Aprova-GmbH/lightodm/blob/main/CHANGELOG.md
 Author-email: Andrey Vykhodtsev <vya@aprova.ch>
 License: Apache-2.0
 License-File: LICENSE
@@ -179,6 +180,37 @@ product = Product(name="Widget", sku="WDG-001")
 print(product.id)  # Generated ObjectId string
 ```
 
+### Composite Keys
+
+For multi-tenant applications or when you need deterministic IDs based on multiple fields, use composite keys:
+
+```python
+from lightodm import MongoBaseModel
+
+class TenantUser(MongoBaseModel):
+    class Settings:
+        name = "tenant_users"
+        composite_key = ["tenant_id", "user_id"]  # Order matters
+
+    tenant_id: str
+    user_id: str
+    data: str
+
+# ID is computed as MD5 hash of concatenated field values
+user = TenantUser(tenant_id="tenant1", user_id="user1", data="test")
+print(user.id)  # e.g., "a1b2c3..." - always the same for same tenant_id + user_id
+
+# Same values always produce the same ID (idempotent)
+user2 = TenantUser(tenant_id="tenant1", user_id="user1", data="different")
+assert user.id == user2.id  # True - composite key only uses specified fields
+```
+
+Composite key behavior:
+- Field order in `composite_key` list determines concatenation order
+- All composite key fields must have non-None values
+- Composite key takes precedence over explicitly provided IDs
+- Produces a 32-character hexadecimal MD5 hash
+
 ### Custom Connection
 
 Override `get_collection()` or `get_async_collection()` for custom connection logic:

{lightodm-0.1.0 → lightodm-0.2.0}/README.md

@@ -139,6 +139,37 @@ product = Product(name="Widget", sku="WDG-001")
 print(product.id)  # Generated ObjectId string
 ```
 
+### Composite Keys
+
+For multi-tenant applications or when you need deterministic IDs based on multiple fields, use composite keys:
+
+```python
+from lightodm import MongoBaseModel
+
+class TenantUser(MongoBaseModel):
+    class Settings:
+        name = "tenant_users"
+        composite_key = ["tenant_id", "user_id"]  # Order matters
+
+    tenant_id: str
+    user_id: str
+    data: str
+
+# ID is computed as MD5 hash of concatenated field values
+user = TenantUser(tenant_id="tenant1", user_id="user1", data="test")
+print(user.id)  # e.g., "a1b2c3..." - always the same for same tenant_id + user_id
+
+# Same values always produce the same ID (idempotent)
+user2 = TenantUser(tenant_id="tenant1", user_id="user1", data="different")
+assert user.id == user2.id  # True - composite key only uses specified fields
+```
+
+Composite key behavior:
+- Field order in `composite_key` list determines concatenation order
+- All composite key fields must have non-None values
+- Composite key takes precedence over explicitly provided IDs
+- Produces a 32-character hexadecimal MD5 hash
+
 ### Custom Connection
 
 Override `get_collection()` or `get_async_collection()` for custom connection logic:

{lightodm-0.1.0 → lightodm-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lightodm"
-version = "0.1.0"
+version = "0.2.0"
 description = "Lightweight MongoDB ODM - Simple async/sync Object-Document Mapper for MongoDB"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -58,8 +58,9 @@ dev = [
 [project.urls]
 Homepage = "https://github.com/Aprova-GmbH/lightodm"
 Repository = "https://github.com/Aprova-GmbH/lightodm"
-Documentation = "https://github.com/Aprova-GmbH/lightodm#readme"
+Documentation = "https://lightodm.readthedocs.io"
 Issues = "https://github.com/Aprova-GmbH/lightodm/issues"
+Changelog = "https://github.com/Aprova-GmbH/lightodm/blob/main/CHANGELOG.md"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/lightodm"]

{lightodm-0.1.0 → lightodm-0.2.0}/src/lightodm/__init__.py

@@ -23,7 +23,7 @@ Example:
     await user.asave()
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 from lightodm.connection import (
     MongoConnection,
@@ -35,12 +35,13 @@ from lightodm.connection import (
     get_database,
     get_mongo_connection,
 )
-from lightodm.model import MongoBaseModel, generate_id
+from lightodm.model import MongoBaseModel, generate_composite_id, generate_id
 
 __all__ = [
     # Model
     "MongoBaseModel",
     "generate_id",
+    "generate_composite_id",
     # Connection
     "MongoConnection",
     "connect",

{lightodm-0.1.0 → lightodm-0.2.0}/src/lightodm/connection.py

@@ -298,6 +298,7 @@ def connect(
     Initialize MongoDB connection with optional explicit parameters.
 
     If parameters are not provided, they will be read from environment variables:
+
     - MONGO_URL
     - MONGO_USER
     - MONGO_PASSWORD
@@ -312,7 +313,8 @@ def connect(
     Returns:
         PyMongo Database instance
 
-    Example:
+    Example::
+
         # Connect with explicit parameters
         db = connect(
             url="mongodb://localhost:27017",

{lightodm-0.1.0 → lightodm-0.2.0}/src/lightodm/model.py

@@ -4,11 +4,12 @@ MongoDB Base Model for Pydantic
 Provides ODM functionality for MongoDB with both sync and async support.
 """
 
+import hashlib
 from typing import AsyncIterator, Iterator, List, Optional, Type, TypeVar
 
 from bson import ObjectId
 from motor.motor_asyncio import AsyncIOMotorCollection
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 from pymongo.collection import Collection as PyMongoCollection
 
 from lightodm.connection import get_async_database, get_collection
@@ -27,6 +28,20 @@ def generate_id() -> str:
     return str(ObjectId())
 
 
+def generate_composite_id(values: list) -> str:
+    """
+    Generate MD5 hash from list of values for composite key.
+
+    Args:
+        values: List of values to concatenate and hash
+
+    Returns:
+        32-character hexadecimal MD5 hash string
+    """
+    concatenated = "".join(str(v) for v in values)
+    return hashlib.md5(concatenated.encode("utf-8")).hexdigest()
+
+
 class MongoBaseModel(BaseModel):
     """
     Base class for MongoDB document models with ODM functionality.
@@ -66,6 +81,7 @@ class MongoBaseModel(BaseModel):
     # Settings inner class - must be overridden in subclasses
     class Settings:
         name: Optional[str] = None  # MongoDB collection name
+        composite_key: Optional[List[str]] = None  # Fields for composite key ID
 
     @classmethod
     def _uses_mongo_id_alias(cls) -> bool:
@@ -77,6 +93,34 @@ class MongoBaseModel(BaseModel):
             alias = getattr(field, "validation_alias", None)
         return alias == "_id"
 
+    @model_validator(mode="after")
+    def _compute_composite_key(self):
+        """Compute composite key ID if defined in Settings."""
+        composite_key = getattr(self.Settings, "composite_key", None)
+
+        if composite_key is None:
+            return self
+
+        if not isinstance(composite_key, (list, tuple)) or len(composite_key) == 0:
+            raise ValueError("composite_key must be a non-empty list")
+
+        values = []
+        for field_name in composite_key:
+            # Access model_fields from the class, not the instance (Pydantic v2.11+)
+            if field_name not in self.__class__.model_fields and not hasattr(self, field_name):
+                raise ValueError(f"Composite key field '{field_name}' not found in model")
+
+            value = getattr(self, field_name, None)
+            if value is None:
+                raise ValueError(
+                    f"Composite key field '{field_name}' is None. All fields must have values."
+                )
+
+            values.append(value)
+
+        self.id = generate_composite_id(values)
+        return self
+
     def __init_subclass__(cls, **kwargs):
         """
         Validate Settings class is properly defined in subclass.

lightodm-0.2.0/tests/test_async.py

@@ -0,0 +1,311 @@
+"""Tests for async operations in lightodm."""
+
+import pytest
+
+from lightodm import MongoBaseModel
+
+
+class AsyncTestModel(MongoBaseModel):
+    """Test model for async operations."""
+
+    class Settings:
+        name = "async_test_collection"
+
+    name: str
+    value: int
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_save_and_get(cleanup_test_collections):
+    """Test async save and get operations with real MongoDB."""
+    # Create and save - uses real MongoDB via environment variables
+    model = AsyncTestModel(name="async_test", value=42)
+    doc_id = await model.asave()
+
+    assert doc_id == model.id
+
+    # Retrieve - uses real MongoDB
+    retrieved = await AsyncTestModel.aget(doc_id)
+    assert retrieved is not None
+    assert retrieved.name == "async_test"
+    assert retrieved.value == 42
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_find(cleanup_test_collections):
+    """Test async find operations with real MongoDB."""
+    # Create multiple documents
+    models = [AsyncTestModel(name=f"test_{i}", value=i) for i in range(5)]
+
+    for model in models:
+        await model.asave()
+
+    # Find all
+    results = await AsyncTestModel.afind({})
+    assert len(results) == 5
+
+    # Find with filter
+    results = await AsyncTestModel.afind({"value": {"$gte": 3}})
+    assert len(results) == 2
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_delete(cleanup_test_collections):
+    """Test async delete operation with real MongoDB."""
+    # Create and save
+    model = AsyncTestModel(name="to_delete", value=100)
+    await model.asave()
+
+    # Verify it exists
+    retrieved = await AsyncTestModel.aget(model.id)
+    assert retrieved is not None
+
+    # Delete
+    deleted = await model.adelete()
+    assert deleted is True
+
+    # Verify it's gone
+    retrieved = await AsyncTestModel.aget(model.id)
+    assert retrieved is None
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_update(cleanup_test_collections):
+    """Test async update operations with real MongoDB."""
+    # Create initial document
+    model = AsyncTestModel(name="original", value=10)
+    await model.asave()
+
+    # Update
+    success = await AsyncTestModel.aupdate_one({"_id": model.id}, {"$set": {"value": 20}})
+    assert success is True
+
+    # Verify update
+    retrieved = await AsyncTestModel.aget(model.id)
+    assert retrieved.value == 20
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_count(cleanup_test_collections):
+    """Test async count operation with real MongoDB."""
+    # Create documents
+    for i in range(3):
+        model = AsyncTestModel(name=f"count_test_{i}", value=i)
+        await model.asave()
+
+    # Count all
+    count = await AsyncTestModel.acount()
+    assert count == 3
+
+    # Count with filter
+    count = await AsyncTestModel.acount({"value": {"$gt": 0}})
+    assert count == 2
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_find_one(cleanup_test_collections):
+    """Test async find_one operation with real MongoDB."""
+    # Create documents
+    model1 = AsyncTestModel(name="first", value=1)
+    model2 = AsyncTestModel(name="second", value=2)
+    await model1.asave()
+    await model2.asave()
+
+    # Find one by filter
+    result = await AsyncTestModel.afind_one({"name": "second"})
+    assert result is not None
+    assert result.name == "second"
+    assert result.value == 2
+
+    # Find one non-existent
+    result = await AsyncTestModel.afind_one({"name": "nonexistent"})
+    assert result is None
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_find_iter(cleanup_test_collections):
+    """Test async find_iter operation with real MongoDB."""
+    # Create documents
+    models = [AsyncTestModel(name=f"iter_{i}", value=i) for i in range(3)]
+    for model in models:
+        await model.asave()
+
+    # Use async iterator
+    results = []
+    async for doc in AsyncTestModel.afind_iter({}):
+        results.append(doc)
+
+    assert len(results) == 3
+    assert all(isinstance(r, AsyncTestModel) for r in results)
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_update_many(cleanup_test_collections):
+    """Test async update_many operation with real MongoDB."""
+    # Create documents
+    for i in range(5):
+        model = AsyncTestModel(name=f"batch_{i}", value=i)
+        await model.asave()
+
+    # Update multiple
+    modified_count = await AsyncTestModel.aupdate_many(
+        {"value": {"$gte": 3}}, {"$set": {"name": "updated"}}
+    )
+    assert modified_count == 2
+
+    # Verify updates
+    results = await AsyncTestModel.afind({"name": "updated"})
+    assert len(results) == 2
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_delete_one(cleanup_test_collections):
+    """Test async delete_one operation with real MongoDB."""
+    # Create documents
+    model1 = AsyncTestModel(name="delete_me", value=1)
+    model2 = AsyncTestModel(name="delete_me", value=2)
+    await model1.asave()
+    await model2.asave()
+
+    # Delete one
+    deleted = await AsyncTestModel.adelete_one({"name": "delete_me"})
+    assert deleted is True
+
+    # Verify only one was deleted
+    count = await AsyncTestModel.acount({"name": "delete_me"})
+    assert count == 1
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_delete_one_no_match(cleanup_test_collections):
+    """Test adelete_one returns False when no document matches."""
+    deleted = await AsyncTestModel.adelete_one({"name": "nonexistent"})
+    assert deleted is False
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_delete_many(cleanup_test_collections):
+    """Test async delete_many operation with real MongoDB."""
+    # Create documents
+    for i in range(5):
+        model = AsyncTestModel(name=f"batch_delete_{i}", value=i)
+        await model.asave()
+
+    # Delete multiple
+    deleted_count = await AsyncTestModel.adelete_many({"value": {"$lt": 3}})
+    assert deleted_count == 3
+
+    # Verify remaining
+    count = await AsyncTestModel.acount()
+    assert count == 2
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_aggregate(cleanup_test_collections):
+    """Test async aggregate operation with real MongoDB."""
+    # Create documents
+    for i in range(5):
+        model = AsyncTestModel(name=f"agg_{i}", value=i)
+        await model.asave()
+
+    # Run aggregation
+    pipeline = [{"$match": {"value": {"$gte": 2}}}, {"$count": "total"}]
+    results = await AsyncTestModel.aaggregate(pipeline)
+
+    assert len(results) == 1
+    assert results[0]["total"] == 3
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_insert_many(cleanup_test_collections):
+    """Test async insert_many operation with real MongoDB."""
+    # Create models
+    models = [AsyncTestModel(name=f"bulk_{i}", value=i) for i in range(3)]
+
+    # Insert many
+    ids = await AsyncTestModel.ainsert_many(models)
+
+    assert len(ids) == 3
+    assert all(isinstance(id, str) for id in ids)
+
+    # Verify all were inserted
+    count = await AsyncTestModel.acount()
+    assert count == 3
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_insert_many_empty(cleanup_test_collections):
+    """Test ainsert_many with empty list."""
+    ids = await AsyncTestModel.ainsert_many([])
+    assert ids == []
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_delete_without_id(cleanup_test_collections):
+    """Test adelete returns False when ID is not set."""
+    model = AsyncTestModel(name="test", value=1)
+    model.id = None
+    assert await model.adelete() is False
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_save_exclude_none(cleanup_test_collections):
+    """Test async save with exclude_none parameter."""
+
+    # Create model with optional field
+    class ModelWithOptional(AsyncTestModel):
+        optional: str = None
+
+    model = ModelWithOptional(name="test", value=42)
+    doc_id = await model.asave(exclude_none=True)
+
+    # Verify it was saved
+    retrieved = await AsyncTestModel.aget(doc_id)
+    assert retrieved is not None
+    assert retrieved.name == "test"
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_update_one_upsert(cleanup_test_collections):
+    """Test async update_one with upsert."""
+    from lightodm import generate_id
+
+    # Update non-existent document with upsert
+    # Provide _id as string to avoid ObjectId generation
+    new_id = generate_id()
+    success = await AsyncTestModel.aupdate_one(
+        {"_id": new_id}, {"$set": {"_id": new_id, "name": "new_doc", "value": 99}}, upsert=True
+    )
+    assert success is True
+
+    # Verify it was created
+    result = await AsyncTestModel.afind_one({"name": "new_doc"})
+    assert result is not None
+    assert result.name == "new_doc"
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_async_update_one_no_match(cleanup_test_collections):
+    """Test aupdate_one returns False when no document matches."""
+    success = await AsyncTestModel.aupdate_one(
+        {"name": "nonexistent"}, {"$set": {"value": 999}}, upsert=False
+    )
+    assert success is False