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

{python_cqrs-4.7.3/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.3
-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.3 → 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.3"
+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]

{python_cqrs-4.7.3 → 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.3 → 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.3 → 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.3 → 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

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

@@ -0,0 +1,143 @@
+import asyncio
+import typing
+from collections import deque
+
+from cqrs.events.event import IEvent
+from cqrs.events.event_emitter import EventEmitter
+from cqrs.events.map import EventMap
+
+
+class EventProcessor:
+    """
+    Processes events in parallel or sequentially via an event emitter.
+
+    Emits events through the configured :class:`~cqrs.events.event_emitter.EventEmitter`.
+    Follow-up events returned by handlers (via :attr:`~cqrs.events.event_handler.EventHandler.events`)
+    are processed in the same pipeline: BFS in sequential mode, under the same
+    semaphore in parallel mode. Can be reused across different mediators.
+
+    Example::
+
+        event_map = EventMap()
+        event_map.bind(OrderCreatedEvent, OrderCreatedEventHandler)
+        emitter = EventEmitter(event_map=event_map, container=container)
+        processor = EventProcessor(
+            event_map=event_map,
+            event_emitter=emitter,
+            max_concurrent_event_handlers=4,
+            concurrent_event_handle_enable=True,
+        )
+        await processor.emit_events([OrderCreatedEvent(order_id="1")])
+    """
+
+    def __init__(
+        self,
+        event_map: EventMap,
+        event_emitter: EventEmitter | None = None,
+        max_concurrent_event_handlers: int = 1,
+        concurrent_event_handle_enable: bool = True,
+    ) -> None:
+        """
+        Initialize the event processor.
+
+        Args:
+            event_map: Map of event types to handler types.
+            event_emitter: Emitter used to publish events; if None, :meth:`emit_events`
+                is a no-op.
+            max_concurrent_event_handlers: Semaphore limit for parallel mode.
+            concurrent_event_handle_enable: If True, process events in parallel
+                (with semaphore); if False, process sequentially (BFS over events
+                and follow-ups).
+        """
+        self._event_emitter = event_emitter
+        self._event_map = event_map
+        self._max_concurrent_event_handlers = max_concurrent_event_handlers
+        self._concurrent_event_handle_enable = concurrent_event_handle_enable
+        self._event_semaphore = asyncio.Semaphore(max_concurrent_event_handlers)
+
+    async def emit_events(self, events: typing.Sequence[IEvent]) -> None:
+        """
+        Emit all events and process follow-ups in the same pipeline.
+
+        In sequential mode, events and follow-ups are processed in BFS order.
+        In parallel mode, events are processed under the same semaphore limit;
+        as soon as any event completes, its follow-ups are queued and started
+        (FIRST_COMPLETED), without waiting for siblings. Returns when all work
+        is finished.
+
+        Args:
+            events: Events to emit (e.g. domain events). Handlers may return
+                follow-up events via :attr:`~cqrs.events.event_handler.EventHandler.events`.
+
+        Example::
+
+            await processor.emit_events([
+                OrderCreatedEvent(order_id="1"),
+                OrderCreatedEvent(order_id="2"),
+            ])
+        """
+        if not events:
+            return
+
+        if not self._event_emitter:
+            return
+
+        if not self._concurrent_event_handle_enable:
+            # Process events sequentially (BFS: follow-ups re-queued, O(1) popleft)
+            to_process: deque[IEvent] = deque(events)
+            while to_process:
+                event = to_process.popleft()
+                follow_ups = await self._event_emitter.emit(event)
+                to_process.extend(follow_ups)
+        else:
+            # Process events in parallel: start follow-ups as soon as any task completes
+            # (FIRST_COMPLETED), all under the same semaphore
+            await self._emit_events_parallel_first_completed(deque(events))
+
+    async def _emit_one_event(self, event: IEvent) -> typing.Sequence[IEvent]:
+        """
+        Emit one event under the semaphore. Returns follow-up events from the handler.
+
+        Args:
+            event: The event to emit.
+
+        Returns:
+            Follow-up events to process next, or empty sequence.
+        """
+        if not self._event_emitter:
+            return ()
+        async with self._event_semaphore:
+            follow_ups = await self._event_emitter.emit(event)
+        if follow_ups is None:
+            return ()
+        return follow_ups
+
+    async def _emit_events_parallel_first_completed(
+        self,
+        initial_events: deque[IEvent],
+    ) -> None:
+        """
+        Process events in parallel under the semaphore; as soon as any task completes,
+        its follow-up events are queued and started, without waiting for siblings.
+        Uses deque for O(1) popleft when taking the next event.
+        """
+        pending_events: deque[IEvent] = initial_events
+        running_tasks: set[asyncio.Task[typing.Sequence[IEvent]]] = set()
+
+        while pending_events or running_tasks:
+            # Start a task for each pending event (semaphore limits concurrency)
+            while pending_events:
+                event = pending_events.popleft()
+                task = asyncio.create_task(self._emit_one_event(event))
+                running_tasks.add(task)
+
+            if not running_tasks:
+                break
+
+            done, running_tasks = await asyncio.wait(
+                running_tasks,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            for task in done:
+                follow_ups = task.result()
+                pending_events.extend(follow_ups)