python-cq 0.1.0__py3-none-any.whl

cq/__init__.py

@@ -0,0 +1,23 @@
+from ._core.command import Command, CommandBus, command_handler, find_command_bus
+from ._core.dto import DTO
+from ._core.event import Event, EventBus, event_handler, find_event_bus
+from ._core.middleware import Middleware, MiddlewareResult
+from ._core.query import Query, QueryBus, find_query_bus, query_handler
+
+__all__ = (
+    "Command",
+    "CommandBus",
+    "DTO",
+    "Event",
+    "EventBus",
+    "Middleware",
+    "MiddlewareResult",
+    "Query",
+    "QueryBus",
+    "command_handler",
+    "event_handler",
+    "find_command_bus",
+    "find_event_bus",
+    "find_query_bus",
+    "query_handler",
+)

cq/_core/bus.py

@@ -0,0 +1,156 @@
+import asyncio
+from abc import ABC, abstractmethod
+from collections import defaultdict
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from inspect import isclass
+from types import GenericAlias
+from typing import Protocol, Self, TypeAliasType, runtime_checkable
+
+import injection
+
+from cq._core.middleware import Middleware, MiddlewareGroup
+
+type HandlerType[**P, T] = type[Handler[P, T]]
+type HandlerFactory[**P, T] = Callable[..., Handler[P, T]]
+
+type BusType[I, O] = type[Bus[I, O]]
+
+
+@runtime_checkable
+class Handler[**P, T](Protocol):
+    __slots__ = ()
+
+    @abstractmethod
+    async def handle(self, *args: P.args, **kwargs: P.kwargs) -> T:
+        raise NotImplementedError
+
+
+@runtime_checkable
+class Bus[I, O](Protocol):
+    __slots__ = ()
+
+    @abstractmethod
+    async def dispatch(self, input_value: I, /) -> O:
+        raise NotImplementedError
+
+    def dispatch_no_wait(self, first_input_value: I, /, *input_values: I) -> None:
+        asyncio.gather(
+            *(
+                self.dispatch(input_value)
+                for input_value in (first_input_value, *input_values)
+            )
+        )
+
+    @abstractmethod
+    def subscribe(self, input_type: type[I], factory: HandlerFactory[[I], O]) -> Self:
+        raise NotImplementedError
+
+    @abstractmethod
+    def add_middlewares(self, *middlewares: Middleware[[I], O]) -> Self:
+        raise NotImplementedError
+
+
+@dataclass(eq=False, frozen=True, slots=True)
+class SubscriberDecorator[I, O]:
+    bus_type: BusType[I, O] | TypeAliasType | GenericAlias
+    injection_module: injection.Module = field(default_factory=injection.mod)
+
+    def __call__[T](
+        self,
+        first_input_type: type[I],
+        /,
+        *input_types: type[I],
+    ) -> Callable[[T], T]:
+        def decorator(wrapped: T) -> T:
+            if not isclass(wrapped) or not issubclass(wrapped, Handler):
+                raise TypeError(f"`{wrapped}` isn't a valid handler.")
+
+            bus = self.__find_bus()
+            factory = self.injection_module.make_injected_function(wrapped)
+
+            for input_type in (first_input_type, *input_types):
+                bus.subscribe(input_type, factory)
+
+            return wrapped  # type: ignore[return-value]
+
+        return decorator
+
+    def __find_bus(self) -> Bus[I, O]:
+        return self.injection_module.find_instance(self.bus_type)
+
+
+class _BaseBus[I, O](Bus[I, O], ABC):
+    __slots__ = ("__middleware_group",)
+
+    __middleware_group: MiddlewareGroup[[I], O]
+
+    def __init__(self) -> None:
+        self.__middleware_group = MiddlewareGroup()
+
+    def add_middlewares(self, *middlewares: Middleware[[I], O]) -> Self:
+        self.__middleware_group.add(*middlewares)
+        return self
+
+    async def _invoke(self, handler: Handler[[I], O], input_value: I, /) -> O:
+        return await self.__middleware_group.invoke(handler.handle, input_value)
+
+
+class SimpleBus[I, O](_BaseBus[I, O]):
+    __slots__ = ("__handlers",)
+
+    __handlers: dict[type[I], HandlerFactory[[I], O]]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.__handlers = {}
+
+    async def dispatch(self, input_value: I, /) -> O:
+        input_type = type(input_value)
+
+        try:
+            handler_factory = self.__handlers[input_type]
+        except KeyError:
+            return NotImplemented
+
+        return await self._invoke(handler_factory(), input_value)
+
+    def subscribe(self, input_type: type[I], factory: HandlerFactory[[I], O]) -> Self:
+        if input_type in self.__handlers:
+            raise RuntimeError(
+                f"A handler is already registered for the input type: `{input_type}`."
+            )
+
+        self.__handlers[input_type] = factory
+        return self
+
+
+class TaskBus[I](_BaseBus[I, None]):
+    __slots__ = ("__handlers",)
+
+    __handlers: dict[type[I], list[HandlerFactory[[I], None]]]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.__handlers = defaultdict(list)
+
+    async def dispatch(self, input_value: I, /) -> None:
+        handler_factories = self.__handlers.get(type(input_value))
+
+        if not handler_factories:
+            return
+
+        await asyncio.gather(
+            *(
+                self._invoke(handler_factory(), input_value)
+                for handler_factory in handler_factories
+            )
+        )
+
+    def subscribe(
+        self,
+        input_type: type[I],
+        factory: HandlerFactory[[I], None],
+    ) -> Self:
+        self.__handlers[input_type].append(factory)
+        return self

cq/_core/command.py

@@ -0,0 +1,21 @@
+from abc import ABC
+from typing import Any
+
+import injection
+
+from cq._core.bus import Bus, SimpleBus, SubscriberDecorator
+from cq._core.dto import DTO
+
+
+class Command(DTO, ABC):
+    __slots__ = ()
+
+
+type CommandBus[T] = Bus[Command, T]
+command_handler: SubscriberDecorator[Command, Any] = SubscriberDecorator(CommandBus)
+
+injection.set_constant(SimpleBus(), CommandBus, alias=True)
+
+
+def find_command_bus[T]() -> CommandBus[T]:
+    return injection.find_instance(CommandBus)

cq/_core/dto.py

@@ -0,0 +1,10 @@
+from abc import ABC
+from typing import ClassVar
+
+from pydantic import BaseModel, ConfigDict
+
+
+class DTO(BaseModel, ABC):
+    __slots__ = ()
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(frozen=True)

cq/_core/event.py

@@ -0,0 +1,20 @@
+from abc import ABC
+
+import injection
+
+from cq._core.bus import Bus, SubscriberDecorator, TaskBus
+from cq._core.dto import DTO
+
+
+class Event(DTO, ABC):
+    __slots__ = ()
+
+
+type EventBus = Bus[Event, None]
+event_handler: SubscriberDecorator[Event, None] = SubscriberDecorator(EventBus)
+
+injection.set_constant(TaskBus(), EventBus, alias=True)
+
+
+def find_event_bus() -> EventBus:
+    return injection.find_instance(EventBus)

cq/_core/middleware.py

@@ -0,0 +1,74 @@
+from collections.abc import AsyncGenerator, Awaitable, Callable, Iterator
+from dataclasses import dataclass, field
+from typing import Self
+
+type MiddlewareResult[T] = AsyncGenerator[None, T]
+type Middleware[**P, T] = Callable[P, MiddlewareResult[T]]
+
+
+@dataclass(eq=False, frozen=True, slots=True)
+class MiddlewareGroup[**P, T]:
+    __middlewares: list[Middleware[P, T]] = field(
+        default_factory=list,
+        init=False,
+        repr=False,
+    )
+
+    @property
+    def __stack(self) -> Iterator[Middleware[P, T]]:
+        return iter(self.__middlewares)
+
+    def add(self, *middlewares: Middleware[P, T]) -> Self:
+        self.__middlewares.extend(middlewares)
+        return self
+
+    async def invoke(
+        self,
+        handler: Callable[P, Awaitable[T]],
+        /,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> T:
+        return await self.__apply_stack(handler, self.__stack)(*args, **kwargs)
+
+    @classmethod
+    def __apply_middleware(
+        cls,
+        handler: Callable[P, Awaitable[T]],
+        middleware: Middleware[P, T],
+    ) -> Callable[P, Awaitable[T]]:
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            generator: MiddlewareResult[T] = middleware(*args, **kwargs)
+            value: T = NotImplemented
+
+            try:
+                await anext(generator)
+
+                try:
+                    value = await handler(*args, **kwargs)
+                except BaseException as exc:
+                    await generator.athrow(exc)
+                else:
+                    await generator.asend(value)
+
+            except StopAsyncIteration:
+                ...
+
+            finally:
+                await generator.aclose()
+
+            return value
+
+        return wrapper
+
+    @classmethod
+    def __apply_stack(
+        cls,
+        handler: Callable[P, Awaitable[T]],
+        stack: Iterator[Middleware[P, T]],
+    ) -> Callable[P, Awaitable[T]]:
+        for middleware in stack:
+            new_handler = cls.__apply_middleware(handler, middleware)
+            return cls.__apply_stack(new_handler, stack)
+
+        return handler

cq/_core/query.py

@@ -0,0 +1,21 @@
+from abc import ABC
+from typing import Any
+
+import injection
+
+from cq._core.bus import Bus, SimpleBus, SubscriberDecorator
+from cq._core.dto import DTO
+
+
+class Query(DTO, ABC):
+    __slots__ = ()
+
+
+type QueryBus[T] = Bus[Query, T]
+query_handler: SubscriberDecorator[Query, Any] = SubscriberDecorator(QueryBus)
+
+injection.set_constant(SimpleBus(), QueryBus, alias=True)
+
+
+def find_query_bus[T]() -> QueryBus[T]:
+    return injection.find_instance(QueryBus)

python_cq-0.1.0.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.1
+Name: python-cq
+Version: 0.1.0
+Summary: Lightweight CQRS library.
+Home-page: https://github.com/100nm/python-cq
+License: MIT
+Keywords: cqrs
+Author: remimd
+Requires-Python: >=3.12,<4
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pydantic (>=2,<3)
+Requires-Dist: python-injection
+Project-URL: Repository, https://github.com/100nm/python-cq
+Description-Content-Type: text/markdown
+
+# python-cq
+
+[![CI](https://github.com/100nm/python-cq/actions/workflows/ci.yml/badge.svg)](https://github.com/100nm/python-cq)
+[![PyPI](https://img.shields.io/pypi/v/python-cq.svg?color=blue)](https://pypi.org/project/python-cq/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Lightweight library for separating Python code according to **Command and Query Responsibility Segregation** principles.
+
+Dependency injection is handled by [python-injection](https://github.com/100nm/python-injection).
+
+Easy to use with [FastAPI](https://github.com/fastapi/fastapi).
+
+## Installation
+
+⚠️ _Requires Python 3.12 or higher_
+
+```bash
+pip install python-cq
+```
+
+## Resources
+
+* [**Writing Application Layer**](https://github.com/100nm/python-cq/tree/prod/documentation/writing-application-layer.md)
+* [**FastAPI Example**](https://github.com/100nm/python-cq/tree/prod/documentation/fastapi-example.md)
+

python_cq-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+cq/__init__.py,sha256=FFTaq-Kq_ywMqWwaucK4MSYPSVbyHizEEYrRwFj3iIU,604
+cq/_core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cq/_core/bus.py,sha256=1P0jHjK1q33GvvB6lo2-IEhK2RP0EZIIy4GyI9YcLVA,4537
+cq/_core/command.py,sha256=dqN99iG4eAD5cXhi0wzWnuWVE9kPhoNE05S-QDGcqHc,476
+cq/_core/dto.py,sha256=jrlTRvG9fXFyv0nb8PQY2WTVPldgGKxg-r2xL6FOT0c,206
+cq/_core/event.py,sha256=9LocJ3QM1MZ4mqx8V1YJT-2lsNulUKix6Epab_u2VmM,424
+cq/_core/middleware.py,sha256=aCTmTcDkTxhmCS2NLenVpMo5QLJmKrEyn6SI6yAuFk8,2117
+cq/_core/query.py,sha256=rpYLviIFoy5uWVPCVsvGdfzHeyc21HSmt1e1KBFEz_A,456
+python_cq-0.1.0.dist-info/METADATA,sha256=Lr4fXKlyW_ULiTq03uYxbDA0rtt59N0oh1pUWkYmu38,2039
+python_cq-0.1.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+python_cq-0.1.0.dist-info/RECORD,,

python_cq-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any