python-cqrs 4.12.0__tar.gz → 4.14.0__tar.gz

{python_cqrs-4.12.0 → python_cqrs-4.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 4.12.0
+Version: 4.14.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>
@@ -42,18 +42,22 @@ Requires-Dist: requests==2.*; 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: cryptography==48.0.1; extra == "dev"
+Requires-Dist: alembic>=1.13.0; extra == "dev"
+Requires-Dist: cryptography==50.0.0; extra == "dev"
 Requires-Dist: asyncmy==0.2.9; extra == "dev"
 Requires-Dist: asyncpg>=0.29.0; extra == "dev"
 Requires-Dist: redis>=5.0.0; extra == "dev"
 Requires-Dist: aiobreaker>=0.3.0; extra == "dev"
+Requires-Dist: dishka>=1.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.1; extra == "examples"
+Requires-Dist: aiohttp==3.14.3; 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"
 Provides-Extra: kafka
 Requires-Dist: aiokafka==0.10.0; extra == "kafka"
 Requires-Dist: retry-async==0.1.*; extra == "kafka"
@@ -61,6 +65,8 @@ Provides-Extra: rabbit
 Requires-Dist: aio-pika==9.3.0; extra == "rabbit"
 Provides-Extra: sqlalchemy
 Requires-Dist: sqlalchemy[asyncio]==2.0.*; extra == "sqlalchemy"
+Provides-Extra: dishka
+Requires-Dist: dishka>=1.0; extra == "dishka"
 Dynamic: license-file
 
 <div align="center">
@@ -108,12 +114,14 @@ Dynamic: license-file
 ## Table of Contents
 
 - [Overview](#overview)
+- [When NOT to use python-cqrs](#when-not-to-use-python-cqrs)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Request and Response Types](#request-and-response-types)
 - [Request Handlers](#request-handlers)
 - [Mapping](#mapping)
 - [DI container](#di-container)
+- [Scoped dependencies](#scoped-dependencies)
 - [Bootstrap](#bootstrap)
 - [Saga Pattern](#saga-pattern)
 - [Producing Notification Events](#producing-notification-events)
@@ -150,10 +158,21 @@ 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.
 - **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.
 
+## When NOT to use python-cqrs
+
+CQRS, Outbox, and Saga are tools for specific problems — not a default for every service.
+
+- **Prefer a local DB transaction** for single-service CRUD (one database, no broker, no compensation).
+- **Use [Transactional Outbox](#transactional-outbox)** when you dual-write to a database **and** a message broker. Commit the business row and the outbox row together; a publisher drains the outbox later.
+- **Use [Saga](#saga-pattern)** when a multi-step flow crosses service/database boundaries and a later step must be compensated if it fails.
+
+Do not add a Saga for a single `UPDATE` in one service, and do not use a Saga as a substitute for Outbox. Full write-up: [When NOT to use python-cqrs](docs/when_not_to_use.md).
+
 ## Installation
 
 **Python 3.10+** is required.
@@ -250,7 +269,7 @@ class CustomResponse(cqrs.IResponse):
         return cls(result=kwargs["result"], status=kwargs["status"])
 ```
 
-A complete example can be found in [request_response_types.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/request_response_types.py)
+A complete example can be found in [request_response_types.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/request_response_types.py)
 
 ## Request Handlers
 
@@ -283,7 +302,7 @@ class JoinMeetingCommandHandler(RequestHandler[JoinMeetingCommand, None]):
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/request_handler.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/request_handler.py)
 
 ### Query handler
 
@@ -313,7 +332,7 @@ class ReadMeetingQueryHandler(RequestHandler[ReadMeetingQuery, ReadMeetingQueryR
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/request_handler.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/request_handler.py)
 
 ### Streaming Request Handler
 
@@ -349,7 +368,7 @@ class ProcessFilesCommandHandler(StreamingRequestHandler[ProcessFilesCommand, Fi
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/streaming_handler_parallel_events.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/streaming/streaming_handler_parallel_events.py)
 
 ### Chain of Responsibility Request Handler
 
@@ -412,7 +431,7 @@ 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_request_handler.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/cor/cor_request_handler.py)
 
 #### Mermaid Diagram Generation
 
@@ -432,7 +451,7 @@ sequence_diagram = generator.sequence()
 class_diagram = generator.class_diagram()
 ```
 
-Complete example: [CoR Mermaid Diagrams](https://github.com/vadikko2/python-cqrs/blob/master/examples/cor_mermaid.py)
+Complete example: [CoR Mermaid Diagrams](https://github.com/vadikko2/python-cqrs/blob/master/examples/cor/cor_mermaid.py)
 
 ## Mapping
 
@@ -493,7 +512,11 @@ def saga_mapper(mapper: cqrs.SagaMap) -> None:
 Use the following example to set up dependency injection in your command, query and event handlers. This will make
 dependency management simpler.
 
-The package supports two DI container libraries:
+The package supports three DI container libraries:
+
+- [`di`](#di-library) (default)
+- [`dependency-injector`](#dependency-injector-library)
+- [dishka](https://github.com/reagento/dishka) via `DishkaCQRSContainer` (`pip install python-cqrs[dishka]`)
 
 ### di library
 
@@ -522,7 +545,7 @@ def setup_di() -> di.Container:
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/dependency_injection.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/di/di_basic.py)
 
 ### dependency-injector library
 
@@ -538,7 +561,8 @@ class ApplicationContainer(containers.DeclarativeContainer):
     service = providers.Factory(ServiceImplementation)
 
 # Create CQRS container adapter
-cqrs_container = DependencyInjectorCQRSContainer(ApplicationContainer())
+cqrs_container = DependencyInjectorCQRSContainer()
+cqrs_container.attach_external_container(ApplicationContainer())
 
 # Use with bootstrap
 mediator = bootstrap.bootstrap(
@@ -549,8 +573,32 @@ mediator = bootstrap.bootstrap(
 ```
 
 Complete examples can be found in:
-- [Simple example](https://github.com/vadikko2/python-cqrs/blob/master/examples/dependency_injector_integration_simple_example.py)
-- [Practical example with FastAPI](https://github.com/vadikko2/python-cqrs/blob/master/examples/dependency_injector_integration_practical_example.py)
+- [Simple example](https://github.com/vadikko2/python-cqrs/blob/master/examples/di/dependency_injector_simple.py)
+- [Practical example with FastAPI](https://github.com/vadikko2/python-cqrs/blob/master/examples/di/dependency_injector_practical.py)
+
+### Scoped dependencies
+
+By default, the container opens and closes a scope **inside** `resolve()`. A generator such as `async def session() -> AsyncIterator[AsyncSession]` therefore finishes **before** `handle`, which is why people inject factories.
+
+Pass `scope_strategy=ScopeStrategy.SEND` and that session lives until `mediator.send()` returns — including domain-event handlers that run afterwards.
+
+If you do not use generator providers, leave the default `ScopeStrategy.NONE` and change nothing.
+
+```python
+mediator = bootstrap.bootstrap(
+    di_container=container,
+    commands_mapper=commands_mapper,
+    scope_strategy=cqrs.ScopeStrategy.SEND,
+)
+```
+
+Copy-paste SQLAlchemy session + outbox under one SEND scope: the [Tutorial](https://mkdocs.python-cqrs.dev/scoped_dependencies/tutorial/) (`examples/di/scoped_dependencies_sqlalchemy.py`). Minimal `di` UoW: `examples/di/scoped_dependencies_di.py`.
+
+- **SEND** — one UoW per `send()` (command, fallback, and domain events).
+- **HANDLER** — a fresh UoW per handler, including fallback (the primary rolls back first).
+- **NONE** — legacy one-shot resolve; the default.
+
+`di`'s `scope="request"` is provider lifetime, not a CQRS scope — that is only `scope_strategy=`. Docs: [Scoped Dependencies](https://mkdocs.python-cqrs.dev/scoped_dependencies/).
 
 ## Bootstrap
 
@@ -715,6 +763,7 @@ await recover_saga(
     context_builder=OrderContext,
     container=di_container,  # Same container used in bootstrap
     storage=storage,
+    scope_strategy=cqrs.ScopeStrategy.SEND,  # Match the original run
 )
 
 # Access execution history (SagaLog) for monitoring and debugging
@@ -747,7 +796,7 @@ sequence_diagram = generator.sequence()
 class_diagram = generator.class_diagram()
 ```
 
-Complete example: [Saga Mermaid Diagrams](https://github.com/vadikko2/python-cqrs/blob/master/examples/saga_mermaid.py)
+Complete example: [Saga Mermaid Diagrams](https://github.com/vadikko2/python-cqrs/blob/master/examples/saga/saga_mermaid.py)
 
 ## Producing Notification Events
 
@@ -787,7 +836,7 @@ class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/event_producing.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/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.
@@ -858,16 +907,29 @@ class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/save_events_into_outbox.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/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`.
+A runnable FastAPI flow (route → command → transactional outbox → publisher stub) is in
+[fastapi_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/fastapi_outbox.py)
 
 > [!TIP]
-> If you use the protobuf events you should specify `OutboxedEventRepository`
-> by [protobuf serialize](https://github.com/vadikko2/python-cqrs/blob/master/src/cqrs/serializers/protobuf.py). A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/save_proto_events_into_outbox.py)
+> 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()` on the notification
+> event (see [Protobuf messaging](#protobuf-messaging) and the schema assets in
+> [examples/proto/](https://github.com/vadikko2/python-cqrs/tree/master/examples/proto)).
+> Outbox persistence is unchanged — use
+> [save_events_into_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/save_events_into_outbox.py);
+> Protobuf applies when producing to the broker. Full guide:
+> [Protobuf Integration](https://mkdocs.python-cqrs.dev/protobuf/).
 
 ## Producing Events from Outbox to Kafka
 
@@ -906,7 +968,7 @@ async with session_factory() as session:
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/kafka_outboxed_event_producing.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/kafka_outboxed_event_producing.py)
 
 ## Transaction log tailing
 
@@ -949,7 +1011,7 @@ class UserJoinedEventHandler(cqrs.EventHandler[UserJoined]):
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/domain_event_handler.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/domain_event_handler.py)
 
 ### Parallel Event Processing
 
@@ -980,6 +1042,7 @@ mediator = bootstrap.bootstrap_streaming(
 > - Set `max_concurrent_event_handlers` to limit the number of simultaneously running event handlers
 > - Set `concurrent_event_handle_enable=False` to disable parallel processing and process events sequentially
 > - The default value for `max_concurrent_event_handlers` is `10` for `StreamingRequestMediator` and `1` for `RequestMediator`
+> - `ScopeStrategy.SEND` always uses sequential events (`concurrent=None` → `False`). Passing `concurrent_event_handle_enable=True` with `SEND` raises `ValueError`; use `HANDLER` or `NONE` for parallel events.
 
 ## Integration with presentation layers
 
@@ -1017,7 +1080,10 @@ async def join_metting(
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_integration.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/fastapi_integration.py)
+
+End-to-end command + outbox sample (business row and outbox event in one transaction, plus a publisher stub):
+[fastapi_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/fastapi_outbox.py)
 
 ### Kafka events consuming
 
@@ -1065,7 +1131,7 @@ async def hello_world_event_handler(
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/kafka_event_consuming.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/kafka_event_consuming.py)
 
 ### FastAPI SSE Streaming
 
@@ -1086,7 +1152,7 @@ def streaming_mediator_factory() -> cqrs.StreamingRequestMediator:
         domain_events_mapper=domain_events_mapper,
         message_broker=broker,
         max_concurrent_event_handlers=3,
-        concurrent_event_handle_enable=True,
+        concurrent_event_handle_enable=True,  # HANDLER/NONE only; SEND forbids this
     )
 
 @app.post("/process-files")
@@ -1113,7 +1179,9 @@ async def process_files_stream(
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_sse_streaming.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/streaming/fastapi_sse_streaming.py)
+
+If the client disconnects, close the iterator (`aclose()` / `async with aclosing(...)`) so a `SEND` UoW is not held until GC.
 
 ## Protobuf messaging
 

{python_cqrs-4.12.0 → python_cqrs-4.14.0}/README.md

@@ -43,12 +43,14 @@
 ## Table of Contents
 
 - [Overview](#overview)
+- [When NOT to use python-cqrs](#when-not-to-use-python-cqrs)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Request and Response Types](#request-and-response-types)
 - [Request Handlers](#request-handlers)
 - [Mapping](#mapping)
 - [DI container](#di-container)
+- [Scoped dependencies](#scoped-dependencies)
 - [Bootstrap](#bootstrap)
 - [Saga Pattern](#saga-pattern)
 - [Producing Notification Events](#producing-notification-events)
@@ -85,10 +87,21 @@ 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.
 - **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.
 
+## When NOT to use python-cqrs
+
+CQRS, Outbox, and Saga are tools for specific problems — not a default for every service.
+
+- **Prefer a local DB transaction** for single-service CRUD (one database, no broker, no compensation).
+- **Use [Transactional Outbox](#transactional-outbox)** when you dual-write to a database **and** a message broker. Commit the business row and the outbox row together; a publisher drains the outbox later.
+- **Use [Saga](#saga-pattern)** when a multi-step flow crosses service/database boundaries and a later step must be compensated if it fails.
+
+Do not add a Saga for a single `UPDATE` in one service, and do not use a Saga as a substitute for Outbox. Full write-up: [When NOT to use python-cqrs](docs/when_not_to_use.md).
+
 ## Installation
 
 **Python 3.10+** is required.
@@ -185,7 +198,7 @@ class CustomResponse(cqrs.IResponse):
         return cls(result=kwargs["result"], status=kwargs["status"])
 ```
 
-A complete example can be found in [request_response_types.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/request_response_types.py)
+A complete example can be found in [request_response_types.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/request_response_types.py)
 
 ## Request Handlers
 
@@ -218,7 +231,7 @@ class JoinMeetingCommandHandler(RequestHandler[JoinMeetingCommand, None]):
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/request_handler.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/request_handler.py)
 
 ### Query handler
 
@@ -248,7 +261,7 @@ class ReadMeetingQueryHandler(RequestHandler[ReadMeetingQuery, ReadMeetingQueryR
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/request_handler.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/request_handler.py)
 
 ### Streaming Request Handler
 
@@ -284,7 +297,7 @@ class ProcessFilesCommandHandler(StreamingRequestHandler[ProcessFilesCommand, Fi
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/streaming_handler_parallel_events.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/streaming/streaming_handler_parallel_events.py)
 
 ### Chain of Responsibility Request Handler
 
@@ -347,7 +360,7 @@ 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_request_handler.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/cor/cor_request_handler.py)
 
 #### Mermaid Diagram Generation
 
@@ -367,7 +380,7 @@ sequence_diagram = generator.sequence()
 class_diagram = generator.class_diagram()
 ```
 
-Complete example: [CoR Mermaid Diagrams](https://github.com/vadikko2/python-cqrs/blob/master/examples/cor_mermaid.py)
+Complete example: [CoR Mermaid Diagrams](https://github.com/vadikko2/python-cqrs/blob/master/examples/cor/cor_mermaid.py)
 
 ## Mapping
 
@@ -428,7 +441,11 @@ def saga_mapper(mapper: cqrs.SagaMap) -> None:
 Use the following example to set up dependency injection in your command, query and event handlers. This will make
 dependency management simpler.
 
-The package supports two DI container libraries:
+The package supports three DI container libraries:
+
+- [`di`](#di-library) (default)
+- [`dependency-injector`](#dependency-injector-library)
+- [dishka](https://github.com/reagento/dishka) via `DishkaCQRSContainer` (`pip install python-cqrs[dishka]`)
 
 ### di library
 
@@ -457,7 +474,7 @@ def setup_di() -> di.Container:
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/dependency_injection.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/di/di_basic.py)
 
 ### dependency-injector library
 
@@ -473,7 +490,8 @@ class ApplicationContainer(containers.DeclarativeContainer):
     service = providers.Factory(ServiceImplementation)
 
 # Create CQRS container adapter
-cqrs_container = DependencyInjectorCQRSContainer(ApplicationContainer())
+cqrs_container = DependencyInjectorCQRSContainer()
+cqrs_container.attach_external_container(ApplicationContainer())
 
 # Use with bootstrap
 mediator = bootstrap.bootstrap(
@@ -484,8 +502,32 @@ mediator = bootstrap.bootstrap(
 ```
 
 Complete examples can be found in:
-- [Simple example](https://github.com/vadikko2/python-cqrs/blob/master/examples/dependency_injector_integration_simple_example.py)
-- [Practical example with FastAPI](https://github.com/vadikko2/python-cqrs/blob/master/examples/dependency_injector_integration_practical_example.py)
+- [Simple example](https://github.com/vadikko2/python-cqrs/blob/master/examples/di/dependency_injector_simple.py)
+- [Practical example with FastAPI](https://github.com/vadikko2/python-cqrs/blob/master/examples/di/dependency_injector_practical.py)
+
+### Scoped dependencies
+
+By default, the container opens and closes a scope **inside** `resolve()`. A generator such as `async def session() -> AsyncIterator[AsyncSession]` therefore finishes **before** `handle`, which is why people inject factories.
+
+Pass `scope_strategy=ScopeStrategy.SEND` and that session lives until `mediator.send()` returns — including domain-event handlers that run afterwards.
+
+If you do not use generator providers, leave the default `ScopeStrategy.NONE` and change nothing.
+
+```python
+mediator = bootstrap.bootstrap(
+    di_container=container,
+    commands_mapper=commands_mapper,
+    scope_strategy=cqrs.ScopeStrategy.SEND,
+)
+```
+
+Copy-paste SQLAlchemy session + outbox under one SEND scope: the [Tutorial](https://mkdocs.python-cqrs.dev/scoped_dependencies/tutorial/) (`examples/di/scoped_dependencies_sqlalchemy.py`). Minimal `di` UoW: `examples/di/scoped_dependencies_di.py`.
+
+- **SEND** — one UoW per `send()` (command, fallback, and domain events).
+- **HANDLER** — a fresh UoW per handler, including fallback (the primary rolls back first).
+- **NONE** — legacy one-shot resolve; the default.
+
+`di`'s `scope="request"` is provider lifetime, not a CQRS scope — that is only `scope_strategy=`. Docs: [Scoped Dependencies](https://mkdocs.python-cqrs.dev/scoped_dependencies/).
 
 ## Bootstrap
 
@@ -650,6 +692,7 @@ await recover_saga(
     context_builder=OrderContext,
     container=di_container,  # Same container used in bootstrap
     storage=storage,
+    scope_strategy=cqrs.ScopeStrategy.SEND,  # Match the original run
 )
 
 # Access execution history (SagaLog) for monitoring and debugging
@@ -682,7 +725,7 @@ sequence_diagram = generator.sequence()
 class_diagram = generator.class_diagram()
 ```
 
-Complete example: [Saga Mermaid Diagrams](https://github.com/vadikko2/python-cqrs/blob/master/examples/saga_mermaid.py)
+Complete example: [Saga Mermaid Diagrams](https://github.com/vadikko2/python-cqrs/blob/master/examples/saga/saga_mermaid.py)
 
 ## Producing Notification Events
 
@@ -722,7 +765,7 @@ class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/event_producing.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/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.
@@ -793,16 +836,29 @@ class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/save_events_into_outbox.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/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`.
+A runnable FastAPI flow (route → command → transactional outbox → publisher stub) is in
+[fastapi_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/fastapi_outbox.py)
 
 > [!TIP]
-> If you use the protobuf events you should specify `OutboxedEventRepository`
-> by [protobuf serialize](https://github.com/vadikko2/python-cqrs/blob/master/src/cqrs/serializers/protobuf.py). A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/save_proto_events_into_outbox.py)
+> 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()` on the notification
+> event (see [Protobuf messaging](#protobuf-messaging) and the schema assets in
+> [examples/proto/](https://github.com/vadikko2/python-cqrs/tree/master/examples/proto)).
+> Outbox persistence is unchanged — use
+> [save_events_into_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/save_events_into_outbox.py);
+> Protobuf applies when producing to the broker. Full guide:
+> [Protobuf Integration](https://mkdocs.python-cqrs.dev/protobuf/).
 
 ## Producing Events from Outbox to Kafka
 
@@ -841,7 +897,7 @@ async with session_factory() as session:
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/kafka_outboxed_event_producing.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/kafka_outboxed_event_producing.py)
 
 ## Transaction log tailing
 
@@ -884,7 +940,7 @@ class UserJoinedEventHandler(cqrs.EventHandler[UserJoined]):
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/domain_event_handler.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/domain_event_handler.py)
 
 ### Parallel Event Processing
 
@@ -915,6 +971,7 @@ mediator = bootstrap.bootstrap_streaming(
 > - Set `max_concurrent_event_handlers` to limit the number of simultaneously running event handlers
 > - Set `concurrent_event_handle_enable=False` to disable parallel processing and process events sequentially
 > - The default value for `max_concurrent_event_handlers` is `10` for `StreamingRequestMediator` and `1` for `RequestMediator`
+> - `ScopeStrategy.SEND` always uses sequential events (`concurrent=None` → `False`). Passing `concurrent_event_handle_enable=True` with `SEND` raises `ValueError`; use `HANDLER` or `NONE` for parallel events.
 
 ## Integration with presentation layers
 
@@ -952,7 +1009,10 @@ async def join_metting(
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_integration.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/fastapi_integration.py)
+
+End-to-end command + outbox sample (business row and outbox event in one transaction, plus a publisher stub):
+[fastapi_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/outbox/fastapi_outbox.py)
 
 ### Kafka events consuming
 
@@ -1000,7 +1060,7 @@ async def hello_world_event_handler(
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/kafka_event_consuming.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/events/kafka_event_consuming.py)
 
 ### FastAPI SSE Streaming
 
@@ -1021,7 +1081,7 @@ def streaming_mediator_factory() -> cqrs.StreamingRequestMediator:
         domain_events_mapper=domain_events_mapper,
         message_broker=broker,
         max_concurrent_event_handlers=3,
-        concurrent_event_handle_enable=True,
+        concurrent_event_handle_enable=True,  # HANDLER/NONE only; SEND forbids this
     )
 
 @app.post("/process-files")
@@ -1048,7 +1108,9 @@ async def process_files_stream(
 ```
 
 A complete example can be found in
-the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_sse_streaming.py)
+the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/streaming/fastapi_sse_streaming.py)
+
+If the client disconnects, close the iterator (`aclose()` / `async with aclosing(...)`) so a `SEND` UoW is not held until GC.
 
 ## Protobuf messaging
 

{python_cqrs-4.12.0 → python_cqrs-4.14.0}/pyproject.toml

@@ -31,7 +31,7 @@ maintainers = [{ name = "Vadim Kozyrevskiy", email = "vadikko2@mail.ru" }]
 name = "python-cqrs"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "4.12.0"
+version = "4.14.0"
 
 [project.optional-dependencies]
 aiobreaker = ["aiobreaker>=0.3.0"]
@@ -52,24 +52,29 @@ dev = [
   "pytest~=7.4.2",
   "pytest-asyncio~=0.21.1",
   "pytest-env==0.6.2",
-  "cryptography==48.0.1",
+  "alembic>=1.13.0",  # from outbox migrations tests
+  "cryptography==50.0.0",
   "asyncmy==0.2.9",
   "asyncpg>=0.29.0",
   "redis>=5.0.0",
   # Circuit breaker for tests
   "aiobreaker>=0.3.0", # from aiobreaker
+  "dishka>=1.0",  # scoped-deps dishka adapter tests / examples
 ]
 examples = [
   "fastapi==0.109.*",
   "faststream[kafka]==0.5.28",
   "faker>=37.12.0",
   "uvicorn==0.32.0",
-  "aiohttp==3.14.1",
+  "aiohttp==3.14.3",
   "protobuf>=4.25.8",
+  "aiosqlite>=0.20.0",
+  "dishka>=1.0",
 ]
 kafka = ["aiokafka==0.10.0", "retry-async==0.1.*"]
 rabbit = ["aio-pika==9.3.0"]
 sqlalchemy = ["sqlalchemy[asyncio]==2.0.*"]
+dishka = ["dishka>=1.0"]
 
 [project.urls]
 Documentation = "https://mkdocs.python-cqrs.dev/"