stackraise 0.1.0__py3-none-any.whl

stackraise/db/pipeline.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Self
+import stackraise.db as db
+import stackraise.model as model
+import stackraise.inflection as inflection
+from .protocols import (
+    QueryLike,
+    ensure_mongo_query,
+    SortLike,
+    ensure_mongo_sort,
+    DocumentProtocol,
+)
+from .cursor import CursorMixin, CursorIterator
+from .adapter import Adapter
+
+_MISSING = object()
+
+
+class Pipeline[T: model.Dto](CursorMixin[T]):
+    def __init__(
+        self,
+        collection: db.Collection,
+    ):
+        self._collection = collection
+        self._result_type = None
+        self._stages = []
+
+    def result_type[R](self, type: type[R]) -> Pipeline[R]:
+        """Set the result type for the pipeline."""
+        self._result_type = type
+        return self
+
+    async def aiter(self):
+        adapter = (
+            Adapter(self._result_type)
+            if self._result_type
+            else self._collection.adapter
+        )
+        inner = await self._collection._aggregate(self._stages)
+        return CursorIterator(adapter, inner)
+
+    def stage(self, stage: Mapping[str, Any]) -> Pipeline:
+        """Add a stage to the pipeline."""
+        self._stages.append(stage)
+        return self
+
+    def match(self, query: QueryLike) -> Self:
+        """Add a $match stage to the pipeline."""
+        query = ensure_mongo_query(query)
+        if query:
+            self._stages.append({"$match": query})
+        return self
+
+    def unwind(
+        self,
+        field_path: str,
+        index_field: Optional[str] = None,
+        preserve: bool = False,
+    ) -> Self:
+        """Add an $unwind stage to the pipeline"""
+
+        if index_field is not None or preserve is not False:
+            params = {"path": f"${field_path}"}
+
+            if index_field is not None:
+                params["includeArrayIndex"] = index_field
+
+            if preserve is not False:
+                params["preserveNullAndEmptyArrays"] = True
+        else:
+            params = f"${field_path}"
+
+        self.stage({"$unwind": params})
+
+        return self
+
+    def sort(self, sort: SortLike) -> Self:
+        """Add a $sort stage to the pipeline."""
+        sort = ensure_mongo_sort(sort)
+        if sort:
+            self.stage({"$sort": sort})
+        return self
+
+    def set(self, set_fields: dict[str, Any]):
+        """Add a $set stage to the pipeline."""
+        if set_fields:
+            self.stage({"$set": set_fields})
+        return self
+
+    def unset(self, *unset_fields: list[str]):
+        """Add a $unset stage to the pipeline"""
+        if unset_fields:
+            self.stage({"$unset": unset_fields})
+        return self
+
+    def facet(self, facet_pipelines: dict[str, list] = {}) -> Self:
+        if facet_pipelines:
+            self.stage({"$facet": facet_pipelines})
+        return self
+
+    def embed(
+        self,
+        from_: type[DocumentProtocol] | db.Collection[DocumentProtocol] | Pipeline[DocumentProtocol],
+        ref_field: Optional[str] = None,
+        foreign_field: str = "_id",
+        as_field: Optional[str] = None,
+        #pipeline: Optional[Pipeline] = None,
+        by_query: Optional[QueryLike] = _MISSING,
+        many: bool = False,
+    ) -> Self:
+        """
+        Embed an entity from another collection into the pipeline.
+
+        This will perform a $lookup and $unwind operations to embed (or nest) a single document
+        from another collection into the current pipeline. This produces the following
+        stages according to  mongodb specification:
+        ```
+        # lookup stage
+        {
+            "$lookup": {
+                "from": collection.name,
+                "localField": field or to_camelcase(entity_name),
+                "foreignField": foreign_field or "_id",
+                "as": as_field or field or to_camelcase(entity_name)
+            }
+        }
+        # unwind stage if many is False
+        {
+            "$unwind": f"${as_field or field or to_camelcase(entity_name)}"
+        }
+        ```
+        """
+
+        pipeline = []
+        if isinstance(from_, Pipeline):
+            collection = from_._collection
+            pipeline = from_._stages
+        elif isinstance(from_, type):
+            collection = from_.collection
+        else:
+            collection = from_
+
+        if ref_field is None:
+            ref_field = inflection.to_camelcase(collection.adapter.typename)
+
+        if as_field is None:
+            as_field = ref_field
+
+        if by_query is not _MISSING:
+            by_query = ensure_mongo_query(by_query)
+
+            self.stage(
+                {
+                    "$lookup": {
+                        "from": collection.name,
+                        "as": as_field,
+                        "pipeline": [{"$match": by_query}, *pipeline],
+                    }
+                }
+            )
+        else:
+
+            self.stage(
+                {
+                    "$lookup": {
+                        "from": collection.name,
+                        "localField": ref_field,
+                        "foreignField": foreign_field,
+                        "as": as_field,
+                        "pipeline": pipeline,
+                    }
+                }
+            )
+
+        if many is False:
+            self.unwind(as_field)
+
+        return self
+
+    def join(
+        self,
+        from_: (
+            type[DocumentProtocol]
+            | db.Collection[DocumentProtocol]
+            | Pipeline[DocumentProtocol]
+        ),
+        local_field: str = "_id",
+        foreign_field: Optional[str] = None,
+        as_field: Optional[str] = None,
+        unwind: bool = False,
+    ) -> Self:
+        """
+        Join another collection into the pipeline.
+        This will perform a $lookup operation to join another collection into the current pipeline.
+        The resulting stages will look like this:
+        ```
+        {
+            "$lookup": {
+                "from": collection.name,
+                "localField": local_field,
+                "foreignField": foreign_field or to_camelcase(entity_name),
+                "as": as_field or collection.name
+            }
+        }
+        ```
+        If `unwind` is True, it will also add an `$unwind` stage
+        ```
+        {
+            "$unwind": f"${as_field or collection.name}"
+        }
+        ```
+        """
+        pipeline = []
+        if isinstance(from_, Pipeline):
+            pipeline = from_._stages
+            collection = from_._collection
+        elif isinstance(from_, type):
+            collection = from_.collection
+        else:
+            collection = from_
+
+        if foreign_field is None:
+            foreign_field = inflection.to_camelcase(self._collection.adapter.typename)
+
+        if as_field is None:
+            as_field = inflection.to_camelcase(collection.name)
+
+
+        self.stage(
+            {
+                "$lookup": {
+                    "from": collection.name,
+                    "localField": local_field,
+                    "foreignField": foreign_field,
+                    "as": as_field,
+                    "pipeline": pipeline,
+                }
+            }
+        )
+
+        if unwind:
+            self.unwind(as_field)
+
+        return self

stackraise/db/protocols.py

@@ -0,0 +1,141 @@
+#%%
+from __future__ import annotations
+
+from typing import Any, Literal, Mapping, Protocol, Self, ClassVar
+from weakref import WeakSet
+
+import stackraise.db as db
+
+
+class DocumentProtocol(Protocol):
+    #kind: ClassVar[str]
+    id: db.Id
+    ref: db.Document.Ref
+    collection: ClassVar[db.Collection[Self]]
+
+    async def __prepare_for_storage__(self) -> None:
+        """Check the document's integrity."""
+        pass
+
+    async def __handle_post_deletion__(self) -> None:
+        """Perform any cleanup after the document is deleted."""
+        pass
+
+
+type MongoQuery = Mapping[str, Any]
+type QueryLike = QueryProtocol | Mapping[str, Any]
+
+class QueryProtocol(Protocol):
+    async def to_mongo_query(self) -> MongoQuery:
+        """Convert the query to a MongoDB query."""
+        pass
+
+
+def ensure_mongo_query(query: QueryLike) -> MongoQuery:
+    if not isinstance(query, Mapping):
+        if not hasattr(query, "to_mongo_query"):
+            raise TypeError(f"Expected a Mapping or QueryProtocol, got {type(query)}")
+        query = query.to_mongo_query()
+        assert isinstance(query, Mapping), f"Expected a Mapping, got {type(query)}"
+    return query
+
+
+def merge_queries(*queries: QueryLike) -> MongoQuery:
+    """Merge multiple queries into a single MongoDB query."""
+    merged_query: MongoQuery = {}
+    for query in queries:
+        if isinstance(query, Mapping):
+            merged_query.update(query)
+        elif hasattr(query, "to_mongo_query"):
+            merged_query.update(query.to_mongo_query())
+        else:
+            raise TypeError(f"Expected a Mapping or QueryProtocol, got {type(query)}")
+    return merged_query
+
+type MongoSort = dict[str, Literal[1, -1]]
+type SortLike = MongoSort | str
+
+class SortProtocol(Protocol):
+    async def to_mongo_sort(self) -> MongoSort:
+        """Convert the sort to a MongoDB sort."""
+        pass
+
+_SORT_MODE_MAPPING = {
+    '<': 1,
+    '>': -1,
+    '=': None,  # No ordering by this field
+    1: 1,
+    -1: -1,
+    0: None,  # No ordering by this field
+}
+def ensure_mongo_sort(sort: SortLike) -> MongoSort:
+    """Ensure the sort is a valid MongoDB sort."""
+    def mode_mapping(mode: Any) -> Literal[1, -1, None]:
+        if mode not in _SORT_MODE_MAPPING:
+            raise ValueError(f"Invalid sort mode: {mode}")
+        return _SORT_MODE_MAPPING[mode]
+
+
+    if isinstance(sort, str):
+        sort = {sort: 1}  # Default to ascending order
+    elif isinstance(sort, list):
+        sort = {field: 1 for field in sort}  # Default to ascending order for all fields
+    if not isinstance(sort, dict):
+        if not hasattr(sort, "to_mongo_sort"):
+            raise TypeError(f"Expected a dict or SortProtocol, got {type(sort)}")
+        sort = sort.to_mongo_sort()
+        
+    assert isinstance(sort, dict), f"Expected a dict, got {type(sort)}"
+    return {k: m for k, v in sort.items() if (m := mode_mapping(v)) is not None}
+
+
+type MongoPipeline = list[Mapping[str, Any]]
+type PipelineLike = PipelineProtocol | MongoPipeline
+
+class PipelineProtocol(Protocol):
+    async def to_mongo_pipeline(self) -> MongoPipeline:
+        """Convert the pipeline to a MongoDB pipeline."""
+        pass
+
+def ensure_mongo_pipeline(pipeline: PipelineLike) -> MongoPipeline:
+    if not isinstance(pipeline, list):
+        if not hasattr(pipeline, "to_mongo_pipeline"):
+            raise TypeError(f"Expected a list or PipelineProtocol, got {type(pipeline)}")
+        pipeline = pipeline.to_mongo_pipeline()
+    return pipeline
+
+
+
+_collection_instances: WeakSet[CollectionProtocol] = WeakSet()
+
+def register_collection_instance(collection: CollectionProtocol):
+    """Register a collection instance."""
+    _collection_instances.add(collection)
+
+def get_collection_instances() -> list[CollectionProtocol]:
+    """Return all registered collection instances."""
+    return list(_collection_instances)
+
+class CollectionProtocol(Protocol):
+    name: str
+    document_cls: type[db.Document]
+
+    async def _startup_task(self) -> None:
+        """Manage the lifespan of the collection."""
+        pass
+
+    async def find(self, query: QueryLike) -> list[db.Document]:
+        """Find documents matching the query."""
+        pass
+
+    async def insert_one(self, document: db.Document) -> db.Id:
+        """Insert a single document."""
+        pass
+
+    async def update_one(self, query: QueryLike, update: Mapping[str, Any]) -> None:
+        """Update a single document."""
+        pass
+
+    async def delete_one(self, query: QueryLike) -> None:
+        """Delete a single document."""
+        pass

stackraise/di.py

@@ -0,0 +1,36 @@
+from typing import Protocol, Self, runtime_checkable, Awaitable
+from fastapi import Depends
+
+
+@runtime_checkable
+class Injectable[T](Protocol):
+    def inject(self) -> Awaitable[T] | T: ...
+
+
+def Inject[T](obj: Injectable[T]) -> Self:
+    assert issubclass(obj, Injectable), f"Cannot inject {obj}, it is not an Injectable"
+    return Depends(obj.inject)
+
+
+class Singleton:
+    _instance = None
+
+    def __new__(cls, *args, **kwargs):
+        assert (
+            cls._instance is None
+        ), f"Singleton instance of {cls.__qualname__} already initialized"
+
+        if cls._instance is not None:
+            return cls._instance
+
+        self = super().__new__(cls)
+
+        cls._instance = self
+        return self
+
+    @classmethod
+    def inject(cls) -> Self:
+        assert (
+            cls._instance is not None
+        ), f"Singleton instance of {cls.__qualname__} not initialized"
+        return cls._instance

stackraise/event.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+from inspect import iscoroutinefunction
+from typing import Awaitable, Callable, Generic, Optional, TypeAlias, TypeVar
+from anyio import create_task_group
+from stackraise.logging import get_logger
+
+E = TypeVar("E")
+
+EventHandler: TypeAlias = Callable[[E], Awaitable[None] | None]
+AsyncEventHandler: TypeAlias = Callable[[E], Awaitable[None]]
+
+
+class EventEmitter(Generic[E]):
+    """Representa una fuente de eventos
+
+    >>> from pydantic import BaseModel
+    >>> class UserSigninEvent(BaseModel)
+    >>> user_signin_event = EventEmitter()
+
+    >>> user_signin_event.emit(UserSigninEvent())
+
+    """
+
+    _name: str
+    _subscriptions: set[EventSubscription]
+
+    def __init__(self, name: str):
+        self._name = name
+        self._log = get_logger(f"{name} event emitter")
+        self._subscriptions = set()
+        self._exception_count: int = 0
+
+    def __repr__(self):
+        return (
+            f"EventEmitter({self._name}, "
+            f"{len(self._subscriptions)} enabled subscriptions, "
+            f"{len(self._exception_count)} exceptions counted)"
+        )
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def log(self):
+        return self._log
+
+    @property
+    def subscriptions(self) -> list[EventSubscription]:
+        return list(self._subscriptions)
+
+    async def emit(self, event: E):
+        """Emite un evento"""
+        try:
+            async with create_task_group() as tg:
+                for sub in self.subscriptions:
+                    tg.start_soon(sub._event_task, event, name=self.name)
+        except* Exception as e:
+            self.log.exception("Occurred while broadcasting event")
+            
+
+    __call__ = emit
+
+    @property
+    def exception_count(self):
+        return self._exception_count
+
+    def subscribe(
+        self, handler: EventHandler, name: Optional[str] = None
+    ) -> EventSubscription:
+        subscription = EventSubscription(self, handler, name=name)
+        subscription.subscribe()
+        return subscription
+
+    def handler(
+        self, /, name: Optional[str] = None
+    ) -> Callable[[EventHandler], EventHandler]:
+        def decorator(handler: EventHandler) -> EventHandler:
+            self.subscribe(handler, name=name)
+            return handler
+
+        return decorator
+
+
+class EventSubscription(Generic[E]):
+    _name: str
+    _emitter: EventEmitter[E]
+    _event_handler: AsyncEventHandler
+    _exception_handler: Callable[[ExceptionGroup]]
+
+    def __init__(
+        self,
+        emitter: EventEmitter[E],
+        handler: EventHandler,
+        name: Optional[str] = None,
+    ):
+        self._name = name or handler.__name__
+        self._emitter = emitter
+        self._event_handler = ensure_async(handler)
+        self._exception_handler = default_exception_handler
+
+    def __repr__(self):
+        return (
+            f"EventSubscription({self._emitter._name}, "
+            f"{self._name} "
+            f'{"enabled" if self.is_enabled else "disabled"})'
+        )
+
+    @property
+    def emitter(self):
+        return self._emitter
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def is_enabled(self) -> bool:
+        return self in self._emitter._subscriptions
+
+    def subscribe(self):
+        self._emitter._subscriptions.add(self)
+
+    def unsubscribe(self):
+        self._emitter._subscriptions.remove(self)
+
+    async def _event_task(self, event: E):
+        try:
+            await self._event_handler(event)
+        except* Exception as exc:
+            self._emitter._exception_count += 1
+            try:
+                self._exception_handler(exc, self)
+            except* Exception as nested_exc:
+                self.emitter.log.fatal("Exception handling exception")
+                self.emitter.log.exception(nested_exc)
+
+
+def default_exception_handler(exc: Exception, subscription: EventSubscription):
+    subscription.emitter.log.exception(exc)
+
+
+def ensure_async(fn: Callable[[E], Awaitable[None]]):
+    if not iscoroutinefunction(fn):
+
+        async def async_wrapper(*args, **kwargs):
+            return fn(*args, **kwargs)
+
+        return async_wrapper
+    return fn

stackraise/inflection.py

@@ -0,0 +1,28 @@
+from functools import cache
+
+from inflector import English
+from slugify import slugify
+
+_english_inflector = English()
+
+@cache
+def to_tablename(s: str) -> str:
+    return _english_inflector.tableize(s)
+
+@cache
+def to_camelcase(s: str) -> str:
+    ns = s.rstrip('_')
+
+    camel = _english_inflector.camelize(ns)
+    camel = camel[0].lower() + camel[1:]
+
+    return camel + '_' * (len(s) - len(ns))
+
+@cache
+def to_slug(s: str) -> str:
+    return slugify(s)
+
+@cache
+def to_underscore(s: str) -> str:
+    return _english_inflector.underscore(s)
+

stackraise/io/__init__.py

@@ -0,0 +1,3 @@
+#from .email_message import *
+from .imap_client import *
+from .smtp_client import *