python-cqrs 5.0.0__tar.gz → 5.2.0__tar.gz

{python_cqrs-5.0.0/src/python_cqrs.egg-info → python_cqrs-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 5.0.0
+Version: 5.2.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>
@@ -22,13 +22,16 @@ Requires-Dist: di[anyio]==0.*
 Requires-Dist: dependency-injector>=4.0
 Requires-Dist: orjson==3.*
 Requires-Dist: python-dotenv==1.*
-Requires-Dist: typing-extensions>=4.0
+Requires-Dist: typing-extensions>=4.7
 Provides-Extra: aiobreaker
 Requires-Dist: aiobreaker>=0.3.0; extra == "aiobreaker"
 Provides-Extra: pydantic
 Requires-Dist: pydantic==2.*; extra == "pydantic"
 Provides-Extra: sqlalchemy
 Requires-Dist: sqlalchemy[asyncio]==2.0.*; extra == "sqlalchemy"
+Provides-Extra: sqlmodel
+Requires-Dist: sqlmodel>=0.0.22; extra == "sqlmodel"
+Requires-Dist: sqlalchemy[asyncio]==2.0.*; extra == "sqlmodel"
 Provides-Extra: dev
 Requires-Dist: pycln==2.5.0; extra == "dev"
 Requires-Dist: pre-commit==3.8.0; extra == "dev"
@@ -54,12 +57,14 @@ Requires-Dist: dishka>=1.0; extra == "dev"
 Requires-Dist: protobuf>=4.25.8; extra == "dev"
 Requires-Dist: pydantic==2.*; extra == "dev"
 Requires-Dist: sqlalchemy[asyncio]==2.0.*; extra == "dev"
+Requires-Dist: sqlmodel>=0.0.22; extra == "dev"
+Requires-Dist: aiosqlite>=0.20.0; extra == "dev"
 Provides-Extra: examples
 Requires-Dist: fastapi==0.109.*; extra == "examples"
 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.14.3; extra == "examples"
+Requires-Dist: aiohttp==3.14.4; extra == "examples"
 Requires-Dist: protobuf>=4.25.8; extra == "examples"
 Requires-Dist: aiosqlite>=0.20.0; extra == "examples"
 Requires-Dist: dishka>=1.0; extra == "examples"
@@ -98,32 +103,17 @@ Dynamic: license-file
     <a href="https://codecov.io/gh/vadikko2/python-cqrs">
       <img src="https://img.shields.io/codecov/c/github/vadikko2/python-cqrs?logo=codecov&logoColor=white" alt="Coverage">
     </a>
-    <a href="https://codspeed.io/vadikko2/python-cqrs?utm_source=badge">
-      <img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed">
-    </a>
-    <a href="https://mkdocs.python-cqrs.dev/">
-      <img src="https://img.shields.io/badge/docs-mkdocs-blue?logo=readthedocs" alt="Documentation">
-    </a>
-    <a href="https://deepwiki.com/vadikko2/python-cqrs">
-      <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
-    </a>
     <a href="https://github.com/mjhea0/awesome-fastapi#developer-tools">
       <img src="https://img.shields.io/badge/Awesome%20FastAPI-✓%20in%20list-purple?logo=eye&logoColor=white&style=flat-square" alt="Included in Awesome FastAPI">
     </a>
   </p>
 </div>
 
-> [!WARNING]
-> **Breaking Changes in v5.0.0**
->
-> Starting with version 5.0.0, Pydantic support will become optional. The default implementations of `Request`, `Response`, `DomainEvent`, and `NotificationEvent` will be migrated to dataclasses-based implementations.
-
 ## Table of Contents
 
 - [Overview](#overview)
 - [When NOT to use python-cqrs](#when-not-to-use-python-cqrs)
 - [Installation](#installation)
-- [Version Support](#version-support)
 - [Quick Start](#quick-start)
 - [Request and Response Types](#request-and-response-types)
 - [Request Handlers](#request-handlers)
@@ -148,9 +138,6 @@ Dynamic: license-file
 
 An event-driven framework for building distributed systems in Python. It centers on CQRS (Command Query Responsibility Segregation) and extends into messaging, sagas, and reliable event delivery — so you can separate read and write flows, react to events from the bus, run distributed transactions with compensation, and publish events via Transaction Outbox. The result is clearer structure, better scalability, and easier evolution 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, ordered by importance:
-
 **Core framework**
 
 1. Redesigned the event and request mapping mechanism to handlers;
@@ -166,7 +153,7 @@ project ([documentation](https://akhundmurad.github.io/diator/)) with several en
 
 - **Typing:** Pydantic [v2.*](https://docs.pydantic.dev/2.8/) and `IRequest`/`IResponse` interfaces — use Pydantic-based, dataclass-based, or custom Request/Response implementations.
 - **Broker:** Kafka via [aiokafka](https://github.com/aio-libs/aiokafka).
-- **Storage:** SQLAlchemy-based Outbox and Saga storage on MySQL/MariaDB and PostgreSQL.
+- **Storage:** SQLAlchemy and SQLModel outbox and saga storage on MySQL/MariaDB and PostgreSQL.
 - **Integration:** Ready for integration with FastAPI and FastStream.
 - **Documentation:** Built-in Mermaid diagram generation (Sequence and Class diagrams).
 - **Protobuf:** Interface-level support for converting Notification events to Protobuf and back.
@@ -189,11 +176,12 @@ Do not add a Saga for a single `UPDATE` in one service, and do not use a Saga as
 pip install python-cqrs
 ```
 
-Optional extras (5.0+ — pydantic and SQLAlchemy are no longer core dependencies):
+Optional extras (5.0+ — pydantic and SQLAlchemy are no longer core dependencies; SQLModel storage is 5.1+):
 
 ```bash
 pip install "python-cqrs[pydantic]"     # PydanticRequest / Pydantic* events
 pip install "python-cqrs[sqlalchemy]"   # Outbox / Saga SQLAlchemy storage
+pip install "python-cqrs[sqlmodel]"     # Outbox / Saga SQLModel storage
 pip install "python-cqrs[kafka]"        # Kafka broker (aiokafka)
 pip install "python-cqrs[examples]"     # FastAPI, FastStream, uvicorn, etc.
 pip install "python-cqrs[aiobreaker]"   # Circuit breaker for saga fallbacks
@@ -203,37 +191,8 @@ Default `Request` / `Response` / `Event` / `DomainEvent` / `NotificationEvent` a
 are dataclass-based (`DC*`). Use `Pydantic*` types with the pydantic extra when you
 need validation.
 
-### Import paths (5.0+)
-
-| Area | Import |
-|------|--------|
-| Bootstrap | `from cqrs.bootstrap import requests, events, saga` |
-| Mediators | `from cqrs.mediators import RequestMediator, SagaMediator, …` |
-| Handlers | `from cqrs.handlers import RequestHandler, EventHandler, …` |
-| Models | `from cqrs.models import Request, Event, …` / `cqrs.models.pydantic` |
-| Maps | `from cqrs.mapping import RequestMap, EventMap, OutboxedEventMap` |
-| Mermaid | `from cqrs.mermaid import CoRMermaid, SagaMermaid` |
-| Outbox producer | `from cqrs.message_brokers.producer import EventProducer` |
-
-`SagaMediator.execute(...)` replaces the former `SagaMediator.stream(...)`
-(StreamingRequestMediator.stream is unchanged).
-
-## Version Support
-
-| Line | Git branch | What changes |
-|------|------------|--------------|
-| **4.x** | `4.x` | Bug fixes and security only (~12 months after 5.0.0) |
-| **5.x** | `master` | Features and breaking changes |
-
-Stay on 4.x until you migrate:
+Coding agents in an application can follow [`templates/AGENTS.md`](templates/AGENTS.md). Copy that file into the application repository.
 
-```bash
-pip install "python-cqrs>=4,<5"
-```
-
-Docs: [4.x](https://mkdocs.python-cqrs.dev/4.0/) and [5.x / latest](https://mkdocs.python-cqrs.dev/latest/) (version switcher after mike deploy). See [SECURITY.md](SECURITY.md) for the support window and vulnerability reporting, and [CONTRIBUTING.md](CONTRIBUTING.md#8-maintaining--fixing-4x) for how to contribute 4.x bugfixes.
-
-A package-level EOL `DeprecationWarning` toward 5.x will be added on the **first 4.x patch after 5.0.0** — not before.
 
 ## Quick Start
 
@@ -244,12 +203,12 @@ import di
 import cqrs
 from cqrs.bootstrap import requests as bootstrap
 
-class CreateOrderCommand(cqrs.Request):
+class CreateOrderCommand(cqrs.Request[None]):
     order_id: str
     amount: float
 
-class CreateOrderHandler(cqrs.RequestHandler[CreateOrderCommand, None]):
-    async def handle(self, request: CreateOrderCommand) -> None:
+class CreateOrderHandler(cqrs.RequestHandler[CreateOrderCommand]):
+    async def handle(self, request: CreateOrderCommand):
         print(f"Order {request.order_id}, amount {request.amount}")
 
 def commands_mapper(mapper: cqrs.RequestMap) -> None:
@@ -326,14 +285,20 @@ Request handlers can be divided into two main types:
 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.
 
 ```python
+import cqrs
 from cqrs.handlers.request import RequestHandler
 from cqrs.models.event import Event
 
-class JoinMeetingCommandHandler(RequestHandler[JoinMeetingCommand, None]):
+class JoinMeetingCommand(cqrs.Request[None]):
+    user_id: str
+    meeting_id: str
+
+class JoinMeetingCommandHandler(RequestHandler[JoinMeetingCommand]):
 
       def __init__(self, meetings_api: MeetingAPIProtocol) -> None:
           self._meetings_api = meetings_api
@@ -343,25 +308,36 @@ class JoinMeetingCommandHandler(RequestHandler[JoinMeetingCommand, None]):
       def events(self) -> typing.List[events.Event]:
           return self._events
 
-      async def handle(self, request: JoinMeetingCommand) -> None:
+      async def handle(self, request: JoinMeetingCommand):
           await self._meetings_api.join_user(request.user_id, request.meeting_id)
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/request_handler.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/request_handler.py).
+The one-argument form is in
+[`examples/events/typed_request_handler.py`](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/typed_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).
+
 > [!TIP]
 > The read model can be constructed based on domain events produced by the `Command Handler`.
 
 ```python
+import cqrs
 from cqrs.handlers.request import RequestHandler
 from cqrs.models.event import Event
 
-class ReadMeetingQueryHandler(RequestHandler[ReadMeetingQuery, ReadMeetingQueryResult]):
+class ReadMeetingQueryResult(cqrs.Response):
+    link: str
+    meeting_id: str
+
+class ReadMeetingQuery(cqrs.Request[ReadMeetingQueryResult]):
+    meeting_id: str
+
+class ReadMeetingQueryHandler(RequestHandler[ReadMeetingQuery]):
 
       def __init__(self, meetings_api: MeetingAPIProtocol) -> None:
           self._meetings_api = meetings_api
@@ -371,14 +347,16 @@ class ReadMeetingQueryHandler(RequestHandler[ReadMeetingQuery, ReadMeetingQueryR
       def events(self) -> typing.List[events.Event]:
           return self._events
 
-      async def handle(self, request: ReadMeetingQuery) -> ReadMeetingQueryResult:
+      async def handle(self, request: ReadMeetingQuery):
           link = await self._meetings_api.get_link(request.meeting_id)
           return ReadMeetingQueryResult(link=link, meeting_id=request.meeting_id)
 
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/request_handler.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/request_handler.py).
+The one-argument form is in
+[`examples/events/typed_request_handler.py`](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/typed_request_handler.py).
 
 ### Streaming Request Handler
 
@@ -389,11 +367,18 @@ real-time progress updates.
 `StreamingRequestHandler` works with `StreamingRequestMediator` that streams results to clients in real-time.
 
 ```python
-import typing
+import cqrs
 from cqrs.handlers.request import StreamingRequestHandler
 from cqrs.models.event import Event
 
-class ProcessFilesCommandHandler(StreamingRequestHandler[ProcessFilesCommand, FileProcessedResult]):
+class FileProcessedResult(cqrs.Response):
+    file_id: str
+    status: str
+
+class ProcessFilesCommand(cqrs.Request[FileProcessedResult]):
+    file_ids: list[str]
+
+class ProcessFilesCommandHandler(StreamingRequestHandler[ProcessFilesCommand]):
     def __init__(self):
         self._events: list[Event] = []
 
@@ -404,7 +389,7 @@ class ProcessFilesCommandHandler(StreamingRequestHandler[ProcessFilesCommand, Fi
     def clear_events(self) -> None:
         self._events.clear()
 
-    async def handle(self, request: ProcessFilesCommand) -> typing.AsyncIterator[FileProcessedResult]:
+    async def handle(self, request: ProcessFilesCommand):
         for file_id in request.file_ids:
             # Process file
             result = FileProcessedResult(file_id=file_id, status="completed", ...)
@@ -414,7 +399,9 @@ class ProcessFilesCommandHandler(StreamingRequestHandler[ProcessFilesCommand, Fi
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/streaming/streaming_handler_parallel_events.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/streaming/streaming_handler_parallel_events.py).
+The one-argument form is in
+[`examples/streaming/typed_streaming_handler.py`](https://github.com/vadikko2/python-cqrs/blob/master/examples/streaming/typed_streaming_handler.py).
 
 ### Chain of Responsibility Request Handler
 
@@ -427,10 +414,18 @@ when a handler successfully processes the request or when all handlers have been
 
 ```python
 import typing
+import cqrs
 from cqrs.handlers.cor import CORRequestHandler
 from cqrs.models.event import Event
 
-class CreditCardPaymentHandler(CORRequestHandler[ProcessPaymentCommand, PaymentResult]):
+class PaymentResult(cqrs.Response):
+    success: bool
+    transaction_id: str
+
+class ProcessPaymentCommand(cqrs.Request[PaymentResult]):
+    payment_method: str
+
+class CreditCardPaymentHandler(CORRequestHandler[ProcessPaymentCommand]):
     def __init__(self, payment_service: PaymentServiceProtocol) -> None:
         self._payment_service = payment_service
         self._events: typing.List[Event] = []
@@ -439,7 +434,7 @@ class CreditCardPaymentHandler(CORRequestHandler[ProcessPaymentCommand, PaymentR
     def events(self) -> typing.List[Event]:
         return self._events
 
-    async def handle(self, request: ProcessPaymentCommand) -> PaymentResult | None:
+    async def handle(self, request: ProcessPaymentCommand):
         if request.payment_method == "credit_card":
             # Process credit card payment
             result = await self._payment_service.process_credit_card(request)
@@ -449,7 +444,7 @@ class CreditCardPaymentHandler(CORRequestHandler[ProcessPaymentCommand, PaymentR
         # Pass to next handler
         return await self.next(request)
 
-class PayPalPaymentHandler(CORRequestHandler[ProcessPaymentCommand, PaymentResult]):
+class PayPalPaymentHandler(CORRequestHandler[ProcessPaymentCommand]):
     def __init__(self, paypal_service: PayPalServiceProtocol) -> None:
         self._paypal_service = paypal_service
         self._events: typing.List[Event] = []
@@ -458,7 +453,7 @@ class PayPalPaymentHandler(CORRequestHandler[ProcessPaymentCommand, PaymentResul
     def events(self) -> typing.List[Event]:
         return self._events
 
-    async def handle(self, request: ProcessPaymentCommand) -> PaymentResult | None:
+    async def handle(self, request: ProcessPaymentCommand):
         if request.payment_method == "paypal":
             # Process PayPal payment
             result = await self._paypal_service.process_payment(request)
@@ -477,7 +472,9 @@ def payment_mapper(mapper: cqrs.RequestMap) -> None:
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/cor/cor_request_handler.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/cor/cor_request_handler.py).
+The one-argument form is in
+[`examples/cor/typed_cor_request_handler.py`](https://github.com/vadikko2/python-cqrs/blob/master/examples/cor/typed_cor_request_handler.py).
 
 #### Mermaid Diagram Generation
 
@@ -849,7 +846,11 @@ Complete example: [Saga Mermaid Diagrams](https://github.com/vadikko2/python-cqr
 During the handling of a command, `cqrs.NotificationEvent` events may be generated and then sent to the broker.
 
 ```python
-class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
+class JoinMeetingCommand(cqrs.Request[None]):
+    user_id: str
+    meeting_id: str
+
+class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand]):
     def __init__(self):
         self._events = []
 
@@ -857,7 +858,7 @@ class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
     def events(self):
         return self._events
 
-    async def handle(self, request: JoinMeetingCommand) -> None:
+    async def handle(self, request: JoinMeetingCommand):
         print(f"User {request.user_id} joined meeting {request.meeting_id}")
         self._events.append(
             cqrs.NotificationEvent[UserJoinedNotificationPayload](
@@ -917,7 +918,11 @@ The package implements the [Transactional Outbox](https://microservices.io/patte
 pattern, which ensures that messages are produced to the broker according to the at-least-once semantics.
 
 ```python
-class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
+class JoinMeetingCommand(cqrs.Request[None]):
+    user_id: str
+    meeting_id: str
+
+class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand]):
     def __init__(self, outbox: cqrs.OutboxedEventRepository):
         self.outbox = outbox
 
@@ -925,7 +930,7 @@ class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
     def events(self):
         return []
 
-    async def handle(self, request: JoinMeetingCommand) -> None:
+    async def handle(self, request: JoinMeetingCommand):
         print(f"User {request.user_id} joined meeting {request.meeting_id}")
         # Outbox repository is bound to a session (e.g. via DI request scope).
         # add() takes only the event; commit() persists the outbox and your changes.
@@ -962,12 +967,14 @@ A runnable FastAPI flow (route → command → transactional outbox → publishe
 > The Outbox table is named `outbox` by default. To rename it, or to attach the model to your own declarative
 > base, use `cqrs.rebind_outbox_model(OutboxModel, Base, table_name="my_outbox_table")` at startup — before
 > `create_all()`, before generating migrations and before the first query.
+
 > [!TIP]
 > `SqlAlchemyOutboxedEventRepository` works on **MySQL/MariaDB** and **PostgreSQL**: the outbox columns are
 > rendered with dialect-aware types (`BINARY(16)` on MySQL, `UUID`/`BYTEA` on PostgreSQL), with a portable
 > `BLOB` fallback for other dialects. Switching databases is a DSN change only — see the
 > [Database Support](https://mkdocs.python-cqrs.dev/outbox/databases/) docs for the DDL, the Alembic recipe and
 > how to register a native type for your own database.
+
 > [!TIP]
 > For Protobuf events, implement `proto()` / `from_proto()` and register a
 > `ProtobufEventSerializer` on an `OutboxedEventMap`. JSON stays the default —
@@ -1032,7 +1039,11 @@ 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
-class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
+class JoinMeetingCommand(cqrs.Request[None]):
+    user_id: str
+    meeting_id: str
+
+class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand]):
     def __init__(self):
         self._events = []
 
@@ -1040,7 +1051,7 @@ class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
     def events(self):
         return self._events
 
-    async def handle(self, request: JoinMeetingCommand) -> None:
+    async def handle(self, request: JoinMeetingCommand):
         STORAGE[request.meeting_id].append(request.user_id)
         self._events.append(
             UserJoined(user_id=request.user_id, meeting_id=request.meeting_id),