mdb-engine 0.1.6__py3-none-any.whl → 0.2.0__py3-none-any.whl

mdb_engine/repositories/base.py

@@ -0,0 +1,325 @@
+"""
+Abstract Repository Pattern
+
+Defines the repository interface that abstracts data access operations.
+This allows domain services to work with any data store implementation.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, Generic, List, Optional, TypeVar
+
+from bson import ObjectId
+
+
+@dataclass
+class Entity:
+    """
+    Base class for domain entities.
+
+    All entities have an ID and timestamps. Subclass this for your domain models.
+
+    Example:
+        @dataclass
+        class User(Entity):
+            email: str
+            name: str
+            role: str = "user"
+    """
+
+    id: Optional[str] = None
+    created_at: Optional[datetime] = field(default=None)
+    updated_at: Optional[datetime] = field(default=None)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert entity to dictionary for storage."""
+        data = {}
+        for key, value in self.__dict__.items():
+            if value is not None:
+                if key == "id":
+                    # Convert string ID to ObjectId for MongoDB
+                    if value and ObjectId.is_valid(value):
+                        data["_id"] = ObjectId(value)
+                    else:
+                        data["_id"] = value
+                else:
+                    data[key] = value
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Entity":
+        """Create entity from dictionary (e.g., from database)."""
+        if data is None:
+            return None
+
+        # Convert _id to id
+        if "_id" in data:
+            data["id"] = str(data.pop("_id"))
+
+        # Get field names from dataclass
+        import dataclasses
+
+        field_names = {f.name for f in dataclasses.fields(cls)}
+
+        # Filter to only known fields
+        filtered_data = {k: v for k, v in data.items() if k in field_names}
+
+        return cls(**filtered_data)
+
+
+T = TypeVar("T", bound=Entity)
+
+
+class Repository(ABC, Generic[T]):
+    """
+    Abstract repository interface for data access.
+
+    This interface defines standard CRUD operations that can be
+    implemented for any data store (MongoDB, PostgreSQL, in-memory, etc.)
+
+    Type parameter T should be an Entity subclass.
+
+    Example:
+        class UserRepository(Repository[User]):
+            async def find_by_email(self, email: str) -> Optional[User]:
+                users = await self.find({"email": email}, limit=1)
+                return users[0] if users else None
+    """
+
+    @abstractmethod
+    async def get(self, id: str) -> Optional[T]:
+        """
+        Get a single entity by ID.
+
+        Args:
+            id: Entity ID
+
+        Returns:
+            Entity if found, None otherwise
+        """
+        pass
+
+    @abstractmethod
+    async def find(
+        self,
+        filter: Optional[Dict[str, Any]] = None,
+        skip: int = 0,
+        limit: int = 100,
+        sort: Optional[List[tuple]] = None,
+    ) -> List[T]:
+        """
+        Find entities matching a filter.
+
+        Args:
+            filter: MongoDB-style filter dictionary
+            skip: Number of documents to skip
+            limit: Maximum documents to return
+            sort: List of (field, direction) tuples
+
+        Returns:
+            List of matching entities
+        """
+        pass
+
+    @abstractmethod
+    async def find_one(
+        self,
+        filter: Dict[str, Any],
+    ) -> Optional[T]:
+        """
+        Find a single entity matching a filter.
+
+        Args:
+            filter: MongoDB-style filter dictionary
+
+        Returns:
+            First matching entity or None
+        """
+        pass
+
+    @abstractmethod
+    async def add(self, entity: T) -> str:
+        """
+        Add a new entity.
+
+        Args:
+            entity: Entity to add
+
+        Returns:
+            ID of the created entity
+        """
+        pass
+
+    @abstractmethod
+    async def add_many(self, entities: List[T]) -> List[str]:
+        """
+        Add multiple entities.
+
+        Args:
+            entities: List of entities to add
+
+        Returns:
+            List of created entity IDs
+        """
+        pass
+
+    @abstractmethod
+    async def update(self, id: str, entity: T) -> bool:
+        """
+        Update an existing entity.
+
+        Args:
+            id: Entity ID
+            entity: Updated entity data
+
+        Returns:
+            True if entity was updated, False if not found
+        """
+        pass
+
+    @abstractmethod
+    async def update_fields(self, id: str, fields: Dict[str, Any]) -> bool:
+        """
+        Update specific fields of an entity.
+
+        Args:
+            id: Entity ID
+            fields: Dictionary of fields to update
+
+        Returns:
+            True if entity was updated, False if not found
+        """
+        pass
+
+    @abstractmethod
+    async def delete(self, id: str) -> bool:
+        """
+        Delete an entity by ID.
+
+        Args:
+            id: Entity ID
+
+        Returns:
+            True if entity was deleted, False if not found
+        """
+        pass
+
+    @abstractmethod
+    async def count(self, filter: Optional[Dict[str, Any]] = None) -> int:
+        """
+        Count entities matching a filter.
+
+        Args:
+            filter: MongoDB-style filter dictionary
+
+        Returns:
+            Count of matching entities
+        """
+        pass
+
+    @abstractmethod
+    async def exists(self, id: str) -> bool:
+        """
+        Check if an entity exists.
+
+        Args:
+            id: Entity ID
+
+        Returns:
+            True if entity exists
+        """
+        pass
+
+
+class InMemoryRepository(Repository[T]):
+    """
+    In-memory repository implementation for testing.
+
+    Stores entities in a dictionary, useful for unit tests
+    without database dependencies.
+    """
+
+    def __init__(self, entity_class: type):
+        self._entity_class = entity_class
+        self._storage: Dict[str, Dict[str, Any]] = {}
+        self._counter = 0
+
+    async def get(self, id: str) -> Optional[T]:
+        data = self._storage.get(id)
+        if data is None:
+            return None
+        return self._entity_class.from_dict(data)
+
+    async def find(
+        self,
+        filter: Optional[Dict[str, Any]] = None,
+        skip: int = 0,
+        limit: int = 100,
+        sort: Optional[List[tuple]] = None,
+    ) -> List[T]:
+        results = []
+        for data in self._storage.values():
+            if filter is None or self._matches_filter(data, filter):
+                results.append(self._entity_class.from_dict(data))
+
+        # Apply skip and limit
+        return results[skip : skip + limit]
+
+    async def find_one(self, filter: Dict[str, Any]) -> Optional[T]:
+        results = await self.find(filter, limit=1)
+        return results[0] if results else None
+
+    async def add(self, entity: T) -> str:
+        self._counter += 1
+        id = str(self._counter)
+        entity.id = id
+        entity.created_at = datetime.utcnow()
+        self._storage[id] = entity.to_dict()
+        return id
+
+    async def add_many(self, entities: List[T]) -> List[str]:
+        return [await self.add(e) for e in entities]
+
+    async def update(self, id: str, entity: T) -> bool:
+        if id not in self._storage:
+            return False
+        entity.id = id
+        entity.updated_at = datetime.utcnow()
+        self._storage[id] = entity.to_dict()
+        return True
+
+    async def update_fields(self, id: str, fields: Dict[str, Any]) -> bool:
+        if id not in self._storage:
+            return False
+        self._storage[id].update(fields)
+        self._storage[id]["updated_at"] = datetime.utcnow()
+        return True
+
+    async def delete(self, id: str) -> bool:
+        if id not in self._storage:
+            return False
+        del self._storage[id]
+        return True
+
+    async def count(self, filter: Optional[Dict[str, Any]] = None) -> int:
+        if filter is None:
+            return len(self._storage)
+        return len(await self.find(filter, limit=999999))
+
+    async def exists(self, id: str) -> bool:
+        return id in self._storage
+
+    def _matches_filter(self, data: Dict[str, Any], filter: Dict[str, Any]) -> bool:
+        """Simple filter matching for testing."""
+        for key, value in filter.items():
+            if key not in data:
+                return False
+            if data[key] != value:
+                return False
+        return True
+
+    def clear(self) -> None:
+        """Clear all entities (useful for test setup)."""
+        self._storage.clear()
+        self._counter = 0

mdb_engine/repositories/mongo.py

@@ -0,0 +1,233 @@
+"""
+MongoDB Repository Implementation
+
+Implements the Repository interface using MongoDB through ScopedCollectionWrapper.
+This provides automatic app scoping and security features.
+"""
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, Generic, List, Optional, Type, TypeVar
+
+from bson import ObjectId
+
+from .base import Entity, Repository
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=Entity)
+
+
+class MongoRepository(Repository[T], Generic[T]):
+    """
+    MongoDB implementation of the Repository interface.
+
+    Uses ScopedCollectionWrapper for automatic app_id scoping
+    and security features.
+
+    Example:
+        # Direct usage
+        users_collection = db.users  # ScopedCollectionWrapper
+        user_repo = MongoRepository(users_collection, User)
+
+        # Find users
+        users = await user_repo.find({"role": "admin"})
+
+        # Add new user
+        user = User(email="john@example.com", name="John")
+        user_id = await user_repo.add(user)
+    """
+
+    def __init__(
+        self,
+        collection: Any,  # ScopedCollectionWrapper - avoid import cycle
+        entity_class: Type[T],
+    ):
+        """
+        Initialize the MongoDB repository.
+
+        Args:
+            collection: ScopedCollectionWrapper for the collection
+            entity_class: Entity subclass for this repository
+        """
+        self._collection = collection
+        self._entity_class = entity_class
+
+    def _to_entity(self, doc: Optional[Dict[str, Any]]) -> Optional[T]:
+        """Convert a MongoDB document to an entity."""
+        if doc is None:
+            return None
+        return self._entity_class.from_dict(doc)
+
+    def _to_document(self, entity: T, include_id: bool = False) -> Dict[str, Any]:
+        """Convert an entity to a MongoDB document."""
+        doc = entity.to_dict()
+        if not include_id and "_id" in doc:
+            del doc["_id"]
+        return doc
+
+    async def get(self, id: str) -> Optional[T]:
+        """Get entity by ID."""
+        try:
+            object_id = ObjectId(id) if ObjectId.is_valid(id) else id
+        except (TypeError, ValueError):
+            return None
+
+        doc = await self._collection.find_one({"_id": object_id})
+        return self._to_entity(doc)
+
+    async def find(
+        self,
+        filter: Optional[Dict[str, Any]] = None,
+        skip: int = 0,
+        limit: int = 100,
+        sort: Optional[List[tuple]] = None,
+    ) -> List[T]:
+        """Find entities matching a filter."""
+        cursor = self._collection.find(filter or {})
+
+        if skip > 0:
+            cursor = cursor.skip(skip)
+        if limit > 0:
+            cursor = cursor.limit(limit)
+        if sort:
+            cursor = cursor.sort(sort)
+
+        docs = await cursor.to_list(length=limit)
+        return [self._to_entity(doc) for doc in docs]
+
+    async def find_one(self, filter: Dict[str, Any]) -> Optional[T]:
+        """Find a single entity matching a filter."""
+        doc = await self._collection.find_one(filter)
+        return self._to_entity(doc)
+
+    async def add(self, entity: T) -> str:
+        """Add a new entity and return its ID."""
+        entity.created_at = datetime.utcnow()
+        doc = self._to_document(entity)
+
+        result = await self._collection.insert_one(doc)
+        entity.id = str(result.inserted_id)
+
+        logger.debug(f"Added {self._entity_class.__name__} with id={entity.id}")
+        return entity.id
+
+    async def add_many(self, entities: List[T]) -> List[str]:
+        """Add multiple entities and return their IDs."""
+        now = datetime.utcnow()
+        docs = []
+
+        for entity in entities:
+            entity.created_at = now
+            docs.append(self._to_document(entity))
+
+        result = await self._collection.insert_many(docs)
+        ids = [str(id) for id in result.inserted_ids]
+
+        for entity, id in zip(entities, ids):
+            entity.id = id
+
+        logger.debug(f"Added {len(ids)} {self._entity_class.__name__} entities")
+        return ids
+
+    async def update(self, id: str, entity: T) -> bool:
+        """Update an entity by ID."""
+        try:
+            object_id = ObjectId(id) if ObjectId.is_valid(id) else id
+        except (TypeError, ValueError):
+            return False
+
+        entity.updated_at = datetime.utcnow()
+        doc = self._to_document(entity)
+
+        result = await self._collection.update_one({"_id": object_id}, {"$set": doc})
+
+        return result.modified_count > 0
+
+    async def update_fields(self, id: str, fields: Dict[str, Any]) -> bool:
+        """Update specific fields of an entity."""
+        try:
+            object_id = ObjectId(id) if ObjectId.is_valid(id) else id
+        except (TypeError, ValueError):
+            return False
+
+        fields["updated_at"] = datetime.utcnow()
+
+        result = await self._collection.update_one({"_id": object_id}, {"$set": fields})
+
+        return result.modified_count > 0
+
+    async def delete(self, id: str) -> bool:
+        """Delete an entity by ID."""
+        try:
+            object_id = ObjectId(id) if ObjectId.is_valid(id) else id
+        except (TypeError, ValueError):
+            return False
+
+        result = await self._collection.delete_one({"_id": object_id})
+        return result.deleted_count > 0
+
+    async def count(self, filter: Optional[Dict[str, Any]] = None) -> int:
+        """Count entities matching a filter."""
+        return await self._collection.count_documents(filter or {})
+
+    async def exists(self, id: str) -> bool:
+        """Check if an entity exists."""
+        try:
+            object_id = ObjectId(id) if ObjectId.is_valid(id) else id
+        except (TypeError, ValueError):
+            return False
+
+        doc = await self._collection.find_one({"_id": object_id}, projection={"_id": 1})
+        return doc is not None
+
+    # Additional MongoDB-specific methods
+
+    async def aggregate(self, pipeline: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Run an aggregation pipeline.
+
+        Args:
+            pipeline: MongoDB aggregation pipeline
+
+        Returns:
+            List of result documents
+        """
+        cursor = self._collection.aggregate(pipeline)
+        return await cursor.to_list(length=None)
+
+    async def update_many(
+        self,
+        filter: Dict[str, Any],
+        update: Dict[str, Any],
+    ) -> int:
+        """
+        Update multiple documents matching a filter.
+
+        Args:
+            filter: MongoDB filter
+            update: Update operations
+
+        Returns:
+            Number of modified documents
+        """
+        if "$set" not in update:
+            update = {"$set": update}
+
+        update["$set"]["updated_at"] = datetime.utcnow()
+
+        result = await self._collection.update_many(filter, update)
+        return result.modified_count
+
+    async def delete_many(self, filter: Dict[str, Any]) -> int:
+        """
+        Delete multiple documents matching a filter.
+
+        Args:
+            filter: MongoDB filter
+
+        Returns:
+            Number of deleted documents
+        """
+        result = await self._collection.delete_many(filter)
+        return result.deleted_count