docs

Author: remimd

README.md

@@ -7,11 +7,18 @@
 
 Documentation: https://python-cq.remimd.dev
 
-Python package designed to organize your code following CQRS principles. It builds on top of [python-injection](https://github.com/100nm/python-injection) for dependency injection.
+**python-cq** is a Python package designed to organize your code following CQRS principles. It provides a `DIAdapter` protocol for dependency injection, with [python-injection](https://github.com/100nm/python-injection) as the default implementation available via the `[injection]` extra.
 
 ## Installation
 
 ⚠️ _Requires Python 3.12 or higher_
+
+Without dependency injection:
 ```bash
 pip install python-cq
 ```
+
+With [python-injection](https://github.com/100nm/python-injection) as the DI backend (recommended):
+```bash
+pip install "python-cq[injection]"
+```

docs/di.md

@@ -0,0 +1,71 @@
+# Custom DI
+
+**python-cq** abstracts dependency injection behind the `DIAdapter` protocol, allowing you to integrate any DI framework.
+
+## The `CQ` class
+
+`CQ` is the central object that binds together the handler registries and the DI adapter. The module-level decorators (`command_handler`, `event_handler`, `query_handler`) and bus factories (`new_command_bus`, `new_event_bus`, `new_query_bus`) all derive from a default `CQ` instance created at import time.
+
+You can create additional isolated instances when you need separate handler registries, for example in tests or in a multi-tenant setup:
+
+```python
+from cq import CQ, ContextCommandPipeline
+
+cq = CQ(my_di_adapter).register_defaults()
+
+command_handler = cq.command_handler
+event_handler = cq.event_handler
+query_handler = cq.query_handler
+
+new_command_bus = cq.new_command_bus
+new_event_bus = cq.new_event_bus
+new_query_bus = cq.new_query_bus
+```
+
+When using `ContextCommandPipeline`, pass `cq.di` explicitly so it uses the same DI adapter:
+
+```python
+ContextCommandPipeline(cq.di)
+```
+
+## Implementing a `DIAdapter`
+
+`DIAdapter` is a `Protocol`. Implement it to integrate any DI framework:
+
+```python
+from collections.abc import Awaitable, Callable
+from cq import CQ, DIAdapter, CommandBus, EventBus, QueryBus
+from typing import Any, AsyncContextManager
+
+class MyDIAdapter(DIAdapter):
+    def command_scope(self) -> AsyncContextManager[None]:
+        # Return an async context manager that:
+        # - opens a DI scope for the duration of a command dispatch
+        # - manages the lifecycle of a RelatedEvents instance within that scope
+        # - silently ignores nested activations (re-entrant calls)
+        ...
+
+    def lazy[T](self, tp: type[T]) -> Callable[[], Awaitable[T]]:
+        # Ask the DI framework for a resolver for `tp`.
+        # The returned callable, when called and awaited, performs the resolution.
+        ...
+
+    def register_defaults(
+        self,
+        command_bus: Callable[..., CommandBus[Any]],
+        event_bus: Callable[..., EventBus],
+        query_bus: Callable[..., QueryBus[Any]],
+    ) -> None:
+        # Register the bus factories as default providers so that handlers
+        # can declare CommandBus, EventBus, or QueryBus as dependencies.
+        # This method is optional; the default implementation is a no-op.
+        ...
+
+    def wire[T](self, tp: type[T]) -> Callable[..., Awaitable[T]]:
+        # Return an async factory that instantiates `tp` with injected dependencies.
+        # Used internally to build handler instances.
+        ...
+
+
+cq = CQ(MyDIAdapter()).register_defaults()
+```

docs/guides/configuring.md

@@ -1,5 +1,8 @@
 # Configuring a Bus
 
+!!! note
+    This guide assumes the `[injection]` extra is installed.
+
 Each bus can be customized with listeners and middlewares. To do so, create a factory function decorated with `@injectable` that returns the configured bus.
 ```python
 from cq import CommandBus, MiddlewareResult, new_command_bus

docs/guides/dispatching.md

@@ -6,7 +6,7 @@ Each bus can take a generic parameter to specify the return type of the `dispatc
 
 ## Retrieving a bus
 
-Bus instances are available through [python-injection](https://github.com/100nm/python-injection)'s dependency injection:
+Bus instances are resolved through the configured DI adapter. When using the `[injection]` extra:
 
 ```python
 from cq import CommandBus

docs/guides/messages.md

@@ -30,7 +30,7 @@ class CreateUserHandler:
         ...
 ```
 
-All constructor dependencies are resolved at runtime by [python-injection](https://github.com/100nm/python-injection).
+All constructor dependencies are resolved at runtime by the configured DI adapter.
 
 ### Using NamedTuple for handlers
 

docs/guides/pipeline.md

@@ -15,6 +15,7 @@ class PaymentContext:
     transaction_id: int
 
     pipeline: ContextCommandPipeline[ValidateCartCommand] = ContextCommandPipeline()
+    # Optionally pass a custom DIAdapter: ContextCommandPipeline(my_di)
 
     @pipeline.step
     def _(self, result: CartValidatedResult) -> CreateTransactionCommand:

docs/index.md

@@ -3,7 +3,7 @@
 [![PyPI - Version](https://img.shields.io/pypi/v/python-cq.svg?color=4051b5&style=for-the-badge)](https://pypi.org/project/python-cq)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/python-cq.svg?color=4051b5&style=for-the-badge)](https://pypistats.org/packages/python-cq)
 
-**python-cq** is a Python package designed to organize your code following CQRS principles. It builds on top of [python-injection](https://github.com/100nm/python-injection) for dependency injection.
+**python-cq** is a Python package designed to organize your code following CQRS principles. It provides a `DIAdapter` protocol for dependency injection, with [python-injection](https://github.com/100nm/python-injection) as the default implementation available via the `[injection]` extra.
 
 ## What is CQRS?
 
@@ -35,6 +35,13 @@ This knowledge will help you design coherent handlers and organize your code eff
 ## Installation
 
 Requires Python 3.12 or higher.
+
+Without dependency injection:
 ```bash
 pip install python-cq
 ```
+
+With [python-injection](https://github.com/100nm/python-injection) as the DI backend (recommended):
+```bash
+pip install "python-cq[injection]"
+```

mkdocs.yml

@@ -21,6 +21,7 @@ nav:
       - Dispatching messages: guides/dispatching.md
       - Configuring a bus: guides/configuring.md
       - Executing multiple commands: guides/pipeline.md
+  - Custom DI: di.md
 
 plugins:
   - search