python-cqrs 0.2.0__tar.gz → 2.0.0__tar.gz

{python_cqrs-0.2.0 → python_cqrs-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-cqrs
-Version: 0.2.0
+Version: 2.0.0
 Summary: Python CQRS pattern implementation
 Author-email: Vadim Kozyrevskiy <vadikko2@mail.ru>
 Maintainer-email: Vadim Kozyrevskiy <vadikko2@mail.ru>
@@ -21,6 +21,7 @@ Requires-Dist: aio-pika==9.3.0
 Requires-Dist: di[anyio]==0.79.2
 Requires-Dist: sqlalchemy[asyncio]==2.0.*
 Requires-Dist: retry-async==0.1.4
+Requires-Dist: python-dotenv==1.0.1
 Provides-Extra: dev
 Requires-Dist: pre-commit==3.8.0; extra == "dev"
 Requires-Dist: pyright==1.1.377; extra == "dev"
@@ -29,28 +30,39 @@ Requires-Dist: aiokafka==0.10.0; extra == "dev"
 Requires-Dist: pytest~=7.4.2; extra == "dev"
 Requires-Dist: pytest-asyncio~=0.21.1; extra == "dev"
 Requires-Dist: pytest-env==0.6.2; extra == "dev"
-Requires-Dist: python-dotenv==1.0.1; extra == "dev"
 Requires-Dist: cryptography==42.0.2; extra == "dev"
 Requires-Dist: asyncmy==0.2.9; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: fastapi==0.109.*; extra == "examples"
+Requires-Dist: uvicorn==0.32.0; extra == "examples"
+Requires-Dist: faststream[kafka]==0.5.28; extra == "examples"
 Provides-Extra: kafka
 Requires-Dist: aiokafka==0.10.0; extra == "kafka"
+Requires-Dist: confluent-kafka==2.6.0; extra == "kafka"
+Provides-Extra: protobuf
+Requires-Dist: protobuf==5.0; extra == "protobuf"
 
-# Python CQRS pattern implementaion with Transaction Outbox supporting
+# Python CQRS pattern implementation with Transaction Outbox supporting
 
 ## Overview
 
 This is a package for implementing the CQRS (Command Query Responsibility Segregation) pattern in Python applications.
-It provides a set of abstractions and utilities to help separate read and write use cases, ensuring better scalability, performance, and maintainability of the application.
+It provides a set of abstractions and utilities to help separate read and write use cases, ensuring better scalability,
+performance, and maintainability of the application.
 
-This package is a fork of the [diator](https://github.com/akhundMurad/diator) project ([documentation](https://akhundmurad.github.io/diator/)) with several enhancements:
+This package is a fork of the [diator](https://github.com/akhundMurad/diator)
+project ([documentation](https://akhundmurad.github.io/diator/)) with several enhancements:
 
 1. Support for Pydantic [v2.*](https://docs.pydantic.dev/2.8/);
 2. `Kafka` support using [aiokafka](https://github.com/aio-libs/aiokafka);
 3. Added `EventMediator` for handling `Notification` and `ECST` events coming from the bus;
 4. Redesigned the event and request mapping mechanism to handlers;
 5. Added `bootstrap` for easy setup;
-6. Added support for [Transaction Outbox](https://microservices.io/patterns/data/transactional-outbox.html), ensuring that `Notification` and `ECST` events are sent to the broker.
-
+6. Added support for [Transaction Outbox](https://microservices.io/patterns/data/transactional-outbox.html), ensuring
+   that `Notification` and `ECST` events are sent to the broker;
+7. FastAPI supporting;
+8. FastStream supporting;
+9. [Protobuf](https://protobuf.dev/) events supporting.
 
 ## Request Handlers
 
@@ -58,7 +70,8 @@ Request handlers can be divided into two main types:
 
 ### Command Handler
 
-Command Handler executes the received command. The logic of the handler may include, for example, modifying the state of the domain model.
+Command Handler executes the received command. The logic of the handler may include, for example, modifying the state of
+the domain model.
 As a result of executing the command, an event may be produced to the broker.
 > [!TIP]
 > By default, the command handler does not return any result, but it is not mandatory.
@@ -96,9 +109,13 @@ class SyncJoinMeetingCommandHandler(SyncRequestHandler[JoinMeetingCommand, None]
           ...
 ```
 
+A complete example can be found in
+the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/request_handler.py)
+
 ### Query handler
 
-Query Handler returns a representation of the requested data, for example, from the [read model](https://radekmaziarka.pl/2018/01/08/cqrs-third-step-simple-read-model/#simple-read-model---to-the-rescue).
+Query Handler returns a representation of the requested data, for example, from
+the [read model](https://radekmaziarka.pl/2018/01/08/cqrs-third-step-simple-read-model/#simple-read-model---to-the-rescue).
 > [!TIP]
 > The read model can be constructed based on domain events produced by the `Command Handler`.
 
@@ -122,6 +139,8 @@ class ReadMeetingQueryHandler(RequestHandler[ReadMeetingQuery, ReadMeetingQueryR
 
 ```
 
+A complete example can be found in
+the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/request_handler.py)
 
 ## Event Handlers
 
@@ -130,59 +149,81 @@ To configure event handling, you need to implement a broker consumer on the side
 Below is an example of `Kafka event consuming` that can be used in the Presentation Layer.
 
 ```python
-from cqrs.events import EventHandler, SyncEventHandler
-
-class UserJoinedEventHandler(EventHandler[UserJoinedEventHandler]):
+class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
+    def __init__(self):
+        self._events = []
 
-    def __init__(self, meetings_api: MeetingAPIProtocol) -> None:
-      self._meetings_api = meetings_api
-
-    async def handle(self, event: UserJoinedEventHandler) -> None:
-      await self._meetings_api.notify_room(event.meeting_id, "New user joined!")
+    @property
+    def events(self):
+        return self._events
 
-class SyncUserJoinedEventHandler(SyncEventHandler[UserJoinedEventHandler]):
+    async def handle(self, request: JoinMeetingCommand) -> None:
+        STORAGE[request.meeting_id].append(request.user_id)
+        self._events.append(
+            UserJoined(user_id=request.user_id, meeting_id=request.meeting_id),
+        )
+        print(f"User {request.user_id} joined meeting {request.meeting_id}")
 
-    def __init__(self, meetings_api: MeetingAPIProtocol) -> None:
-      self._meetings_api = meetings_api
 
-    def handle(self, event: UserJoinedEventHandler) -> None:
-      # do some sync logic
-      ...
+class UserJoinedEventHandler(cqrs.EventHandler[UserJoined]):
+    async def handle(self, event: UserJoined) -> None:
+        print(f"Handle user {event.user_id} joined meeting {event.meeting_id} event")
 ```
 
+A complete example can be found in
+the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/domain_event_handler.py)
+
 ## Producing Notification/ECST Events
 
-During the handling of a command event, messages of type `cqrs.NotificationEvent` or `cqrs.ECSTEvent` may be generated and then sent to the broker.
+During the handling of a command event, messages of type `cqrs.NotificationEvent` or `cqrs.ECSTEvent` may be generated
+and then sent to the broker.
 
 ```python
-class CloseMeetingRoomCommandHandler(requests.RequestHandler[CloseMeetingRoomCommand, None]):
-
-    def __init__(self) -> None:
-        self._events: typing.List[events.Event] = []
+class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
+    def __init__(self):
+        self._events = []
 
     @property
-    def events(self) -> typing.List[events.Event]:
+    def events(self):
         return self._events
 
-    async def handle(self, request: CloseMeetingRoomCommand) -> None:
-        # some process
-        event = events.NotificationEvent(
-            event_topic="meeting_room_notifications",
-            event_name="meeteng_room_closed",
-            payload=dict(
-                meeting_room_id=request.meeting_room_id,
-            ),
+    async def handle(self, request: JoinMeetingCommand) -> None:
+        print(f"User {request.user_id} joined meeting {request.meeting_id}")
+        self._events.append(
+            cqrs.NotificationEvent[UserJoinedNotificationPayload](
+                event_name="UserJoined",
+                topic="user_notification_events",
+                payload=UserJoinedNotificationPayload(
+                    user_id=request.user_id,
+                    meeting_id=request.meeting_id,
+                ),
+            )
+        )
+        self._events.append(
+            cqrs.ECSTEvent[UserJoinedECSTPayload](
+                event_name="UserJoined",
+                topic="user_ecst_events",
+                payload=UserJoinedECSTPayload(
+                    user_id=request.user_id,
+                    meeting_id=request.meeting_id,
+                ),
+            )
         )
-        self._events.append(event)
 ```
 
+A complete example can be found in
+the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/event_producing.py)
+
 After processing the command/request, if there are any Notification/ECST events,
 the EventEmitter is invoked to produce the events via the message broker.
 
 > [!WARNING]
-> It is important to note that producing events using the events property parameter does not guarantee message delivery to the broker.
-> In the event of broker unavailability or an exception occurring during message formation or sending, the message may be lost.
-> This issue can potentially be addressed by configuring retry attempts for sending messages to the broker, but we recommend using the [Transaction Outbox](https://microservices.io/patterns/data/transactional-outbox.html) pattern,
+> It is important to note that producing events using the events property parameter does not guarantee message delivery
+> to the broker.
+> In the event of broker unavailability or an exception occurring during message formation or sending, the message may
+> be lost.
+> This issue can potentially be addressed by configuring retry attempts for sending messages to the broker, but we
+> recommend using the [Transaction Outbox](https://microservices.io/patterns/data/transactional-outbox.html) pattern,
 > which is implemented in the current version of the python-cqrs package for this purpose.
 
 ## Kafka broker
@@ -202,13 +243,10 @@ await broker.send_message(...)
 
 ## Transactional Outbox
 
-The package implements the [Transactional Outbox](https://microservices.io/patterns/data/transactional-outbox.html) pattern, which ensures that messages are produced to the broker according to the at-least-once semantics.
-
+The package implements the [Transactional Outbox](https://microservices.io/patterns/data/transactional-outbox.html)
+pattern, which ensures that messages are produced to the broker according to the at-least-once semantics.
 
 ```python
-from sqlalchemy.ext.asyncio import session as sql_session
-from cqrs import events
-
 def do_some_logic(meeting_room_id: int, session: sql_session.AsyncSession):
     """
     Make changes to the database
@@ -216,33 +254,59 @@ def do_some_logic(meeting_room_id: int, session: sql_session.AsyncSession):
     session.add(...)
 
 
-class CloseMeetingRoomCommandHandler(requests.RequestHandler[CloseMeetingRoomCommand, None]):
-
-    def __init__(self, repository: cqrs.SqlAlchemyOutboxedEventRepository):
-        self._repository = repository
-        self._events: typing.List[events.Event] = []
+class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
+    def __init__(self, outbox: cqrs.OutboxedEventRepository):
+        self.outbox = outbox
 
     @property
     def events(self):
-        return self._events
-
-    async def handle(self, request: CloseMeetingRoomCommand) -> None:
-        async with self._repository as session:
-           do_some_logic(request.meeting_room_id, session)
-           self.repository.add(
-               session,
-               events.ECSTEvent(
-                  event_name="MeetingRoomClosed",
-                  payload=dict(message="foo"),
-              ),
-           )
-           await self.repository.commit(session)
+        return []
+
+    async def handle(self, request: JoinMeetingCommand) -> None:
+        print(f"User {request.user_id} joined meeting {request.meeting_id}")
+        async with self.outbox as session:
+            do_some_logic(request.meeting_id, session) # business logic
+            self.outbox.add(
+                session,
+                cqrs.NotificationEvent[UserJoinedNotificationPayload](
+                    event_name="UserJoined",
+                    topic="user_notification_events",
+                    payload=UserJoinedNotificationPayload(
+                        user_id=request.user_id,
+                        meeting_id=request.meeting_id,
+                    ),
+                ),
+            )
+            self.outbox.add(
+                session,
+                cqrs.ECSTEvent[UserJoinedECSTPayload](
+                    event_name="UserJoined",
+                    topic="user_ecst_events",
+                    payload=UserJoinedECSTPayload(
+                        user_id=request.user_id,
+                        meeting_id=request.meeting_id,
+                    ),
+                ),
+            )
+            await self.outbox.commit(session)
 ```
 
+A complete example can be found in
+the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/save_events_into_outbox.py)
+
+> [!TIP]
+> You can specify the name of the Outbox table using the environment variable `OUTBOX_SQLA_TABLE`.
+> By default, it is set to `outbox`.
+
+> [!TIP]
+> If you use the protobuf events you should specify `OutboxedEventRepository`
+> by [protobuf serialize](https://github.com/vadikko2/cqrs/blob/master/src/cqrs/serializers/protobuf.py). A complete example can be found in
+the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/save_proto_events_into_outbox.py)
 
 ## Producing Events from Outbox to Kafka
 
-As an implementation of the Transactional Outbox pattern, the SqlAlchemyOutboxedEventRepository is available for use as an access repository to the Outbox storage.
+As an implementation of the Transactional Outbox pattern, the SqlAlchemyOutboxedEventRepository is available for use as
+an access repository to the Outbox storage.
 It can be utilized in conjunction with the KafkaMessageBroker.
 
 ```python
@@ -257,12 +321,8 @@ session_factory = async_sessionmaker(
     )
 )
 
-broker = kafka_broker.KafkaMessageBroker(
-    kafka_adapter.kafka_producer_factory(
-        dsn="localhost:9094",
-        topics=["test.topic1", "test.topic2"],
-    ),
-    "DEBUG"
+broker = kafka.KafkaMessageBroker(
+  producer=kafka_adapters.kafka_producer_factory(dsn="localhost:9092"),
 )
 
 producer = cqrs.EventProducer(cqrs.SqlAlchemyOutboxedEventRepository(session_factory, zlib.ZlibCompressor()), broker)
@@ -270,20 +330,25 @@ loop = asyncio.get_event_loop()
 loop.run_until_complete(app.periodically_task())
 ```
 
+A complete example can be found in
+the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/kafka_outboxed_event_producing.py)
 
 ## Transaction log tailing
 
-If the Outbox polling strategy does not suit your needs, I recommend exploring the [Transaction Log Tailing](https://microservices.io/patterns/data/transaction-log-tailing.html) pattern.
+If the Outbox polling strategy does not suit your needs, I recommend exploring
+the [Transaction Log Tailing](https://microservices.io/patterns/data/transaction-log-tailing.html) pattern.
 The current version of the python-cqrs package does not support the implementation of this pattern.
 
 > [!TIP]
-> However, it can be implemented using [Debezium + Kafka Connect](https://debezium.io/documentation/reference/stable/architecture.html),
-> which allows you to produce all newly created events within the Outbox storage directly to the corresponding topic in Kafka (or any other broker).
-
+> However, it can be implemented
+> using [Debezium + Kafka Connect](https://debezium.io/documentation/reference/stable/architecture.html),
+> which allows you to produce all newly created events within the Outbox storage directly to the corresponding topic in
+> Kafka (or any other broker).
 
 ## DI container
 
-Use the following example to set up dependency injection in your command, query and event handlers. This will make dependency management simpler.
+Use the following example to set up dependency injection in your command, query and event handlers. This will make
+dependency management simpler.
 
 ```python
 import di
@@ -309,6 +374,8 @@ def setup_di() -> di.Container:
     return container
 ```
 
+A complete example can be found in
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/dependency_injection.py)
 
 ## Mapping
 
@@ -333,10 +400,11 @@ def init_events(mapper: events.EventMap) -> None:
     mapper.bind(events.ECSTEvent[event_models.ECSTMeetingRoomClosed], event_handlers.UpdateMeetingRoomReadModelHandler)
 ```
 
-
 ## Bootstrap
 
-The `python-cqrs` package implements a set of bootstrap utilities designed to simplify the initial configuration of an application.
+The `python-cqrs` package implements a set of bootstrap utilities designed to simplify the initial configuration of an
+application.
+
 ```python
 import functools
 
@@ -345,6 +413,7 @@ from cqrs.requests import bootstrap as request_bootstrap
 
 from app import dependencies, mapping, orm
 
+
 @functools.lru_cache
 def mediator_factory():
     return request_bootstrap.bootstrap(
@@ -365,12 +434,15 @@ def event_mediator_factory():
     )
 ```
 
-## Integaration with presentation layers
+## Integration with presentation layers
 
->[!TIP]
-> I recommend reading the useful paper [Onion Architecture Used in Software Development](https://www.researchgate.net/publication/371006360_Onion_Architecture_Used_in_Software_Development).
+> [!TIP]
+> I recommend reading the useful
+>
+paper [Onion Architecture Used in Software Development](https://www.researchgate.net/publication/371006360_Onion_Architecture_Used_in_Software_Development).
 > Separating user interaction and use-cases into Application and Presentation layers is a good practice.
-> This can improve the `Testability`, `Maintainability`, `Scalability` of the application. It also provides benefits such as `Separation of Concerns`.
+> This can improve the `Testability`, `Maintainability`, `Scalability` of the application. It also provides benefits
+> such as `Separation of Concerns`.
 
 ### FastAPI requests handling
 
@@ -394,34 +466,62 @@ async def join_metting(
 ):
     await mediator.send(commands.JoinMeetingCommand(meeting_id=meeting_id, user_id=user_id))
     return {"result": "ok"}
-
 ```
 
+A complete example can be found in
+the [documentation](https://github.com/vadikko2/cqrs/blob/master/examples/fastapi_integration.py)
+
 ### Kafka events consuming
 
-If you build interaction by events over brocker like `Kafka`, you can to implement an event consumer on your application's side,
+If you build interaction by events over broker like `Kafka`, you can to implement an event consumer on your
+application's side,
 which will call the appropriate handler for each event.
 An example of handling events from `Kafka` is provided below.
 
 ```python
-import aiokafka
 import cqrs
-import orjson
 
-from app import events
+import pydantic
+import faststream
+from faststream import kafka
+
+broker = kafka.KafkaBroker(bootstrap_servers=["localhost:9092"])
+app = faststream.FastStream(broker)
 
-class OnEvent:
 
-    def __init__(
-        self,
-        event_mediator: cqrs.EventMediator
-    ):
-        self._event_mediator = event_mediator
+class HelloWorldPayload(pydantic.BaseModel):
+    hello: str = pydantic.Field(default="Hello")
+    world: str = pydantic.Field(default="World")
 
-    async def __call__(self, kafka_message: aiokafka.ConsumerRecord) -> None:
-        event = cqrs.ECSTEvent[events.ECSTMeetingRoomClosed].model_validate(
-            orjson.loads(kafka_message.value),
-            context={"assume_validated": True},
-        )
-        await self._event_mediator.send(event)
+
+class HelloWorldECSTEventHandler(cqrs.EventHandler[cqrs.ECSTEvent[HelloWorldPayload]]):
+    async def handle(self, event: cqrs.ECSTEvent[HelloWorldPayload]) -> None:
+        print(f"{event.payload.hello} {event.payload.world}")  # type: ignore
+
+
+@broker.subscriber(
+    "hello_world",
+    group_id="examples",
+    auto_commit=False,
+    value_deserializer=value_deserializer,
+)
+async def hello_world_event_handler(
+    body: cqrs.ECSTEvent[HelloWorldPayload] | None,
+    msg: kafka.KafkaMessage,
+    mediator: cqrs.EventMediator = faststream.Depends(mediator_factory),
+):
+    if body is not None:
+        await mediator.send(body)
+    await msg.ack()
 ```
+
+A complete example can be found in
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/kafka_event_consuming.py)
+
+## Protobuf messaging
+
+The `python-cqrs` package supports integration with [protobuf](https://developers.google.com/protocol-buffers/).\
+Protocol buffers are Google’s language-neutral, platform-neutral, extensible mechanism for serializing structured data –
+think XML, but smaller, faster, and simpler. You define how you want your data to be structured once, then you can use
+special generated source code to easily write and read your structured data to and from a variety of data streams and
+using a variety of languages.