python-cqrs 4.7.2__tar.gz → 4.8.0__tar.gz

{python_cqrs-4.7.2/src/python_cqrs.egg-info → python_cqrs-4.8.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 4.7.2
-Summary: Python CQRS pattern implementation
+Version: 4.8.0
+Summary: Event-Driven Architecture Framework for Distributed Systems
 Author-email: Vadim Kozyrevskiy <vadikko2@mail.ru>, Dmitry Kutlubaev <kutlubaev00@mail.ru>
 Maintainer-email: Vadim Kozyrevskiy <vadikko2@mail.ru>
 Project-URL: Documentation, https://mkdocs.python-cqrs.dev/
@@ -17,14 +17,14 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: dataclass-wizard==0.*
-Requires-Dist: di[anyio]==0.79.2
-Requires-Dist: dependency-injector>=4.48.2
+Requires-Dist: di[anyio]==0.*
+Requires-Dist: dependency-injector>=4.0
 Requires-Dist: orjson==3.*
 Requires-Dist: pydantic==2.*
-Requires-Dist: python-dotenv==1.0.1
-Requires-Dist: retry-async==0.1.4
+Requires-Dist: python-dotenv==1.*
+Requires-Dist: retry-async==0.1.*
 Requires-Dist: sqlalchemy[asyncio]==2.0.*
-Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: typing-extensions>=4.0
 Provides-Extra: aiobreaker
 Requires-Dist: aiobreaker>=0.3.0; extra == "aiobreaker"
 Provides-Extra: dev
@@ -51,10 +51,9 @@ Requires-Dist: faststream[kafka]==0.5.28; extra == "examples"
 Requires-Dist: faker>=37.12.0; extra == "examples"
 Requires-Dist: uvicorn==0.32.0; extra == "examples"
 Requires-Dist: aiohttp==3.13.2; extra == "examples"
+Requires-Dist: protobuf>=4.25.8; extra == "examples"
 Provides-Extra: kafka
 Requires-Dist: aiokafka==0.10.0; extra == "kafka"
-Provides-Extra: protobuf
-Requires-Dist: protobuf==4.25.5; extra == "protobuf"
 Provides-Extra: rabbit
 Requires-Dist: aio-pika==9.3.0; extra == "rabbit"
 Dynamic: license-file

{python_cqrs-4.7.2 → python_cqrs-4.8.0}/pyproject.toml

@@ -17,21 +17,21 @@ classifiers = [
 ]
 dependencies = [
   "dataclass-wizard==0.*",
-  "di[anyio]==0.79.2",
-  "dependency-injector>=4.48.2",
+  "di[anyio]==0.*",
+  "dependency-injector>=4.0",
   "orjson==3.*",
   "pydantic==2.*",
-  "python-dotenv==1.0.1",
-  "retry-async==0.1.4",
+  "python-dotenv==1.*",
+  "retry-async==0.1.*",
   "sqlalchemy[asyncio]==2.0.*",
-  "typing-extensions>=4.0.0"
+  "typing-extensions>=4.0"
 ]
-description = "Python CQRS pattern implementation"
+description = "Event-Driven Architecture Framework for Distributed Systems"
 maintainers = [{name = "Vadim Kozyrevskiy", email = "vadikko2@mail.ru"}]
 name = "python-cqrs"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "4.7.2"
+version = "4.8.0"
 
 [project.optional-dependencies]
 aiobreaker = ["aiobreaker>=0.3.0"]
@@ -62,10 +62,10 @@ examples = [
   "faststream[kafka]==0.5.28",
   "faker>=37.12.0",
   "uvicorn==0.32.0",
-  "aiohttp==3.13.2"
+  "aiohttp==3.13.2",
+  "protobuf>=4.25.8",
 ]
 kafka = ["aiokafka==0.10.0"]
-protobuf = ["protobuf==4.25.5"]
 rabbit = ["aio-pika==9.3.0"]
 
 [project.urls]
@@ -79,8 +79,5 @@ asyncio_mode = "auto"
 junit_family = "xunit1"
 testpaths = ["tests"]
 
-[tool.ruff]
-target-version = "py310"
-
 [tool.setuptools.packages.find]
 where = ["src"]

{python_cqrs-4.7.2 → python_cqrs-4.8.0}/src/cqrs/dispatcher/event.py

@@ -27,9 +27,11 @@ class EventDispatcher:
         self,
         event: IEvent,
         handle_type: typing.Type[_EventHandler],
-    ):
+    ) -> None:
         handler: _EventHandler = await self._container.resolve(handle_type)
         await handler.handle(event)
+        for follow_up in handler.events:
+            await self.dispatch(follow_up)
 
     async def dispatch(self, event: IEvent) -> None:
         handler_types = self._event_map.get(type(event), [])
@@ -38,5 +40,6 @@ class EventDispatcher:
                 "Handlers for event %s not found",
                 type(event).__name__,
             )
+            return
         for h_type in handler_types:
             await self._handle_event(event, h_type)

{python_cqrs-4.7.2 → python_cqrs-4.8.0}/src/cqrs/dispatcher/saga.py

@@ -53,7 +53,7 @@ class SagaDispatcher:
         self._compensation_retry_delay = compensation_retry_delay
         self._compensation_retry_backoff = compensation_retry_backoff
 
-    async def dispatch(
+    def dispatch(
         self,
         context: SagaContext,
         saga_id: uuid.UUID | None = None,
@@ -61,6 +61,7 @@ class SagaDispatcher:
         """
         Dispatch a saga execution for the given context.
 
+        Called without await; returns an AsyncIterator consumed with async for.
         Yields result after each step execution. After each yield, events are collected
         and included in the dispatch result.
 
@@ -75,6 +76,13 @@ class SagaDispatcher:
         Raises:
             SagaDoesNotExist: If no saga is registered for the context type
         """
+        return self._dispatch_impl(context, saga_id=saga_id)
+
+    async def _dispatch_impl(
+        self,
+        context: SagaContext,
+        saga_id: uuid.UUID | None = None,
+    ) -> typing.AsyncIterator[SagaDispatchResult]:
         # Find saga type by context type
         saga_type = self._saga_map.get(type(context))
         if not saga_type:

{python_cqrs-4.7.2 → python_cqrs-4.8.0}/src/cqrs/dispatcher/streaming.py

@@ -28,16 +28,23 @@ class StreamingRequestDispatcher:
         self._container = container
         self._middleware_chain = middleware_chain or MiddlewareChain()
 
-    async def dispatch(
+    def dispatch(
         self,
         request: IRequest,
     ) -> typing.AsyncIterator[RequestDispatchResult]:
         """
         Dispatch a request to a streaming handler and yield results.
 
+        Called without await; returns an AsyncIterator consumed with async for.
         After each yield from the handler, events are collected and included
         in the dispatch result. The generator continues until StopIteration.
         """
+        return self._dispatch_impl(request)
+
+    async def _dispatch_impl(
+        self,
+        request: IRequest,
+    ) -> typing.AsyncIterator[RequestDispatchResult]:
         handler_type = self._request_map.get(type(request), None)
         if handler_type is None:
             raise RequestHandlerDoesNotExist(
@@ -62,9 +69,7 @@ class StreamingRequestDispatcher:
 
         if not inspect.isasyncgenfunction(handler.handle):
             handler_name = (
-                handler_type_typed.__name__
-                if hasattr(handler_type_typed, "__name__")
-                else str(handler_type_typed)
+                handler_type_typed.__name__ if hasattr(handler_type_typed, "__name__") else str(handler_type_typed)
             )
             raise TypeError(
                 f"Handler {handler_name}.handle must be an async generator function",

{python_cqrs-4.7.2 → python_cqrs-4.8.0}/src/cqrs/events/__init__.py

@@ -1,3 +1,15 @@
+"""Event types, handlers, emitter, and event map for the CQRS events layer.
+
+Public API:
+- Event types: :class:`Event`, :class:`DomainEvent`, :class:`NotificationEvent`,
+  and their interfaces/base classes.
+- :class:`EventHandler` — handler interface; implement :meth:`EventHandler.handle`
+  and optionally :attr:`EventHandler.events` for follow-up events.
+- :class:`EventEmitter` — sends domain events to handlers and notification events
+  to a message broker.
+- :class:`EventMap` — registry of event type -> handler types; use :meth:`EventMap.bind`.
+"""
+
 from cqrs.events.event import (
     DCEvent,
     DCDomainEvent,

{python_cqrs-4.7.2 → python_cqrs-4.8.0}/src/cqrs/events/bootstrap.py

@@ -31,6 +31,31 @@ def setup_mediator(
     middlewares: typing.Iterable[mediator_middlewares.Middleware],
     events_mapper: typing.Callable[[events.EventMap], None] | None = None,
 ) -> cqrs.EventMediator:
+    """
+    Create an event mediator with the given container and middlewares.
+
+    Args:
+        container: DI container (e.g. :class:`cqrs.container.di.DIContainer`) or
+            any implementation of :class:`cqrs.container.protocol.Container`.
+        middlewares: Middleware chain for the mediator (e.g. logging).
+        events_mapper: Optional callable that receives an :class:`~cqrs.events.map.EventMap`
+            and binds event types to handler types via :meth:`~cqrs.events.map.EventMap.bind`.
+
+    Returns:
+        Configured :class:`cqrs.EventMediator` instance.
+
+    Example::
+
+        def bind_events(event_map: events.EventMap) -> None:
+            event_map.bind(OrderCreatedEvent, OrderCreatedEventHandler)
+
+        mediator = setup_mediator(
+            container=di_container,
+            middlewares=[logging_middleware.LoggingMiddleware()],
+            events_mapper=bind_events,
+        )
+        await mediator.emit(OrderCreatedEvent(order_id="1"))
+    """
     _events_mapper = events.EventMap()
     if events_mapper is not None:
         events_mapper(_events_mapper)
@@ -71,6 +96,34 @@ def bootstrap(
     events_mapper: typing.Callable[[events.EventMap], None] | None = None,
     on_startup: typing.List[typing.Callable[[], None]] | None = None,
 ) -> cqrs.EventMediator:
+    """
+    Bootstrap an event mediator with optional middlewares and event bindings.
+
+    If ``di_container`` is a :class:`di.Container`, it is wrapped in
+    :class:`cqrs.container.di.DIContainer`. Logging middleware is appended
+    to the middleware list. Runs all ``on_startup`` callables before setup.
+
+    Args:
+        di_container: DI container from the ``di`` package or a CQRS container.
+        middlewares: Optional list of middlewares (e.g. logging, metrics).
+        events_mapper: Optional callable that receives an :class:`~cqrs.events.map.EventMap`
+            and binds event types to handler types.
+        on_startup: Optional list of callables to run before creating the mediator.
+
+    Returns:
+        Configured :class:`cqrs.EventMediator` with logging middleware enabled.
+
+    Example::
+
+        def bind_events(event_map: events.EventMap) -> None:
+            event_map.bind(OrderCreatedEvent, OrderCreatedEventHandler)
+
+        mediator = bootstrap(
+            di_container=di.Container(),
+            events_mapper=bind_events,
+        )
+        await mediator.emit(OrderCreatedEvent(order_id="1"))
+    """
     if on_startup is None:
         on_startup = []
 
@@ -90,8 +143,10 @@ def bootstrap(
     middlewares_list: typing.List[mediator_middlewares.Middleware] = list(
         middlewares or [],
     )
+    if not any(isinstance(m, logging_middleware.LoggingMiddleware) for m in middlewares_list):
+        middlewares_list.append(logging_middleware.LoggingMiddleware())
     return setup_mediator(
         container,
         events_mapper=events_mapper,
-        middlewares=middlewares_list + [logging_middleware.LoggingMiddleware()],
+        middlewares=middlewares_list,
     )

{python_cqrs-4.7.2 → python_cqrs-4.8.0}/src/cqrs/events/event.py

@@ -1,14 +1,14 @@
 import abc
 import dataclasses
-from dataclass_wizard import fromdict, asdict
 import datetime
 import os
+import sys
 import typing
 import uuid
-import sys
 
 import dotenv
 import pydantic
+from dataclass_wizard import asdict, fromdict
 
 if sys.version_info >= (3, 11):
     from typing import Self  # novm
@@ -251,6 +251,9 @@ class INotificationEvent(IEvent, typing.Generic[PayloadT]):
 
         def proto(self) -> typing.Any: ...  # Method for protobuf representation
 
+        @classmethod
+        def from_proto(cls, proto: typing.Any) -> Self: ...
+
 
 @dataclasses.dataclass(frozen=True)
 class DCNotificationEvent(
@@ -300,7 +303,18 @@ class DCNotificationEvent(
             NotImplementedError: This method must be implemented by subclasses
                 that need protobuf serialization.
         """
-        raise NotImplementedError("Method not implemented for dataclass events")
+        raise NotImplementedError("Method not implemented")
+
+    @classmethod
+    def from_proto(cls, proto: typing.Any) -> Self:
+        """
+        Constructs event from proto event object
+
+        Raises:
+            NotImplementedError: This method must be implemented by subclasses
+                that need protobuf deserialization.
+        """
+        raise NotImplementedError("Method not implemented")
 
     def __hash__(self) -> int:
         """
@@ -345,10 +359,34 @@ class PydanticNotificationEvent(
 
     model_config = pydantic.ConfigDict(from_attributes=True)
 
-    def proto(self):
+    def proto(self) -> typing.Any:
+        """
+        Return protobuf representation of the event.
+
+        Raises:
+            NotImplementedError: This method must be implemented by subclasses
+                that need protobuf serialization.
+        """
         raise NotImplementedError("Method not implemented")
 
-    def __hash__(self):
+    @classmethod
+    def from_proto(cls, proto: typing.Any) -> Self:
+        """
+        Constructs event from proto event object
+
+        Raises:
+            NotImplementedError: This method must be implemented by subclasses
+                that need protobuf deserialization.
+        """
+        raise NotImplementedError("Method not implemented")
+
+    def __hash__(self) -> int:
+        """
+        Return the hash of the event based on its event_id.
+
+        Returns:
+            Hash value of the event_id.
+        """
         return hash(self.event_id)
 
 

python_cqrs-4.8.0/src/cqrs/events/event_emitter.py

@@ -0,0 +1,142 @@
+import functools
+import logging
+import typing
+
+from cqrs import container as di_container, message_brokers
+from cqrs.events.event import IDomainEvent, IEvent, INotificationEvent
+from cqrs.events import event_handler, map
+
+logger = logging.getLogger("cqrs")
+
+_H: typing.TypeAlias = event_handler.EventHandler
+
+
+class EventEmitter:
+    """
+    Sends events to registered handlers or to a message broker.
+
+    For :class:`~cqrs.events.event.IDomainEvent`: resolves handlers from the
+    container, runs :meth:`~cqrs.events.event_handler.EventHandler.handle`, and
+    returns follow-up events from :attr:`~cqrs.events.event_handler.EventHandler.events`.
+    For :class:`~cqrs.events.event.INotificationEvent`: sends the event to the
+    message broker (if configured) and returns an empty sequence.
+    """
+
+    def __init__(
+        self,
+        event_map: map.EventMap,
+        container: di_container.Container,
+        message_broker: message_brokers.MessageBroker | None = None,
+    ) -> None:
+        """
+        Initialize the event emitter.
+
+        Args:
+            event_map: Map of event types to handler types (used for domain events).
+            container: DI container to resolve handler instances.
+            message_broker: Optional broker for notification events; required
+                when emitting :class:`~cqrs.events.event.INotificationEvent`.
+
+        Example::
+
+            event_map = EventMap()
+            event_map.bind(OrderCreatedEvent, OrderCreatedEventHandler)
+            emitter = EventEmitter(
+                event_map=event_map,
+                container=di_container,
+                message_broker=kafka_broker,
+            )
+            follow_ups = await emitter.emit(OrderCreatedEvent(order_id="1"))
+        """
+        self._event_map = event_map
+        self._container = container
+        self._message_broker = message_broker
+
+    @functools.singledispatchmethod
+    async def emit(self, event: IEvent) -> typing.Sequence[IEvent]:
+        """
+        Emit an event and return follow-up events from handlers.
+
+        For unknown event types returns an empty sequence. For domain events
+        invokes all registered handlers and collects events from
+        :attr:`~cqrs.events.event_handler.EventHandler.events`. For notification
+        events sends to the message broker.
+
+        Args:
+            event: The event to emit (domain or notification).
+
+        Returns:
+            Follow-up events returned by domain event handlers; empty for
+            notification events or when no handlers are registered.
+
+        Example::
+
+            follow_ups = await emitter.emit(OrderCreatedEvent(order_id="1"))
+            for e in follow_ups:
+                await emitter.emit(e)  # or process via EventProcessor
+        """
+        return ()
+
+    async def _send_to_broker(
+        self,
+        event: INotificationEvent,
+    ) -> None:
+        """
+        Send a notification event to the message broker.
+
+        Args:
+            event: Notification event to send.
+
+        Raises:
+            RuntimeError: If no message broker was configured.
+        """
+        if not self._message_broker:
+            raise RuntimeError(
+                f"To send event {event}, message broker must be specified.",
+            )
+
+        message = message_brokers.Message(
+            message_name=type(event).__name__,
+            message_id=event.event_id,
+            topic=event.topic,
+            payload=event.to_dict(),
+        )
+
+        logger.debug(
+            "Sending Event(%s) to message broker %s",
+            event.event_id,
+            type(self._message_broker).__name__,
+        )
+
+        await self._message_broker.send_message(message)
+
+    @emit.register(IDomainEvent)
+    async def _(self, event: IDomainEvent) -> typing.Sequence[IEvent]:
+        """Emit domain event: run all registered handlers and return their follow-up events."""
+        handlers_types = self._event_map.get(type(event), [])
+        if not handlers_types:
+            logger.warning(
+                "Handlers for domain event %s not found",
+                type(event).__name__,
+            )
+            return ()
+        follow_ups: list[IEvent] = []
+        for handler_type in handlers_types:
+            handler: _H = await self._container.resolve(
+                handler_type,
+            )
+            logger.debug(
+                "Handling Event(%s) via event handler(%s)",
+                type(event).__name__,
+                handler_type.__name__,
+            )
+            await handler.handle(event)
+            # Snapshot follow-ups so shared handlers don't expose stale state
+            follow_ups.extend(list(handler.events))
+        return follow_ups
+
+    @emit.register(INotificationEvent)
+    async def _(self, event: INotificationEvent) -> typing.Sequence[IEvent]:
+        """Emit notification event: send to message broker; no follow-ups."""
+        await self._send_to_broker(event)
+        return ()

python_cqrs-4.8.0/src/cqrs/events/event_handler.py

@@ -0,0 +1,59 @@
+import abc
+from collections.abc import Sequence
+import typing
+
+from cqrs.events.event import IEvent
+
+E = typing.TypeVar("E", bound=IEvent, contravariant=True)
+
+
+class EventHandler(abc.ABC, typing.Generic[E]):
+    """
+    The event handler interface.
+
+    Subclasses must implement :meth:`handle`. Optionally override :attr:`events`
+    to return follow-up events emitted after handling (e.g. for multi-level
+    event chains).
+
+    Example::
+
+        class UserJoinedEvent(DomainEvent):
+            meeting_id: str
+            user_id: str
+
+        class UserJoinedEventHandler(EventHandler[UserJoinedEvent]):
+            def __init__(self, meetings_api: MeetingAPIProtocol) -> None:
+                self._meetings_api = meetings_api
+
+            async def handle(self, event: UserJoinedEvent) -> None:
+                await self._meetings_api.notify_room(
+                    event.meeting_id, "New user joined!"
+                )
+    """
+
+    @property
+    def events(self) -> Sequence[IEvent]:
+        """
+        Events produced by this handler after :meth:`handle` was called.
+
+        Override in subclasses to return follow-up events that should be
+        processed by the same pipeline (e.g. domain events to emit). By default
+        returns an empty sequence.
+
+        Returns:
+            Sequence of follow-up events (e.g. new domain events) to process.
+        """
+        return ()
+
+    @abc.abstractmethod
+    async def handle(self, event: E) -> None:
+        """
+        Handle the given event.
+
+        Args:
+            event: The event instance to handle.
+
+        Raises:
+            NotImplementedError: Must be implemented by subclasses.
+        """
+        raise NotImplementedError