python-cq 0.25.1__tar.gz → 0.26.0__tar.gz

{python_cq-0.25.1 → python_cq-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-cq
-Version: 0.25.1
+Version: 0.26.0
 Summary: CQRS library for async Python projects.
 Project-URL: Documentation, https://python-cq.remimd.dev
 Project-URL: Repository, https://github.com/100nm/python-cq
@@ -35,7 +35,14 @@ Description-Content-Type: text/markdown
 [![PyPI - Version](https://shieldcn.dev/pypi/v/python-cq.svg?variant=secondary)](https://pypi.org/project/python-cq)
 [![PyPI - Downloads](https://shieldcn.dev/pypi/dm/python-cq.svg?variant=secondary)](https://pypistats.org/packages/python-cq)
 
-**python-cq** is an async-first Python library for organizing code around CQRS. It separates reads (queries), writes (commands), and notifications (events) into dedicated message buses, and lets you plug in any dependency injection framework behind a small protocol.
+**python-cq** is an async-first Python library for organizing code around CQRS. It routes commands, queries, and events to their handlers through dedicated buses, and lets you put a queue in front of any of them when a message should be processed later. Dependency injection is pluggable behind a small protocol.
+
+The library is made of two independent parts:
+
+* **Routing**: messages, handlers, buses, middlewares, and command pipelines. This is the core of the library and what most applications need.
+* **Queuing**: a `Queue` protocol and a `Pump` that drains a queue into any async callable, typically a bus.
+
+You can use routing without ever touching queuing, and the queuing primitives work with any dispatcher, not only the buses of this library.
 
 ## What is CQRS?
 
@@ -49,13 +56,13 @@ CQRS is often discussed alongside distributed systems and Event Sourcing, but th
 
 ## Three message types
 
-| Type      | Intent                                | Handlers              | Returns                  |
-|-----------|---------------------------------------|-----------------------|--------------------------|
-| `Command` | Change the state of the system        | Exactly one           | The handler's return value |
-| `Query`   | Read state without side effects       | Exactly one           | The handler's return value |
-| `Event`   | Notify that something has happened    | Zero, one, or many    | Nothing                  |
+| Type      | Intent                             | Handlers           | Returns                    |
+|-----------|------------------------------------|--------------------|----------------------------|
+| `Command` | Change the state of the system     | Exactly one        | The handler's return value |
+| `Query`   | Read state without side effects    | Exactly one        | The handler's return value |
+| `Event`   | Notify that something has happened | Zero, one, or many | Nothing                    |
 
-A `Command` is allowed to return a value (for convenience, typically an id or a result object), but that does not mean it should be used as a query. Keep intent clear.
+A `Command` is allowed to return a value (for convenience, typically an id or a result object), but that does not make it a query. Keep intent clear.
 
 ## Installation
 
@@ -67,7 +74,7 @@ With the default DI backend ([python-injection](https://github.com/100nm/python-
 pip install "python-cq[injection]"
 ```
 
-Without dependency injection (you will need to implement a `DIAdapter`):
+Without dependency injection (you will need to implement a `DIAdapter` to inject anything into your handlers):
 
 ```bash
 pip install python-cq
@@ -105,7 +112,7 @@ async def main(bus: CommandBus[int]) -> None:
 asyncio.run(main())
 ```
 
-The decorator registers the handler against the type of its first `handle` parameter. The bus is resolved by the DI container and dispatched to that handler.
+The decorator registers the handler against the type annotation of the first `handle` parameter. The bus is resolved by the DI container and forwards the command to that handler.
 
 ## Prerequisites
 

{python_cq-0.25.1 → python_cq-0.26.0}/cq/__init__.py

@@ -7,7 +7,12 @@ from ._core.message import (
     Query,
     QueryBus,
 )
-from ._core.middleware import Middleware, MiddlewareResult, resolve_handler_source
+from ._core.middleware import (
+    Middleware,
+    MiddlewareResult,
+    resolve_handler_source,
+    through_middlewares,
+)
 from ._core.queuing.pump import Pump
 from ._core.queuing.queues.abc import Consumer, Delivery, Producer, Queue
 from ._core.queuing.queues.memory import MemoryQueue
@@ -54,6 +59,7 @@ __all__ = (
     "new_query_bus",
     "query_handler",
     "resolve_handler_source",
+    "through_middlewares",
 )
 
 

{python_cq-0.25.1 → python_cq-0.26.0}/cq/_core/middleware.py

@@ -1,5 +1,6 @@
 from collections.abc import AsyncGenerator, Awaitable, Callable
 from dataclasses import dataclass, field
+from functools import wraps
 from inspect import isasyncgenfunction
 from typing import Any, Concatenate, Self, TypeGuard
 
@@ -23,6 +24,13 @@ class MiddlewareGroup[**P, T]:
         init=False,
     )
 
+    def __call__(self, wrapped: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+        @wraps(wrapped)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            return await self.invoke(wrapped, *args, **kwargs)
+
+        return wrapper
+
     def add(self, *middlewares: Middleware[P, T]) -> Self:
         classic_middlewares = reversed(
             tuple(self.__normalize(middleware) for middleware in middlewares)
@@ -48,6 +56,10 @@ class MiddlewareGroup[**P, T]:
 
         return handler
 
+    @classmethod
+    def from_middlewares(cls, *middlewares: Middleware[P, T]) -> Self:
+        return cls().add(*middlewares)
+
     @staticmethod
     def __normalize(middleware: Middleware[P, T]) -> ClassicMiddleware[P, T]:
         if _is_gen_middleware(middleware):
@@ -56,6 +68,14 @@ class MiddlewareGroup[**P, T]:
         return middleware  # type: ignore[return-value]
 
 
+def through_middlewares[**P, T](
+    first_middleware: Middleware[P, T],
+    /,
+    *middlewares: Middleware[P, T],
+) -> MiddlewareGroup[P, T]:
+    return MiddlewareGroup.from_middlewares(first_middleware, *middlewares)
+
+
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class _BoundMiddleware[**P, T]:
     call_next: Callable[P, Awaitable[T]]
@@ -71,11 +91,13 @@ def resolve_handler_source[**P, T](
     | HandleFunction[P, T],
     /,
 ) -> HandlerType[P, T] | Any:
-    while True:
-        try:
-            call_next = call_next.call_next  # type: ignore[union-attr]
-        except AttributeError:
-            return call_next.source  # type: ignore[union-attr]
+    while isinstance(call_next, _BoundMiddleware):
+        call_next = call_next.call_next
+
+    if isinstance(call_next, HandleFunction):
+        return call_next.source
+
+    return call_next
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)

{python_cq-0.25.1 → python_cq-0.26.0}/docs/index.md

@@ -3,7 +3,14 @@
 [![PyPI - Version](https://shieldcn.dev/pypi/v/python-cq.svg?variant=secondary)](https://pypi.org/project/python-cq)
 [![PyPI - Downloads](https://shieldcn.dev/pypi/dm/python-cq.svg?variant=secondary)](https://pypistats.org/packages/python-cq)
 
-**python-cq** is an async-first Python library for organizing code around CQRS. It separates reads (queries), writes (commands), and notifications (events) into dedicated message buses, and lets you plug in any dependency injection framework behind a small protocol.
+**python-cq** is an async-first Python library for organizing code around CQRS. It routes commands, queries, and events to their handlers through dedicated buses, and lets you put a queue in front of any of them when a message should be processed later. Dependency injection is pluggable behind a small protocol.
+
+The library is made of two independent parts:
+
+* **Routing**: messages, handlers, buses, middlewares, and command pipelines. This is the core of the library and what most applications need.
+* **Queuing**: a `Queue` protocol and a `Pump` that drains a queue into any async callable, typically a bus.
+
+You can use routing without ever touching queuing, and the queuing primitives work with any dispatcher, not only the buses of this library.
 
 ## What is CQRS?
 
@@ -17,13 +24,13 @@ CQRS is often discussed alongside distributed systems and Event Sourcing, but th
 
 ## Three message types
 
-| Type      | Intent                                | Handlers              | Returns                  |
-|-----------|---------------------------------------|-----------------------|--------------------------|
-| `Command` | Change the state of the system        | Exactly one           | The handler's return value |
-| `Query`   | Read state without side effects       | Exactly one           | The handler's return value |
-| `Event`   | Notify that something has happened    | Zero, one, or many    | Nothing                  |
+| Type      | Intent                             | Handlers           | Returns                    |
+|-----------|------------------------------------|--------------------|----------------------------|
+| `Command` | Change the state of the system     | Exactly one        | The handler's return value |
+| `Query`   | Read state without side effects    | Exactly one        | The handler's return value |
+| `Event`   | Notify that something has happened | Zero, one, or many | Nothing                    |
 
-A `Command` is allowed to return a value (for convenience, typically an id or a result object), but that does not mean it should be used as a query. Keep intent clear.
+A `Command` is allowed to return a value (for convenience, typically an id or a result object), but that does not make it a query. Keep intent clear.
 
 ## Installation
 
@@ -35,7 +42,7 @@ With the default DI backend ([python-injection](https://github.com/100nm/python-
 pip install "python-cq[injection]"
 ```
 
-Without dependency injection (you will need to implement a `DIAdapter`):
+Without dependency injection (you will need to implement a `DIAdapter` to inject anything into your handlers):
 
 ```bash
 pip install python-cq
@@ -73,7 +80,7 @@ async def main(bus: CommandBus[int]) -> None:
 asyncio.run(main())
 ```
 
-The decorator registers the handler against the type of its first `handle` parameter. The bus is resolved by the DI container and dispatched to that handler.
+The decorator registers the handler against the type annotation of the first `handle` parameter. The bus is resolved by the DI container and forwards the command to that handler.
 
 ## Prerequisites
 

{python_cq-0.25.1 → python_cq-0.26.0}/pyproject.toml

@@ -20,7 +20,7 @@ test = [
 
 [project]
 name = "python-cq"
-version = "0.25.1"
+version = "0.26.0"
 description = "CQRS library for async Python projects."
 license = "MIT"
 license-files = ["LICENSE"]