python-cq 0.17.0__tar.gz → 0.18.0__tar.gz

python_cq-0.18.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: python-cq
+Version: 0.18.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
+Author: remimd
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cqrs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Requires-Dist: anyio
+Requires-Dist: type-analyzer
+Provides-Extra: injection
+Requires-Dist: python-injection[async]; extra == 'injection'
+Description-Content-Type: text/markdown
+
+# python-cq
+
+[![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 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.
+
+## What is CQRS?
+
+CQRS (Command Query Responsibility Segregation) splits read operations from write operations. Each operation has a single, well-defined responsibility, which:
+
+* **clarifies intent**: a `CreateUserCommand` does one thing, and its name says so;
+* **keeps handlers small**: one message, one handler, easy to test in isolation;
+* **makes side effects explicit**: events fan out to subscribers without coupling the producer to them.
+
+CQRS is often discussed alongside distributed systems and Event Sourcing, but the pattern is just as useful in a local or monolithic application. The boundaries it draws are valuable on their own.
+
+## 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                  |
+
+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.
+
+## Installation
+
+Requires Python 3.12 or higher.
+
+With the default DI backend ([python-injection](https://github.com/100nm/python-injection), recommended):
+
+```bash
+pip install "python-cq[injection]"
+```
+
+Without dependency injection (you will need to implement a `DIAdapter`):
+
+```bash
+pip install python-cq
+```
+
+## Quickstart
+
+```python
+import asyncio
+from cq import CommandBus, command_handler
+from dataclasses import dataclass
+from injection import inject
+
+@dataclass
+class CreateUserCommand:
+    name: str
+    email: str
+
+@command_handler
+class CreateUserHandler:
+    async def handle(self, command: CreateUserCommand) -> int:
+        # ... persist the user, return its id
+        return 42
+
+@inject
+async def main(bus: CommandBus[int]) -> None:
+    command = CreateUserCommand(name="Ada", email="ada@example.com")
+    user_id = await bus.dispatch(command)
+    print(f"Created user {user_id}")
+
+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.
+
+## Prerequisites
+
+Familiarity with the following helps you get the most out of python-cq:
+
+* **CQRS**, in particular the distinction between Commands, Queries, and Events.
+* **Domain Driven Design (DDD)**, particularly aggregates and bounded contexts, which complement CQRS well.

{python_cq-0.17.0 → python_cq-0.18.0}/cq/__init__.py

@@ -1,9 +1,9 @@
 from ._core.cq import CQ
 from ._core.di import DIAdapter
 from ._core.di import NoDI as _NoDI
-from ._core.dispatcher.base import Dispatcher
-from ._core.dispatcher.bus import Bus
-from ._core.dispatcher.pipe import ContextPipeline, Pipe
+from ._core.dispatchers.abc import Dispatcher
+from ._core.dispatchers.bus import Bus
+from ._core.dispatchers.pipe import ContextPipeline, Pipe
 from ._core.message import (
     AnyCommandBus,
     Command,
@@ -15,6 +15,9 @@ from ._core.message import (
 )
 from ._core.middleware import Middleware, MiddlewareResult, resolve_handler_source
 from ._core.pipetools import ContextCommandPipeline as _ContextCommandPipeline
+from ._core.pump import Pump
+from ._core.queues.abc import Consumer, Producer, Queue
+from ._core.queues.memory import MemoryQueue
 from ._core.related_events import AnyIORelatedEvents, RelatedEvents
 
 __all__ = (
@@ -24,17 +27,22 @@ __all__ = (
     "CQ",
     "Command",
     "CommandBus",
+    "Consumer",
     "ContextCommandPipeline",
     "ContextPipeline",
     "DIAdapter",
     "Dispatcher",
     "Event",
     "EventBus",
+    "MemoryQueue",
     "Middleware",
     "MiddlewareResult",
     "Pipe",
+    "Producer",
+    "Pump",
     "Query",
     "QueryBus",
+    "Queue",
     "RelatedEvents",
     "command_handler",
     "event_handler",

{python_cq-0.17.0 → python_cq-0.18.0}/cq/_core/cq.py

@@ -1,7 +1,7 @@
 from typing import Any, Self
 
 from cq._core.di import DIAdapter
-from cq._core.dispatcher.bus import Bus, SimpleBus, TaskBus
+from cq._core.dispatchers.bus import Bus, SimpleBus, TaskBus
 from cq._core.handler import (
     HandlerDecorator,
     HandlerRegistry,

{python_cq-0.17.0 → python_cq-0.18.0}/cq/_core/di.py

@@ -5,7 +5,7 @@ from collections.abc import Awaitable, Callable
 from contextlib import nullcontext
 from typing import TYPE_CHECKING, Any, AsyncContextManager, Protocol, runtime_checkable
 
-if TYPE_CHECKING:
+if TYPE_CHECKING:  # pragma: no cover
     from cq import CommandBus, EventBus, QueryBus
 
 

python_cq-0.17.0/cq/_core/dispatcher/base.py → python_cq-0.18.0/cq/_core/dispatchers/abc.py

@@ -9,11 +9,11 @@ from cq._core.middleware import Middleware, MiddlewareGroup
 class Dispatcher[I, O](Protocol):
     __slots__ = ()
 
-    async def __call__(self, input_value: I, /) -> O:
-        return await self.dispatch(input_value)
+    async def __call__(self, message: I, /) -> O:
+        return await self.dispatch(message)
 
     @abstractmethod
-    async def dispatch(self, input_value: I, /) -> O:
+    async def dispatch(self, message: I, /) -> O:
         raise NotImplementedError
 
 
@@ -32,12 +32,12 @@ class BaseDispatcher[I, O](Dispatcher[I, O], ABC):
     async def _invoke_with_middlewares(
         self,
         handler: Callable[[I], Awaitable[O]],
-        input_value: I,
+        message: I,
         /,
         fail_silently: bool = False,
     ) -> O:
         try:
-            return await self.__middleware_group.invoke(handler, input_value)
+            return await self.__middleware_group.invoke(handler, message)
         except Exception:
             if fail_silently:
                 return NotImplemented

{python_cq-0.17.0/cq/_core/dispatcher → python_cq-0.18.0/cq/_core/dispatchers}/bus.py

@@ -5,7 +5,7 @@ from typing import Any, Protocol, Self, runtime_checkable
 import anyio
 from anyio.abc import TaskGroup
 
-from cq._core.dispatcher.base import BaseDispatcher, Dispatcher
+from cq._core.dispatchers.abc import BaseDispatcher, Dispatcher
 from cq._core.handler import (
     HandleFunction,
     HandlerFactory,
@@ -33,7 +33,7 @@ class Bus[I, O](Dispatcher[I, O], Protocol):
     @abstractmethod
     def subscribe(
         self,
-        input_type: type[I],
+        message_type: type[I],
         factory: HandlerFactory[[I], O],
         fail_silently: bool = ...,
     ) -> Self:
@@ -57,19 +57,19 @@ class BaseBus[I, O](BaseDispatcher[I, O], Bus[I, O], ABC):
 
     def subscribe(
         self,
-        input_type: type[I],
+        message_type: type[I],
         factory: HandlerFactory[[I], O],
         fail_silently: bool = False,
     ) -> Self:
-        self.__registry.subscribe(input_type, factory, fail_silently=fail_silently)
+        self.__registry.subscribe(message_type, factory, fail_silently=fail_silently)
         return self
 
-    def _handlers_from(self, input_type: type[I]) -> Iterator[HandleFunction[[I], O]]:
-        return self.__registry.handlers_from(input_type)
+    def _handlers_from(self, message_type: type[I]) -> Iterator[HandleFunction[[I], O]]:
+        return self.__registry.handlers_from(message_type)
 
-    def _trigger_listeners(self, input_value: I, /, task_group: TaskGroup) -> None:
+    def _trigger_listeners(self, message: I, /, task_group: TaskGroup) -> None:
         for listener in self.__listeners:
-            task_group.start_soon(listener, input_value)
+            task_group.start_soon(listener, message)
 
 
 class SimpleBus[I, O](BaseBus[I, O]):
@@ -78,14 +78,14 @@ class SimpleBus[I, O](BaseBus[I, O]):
     def __init__(self, registry: HandlerRegistry[I, O] | None = None, /) -> None:
         super().__init__(registry or SingleHandlerRegistry())
 
-    async def dispatch(self, input_value: I, /) -> O:
+    async def dispatch(self, message: I, /) -> O:
         async with anyio.create_task_group() as task_group:
-            self._trigger_listeners(input_value, task_group)
+            self._trigger_listeners(message, task_group)
 
-        for handler in self._handlers_from(type(input_value)):
+        for handler in self._handlers_from(type(message)):
             return await self._invoke_with_middlewares(
                 handler,
-                input_value,
+                message,
                 handler.fail_silently,
             )
 
@@ -98,14 +98,14 @@ class TaskBus[I](BaseBus[I, None]):
     def __init__(self, registry: HandlerRegistry[I, None] | None = None, /) -> None:
         super().__init__(registry or MultipleHandlerRegistry())
 
-    async def dispatch(self, input_value: I, /) -> None:
+    async def dispatch(self, message: I, /) -> None:
         async with anyio.create_task_group() as task_group:
-            self._trigger_listeners(input_value, task_group)
+            self._trigger_listeners(message, task_group)
 
-            for handler in self._handlers_from(type(input_value)):
+            for handler in self._handlers_from(type(message)):
                 task_group.start_soon(
                     self._invoke_with_middlewares,
                     handler,
-                    input_value,
+                    message,
                     handler.fail_silently,
                 )

{python_cq-0.17.0/cq/_core/dispatcher → python_cq-0.18.0/cq/_core/dispatchers}/lazy.py

@@ -3,7 +3,7 @@ from types import GenericAlias
 from typing import TypeAliasType
 
 from cq._core.di import DIAdapter
-from cq._core.dispatcher.base import Dispatcher
+from cq._core.dispatchers.abc import Dispatcher
 
 
 class LazyDispatcher[I, O](Dispatcher[I, O]):
@@ -19,6 +19,6 @@ class LazyDispatcher[I, O](Dispatcher[I, O]):
     ) -> None:
         self.__resolve = di.lazy(dispatcher_type)  # type: ignore[arg-type]
 
-    async def dispatch(self, input_value: I, /) -> O:
+    async def dispatch(self, message: I, /) -> O:
         dispatcher = await self.__resolve()
-        return await dispatcher.dispatch(input_value)
+        return await dispatcher.dispatch(message)

{python_cq-0.17.0/cq/_core/dispatcher → python_cq-0.18.0/cq/_core/dispatchers}/pipe.py

@@ -14,7 +14,7 @@ from typing import (
 )
 
 from cq._core.common.typing import Decorator, Method
-from cq._core.dispatcher.base import BaseDispatcher, Dispatcher
+from cq._core.dispatchers.abc import BaseDispatcher, Dispatcher
 from cq._core.middleware import Middleware, MiddlewareGroup
 
 type ConvertAsync[**P, I, O] = Callable[Concatenate[O, P], Awaitable[I]]
@@ -31,7 +31,7 @@ class PipelineConverter[**P, I, O](Protocol):
     __slots__ = ()
 
     @abstractmethod
-    async def convert(self, output_value: O, /, *args: P.args, **kwargs: P.kwargs) -> I:
+    async def convert(self, result: O, /, *args: P.args, **kwargs: P.kwargs) -> I:
         raise NotImplementedError
 
 
@@ -54,28 +54,24 @@ class PipelineSteps[**P, I, O]:
         self.__steps.append(PipelineStep(converter, dispatcher))
         return self
 
-    def add_static[T](
-        self,
-        input_value: T,
-        dispatcher: Dispatcher[T, Any] | None,
-    ) -> Self:
-        converter = _StaticPipelineConverter(input_value)
+    def add_static[T](self, message: T, dispatcher: Dispatcher[T, Any] | None) -> Self:
+        converter = _StaticPipelineConverter(message)
         self.add(converter, dispatcher)  # type: ignore[arg-type]
         return self
 
-    async def execute(self, input_value: I, /, *args: P.args, **kwargs: P.kwargs) -> O:
+    async def execute(self, message: I, /, *args: P.args, **kwargs: P.kwargs) -> O:
         dispatcher = self.default_dispatcher
 
         for step in self.__steps:
-            output_value = await dispatcher.dispatch(input_value)
-            input_value = await step.converter.convert(output_value, *args, **kwargs)
+            result = await dispatcher.dispatch(message)
+            message = await step.converter.convert(result, *args, **kwargs)
 
-            if input_value is None:
+            if message is None:
                 return NotImplemented
 
             dispatcher = step.dispatcher or self.default_dispatcher
 
-        return await dispatcher.dispatch(input_value)
+        return await dispatcher.dispatch(message)
 
 
 class Pipe[I, O](BaseDispatcher[I, O]):
@@ -136,15 +132,15 @@ class Pipe[I, O](BaseDispatcher[I, O]):
 
     def add_static_step[T](
         self,
-        input_value: T,
+        message: T,
         /,
         dispatcher: Dispatcher[T, Any] | None = None,
     ) -> Self:
-        self.__steps.add_static(input_value, dispatcher)
+        self.__steps.add_static(message, dispatcher)
         return self
 
-    async def dispatch(self, input_value: I, /) -> O:
-        return await self._invoke_with_middlewares(self.__steps.execute, input_value)
+    async def dispatch(self, message: I, /) -> O:
+        return await self._invoke_with_middlewares(self.__steps.execute, message)
 
 
 class ContextPipeline[I]:
@@ -199,11 +195,11 @@ class ContextPipeline[I]:
 
     def add_static_step[T](
         self,
-        input_value: T,
+        message: T,
         /,
         dispatcher: Dispatcher[T, Any] | None = None,
     ) -> Self:
-        self.__steps.add_static(input_value, dispatcher)
+        self.__steps.add_static(message, dispatcher)
         return self
 
     if TYPE_CHECKING:  # pragma: no cover
@@ -255,49 +251,49 @@ class ContextPipeline[I]:
 
     async def __execute[Context](
         self,
-        input_value: I,
+        message: I,
         /,
         *,
         context: Context,
         context_type: type[Context] | None,
     ) -> Context:
-        async def handler(i: I, /) -> Context:
-            await self.__steps.execute(i, context, context_type)
+        async def handler(first_message: I, /) -> Context:
+            await self.__steps.execute(first_message, context, context_type)
             return context
 
-        return await self.__middleware_group.invoke(handler, input_value)
+        return await self.__middleware_group.invoke(handler, message)
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class BoundContextPipeline[I, O](Dispatcher[I, O]):
     dispatch_method: Callable[[I], Awaitable[O]]
 
-    async def dispatch(self, input_value: I, /) -> O:
-        return await self.dispatch_method(input_value)
+    async def dispatch(self, message: I, /) -> O:
+        return await self.dispatch_method(message)
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class _AsyncPipelineConverter[**P, I, O](PipelineConverter[P, I, O]):
     converter: ConvertAsync[P, I, O]
 
-    async def convert(self, output_value: O, /, *args: P.args, **kwargs: P.kwargs) -> I:
-        return await self.converter(output_value, *args, **kwargs)
+    async def convert(self, result: O, /, *args: P.args, **kwargs: P.kwargs) -> I:
+        return await self.converter(result, *args, **kwargs)
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class _SyncPipelineConverter[**P, I, O](PipelineConverter[P, I, O]):
     converter: ConvertSync[P, I, O]
 
-    async def convert(self, output_value: O, /, *args: P.args, **kwargs: P.kwargs) -> I:
-        return self.converter(output_value, *args, **kwargs)
+    async def convert(self, result: O, /, *args: P.args, **kwargs: P.kwargs) -> I:
+        return self.converter(result, *args, **kwargs)
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class _StaticPipelineConverter[I](PipelineConverter[..., I, Any]):
-    input_value: I
+    message: I
 
-    async def convert(self, output_value: Any, /, *args: Any, **kwargs: Any) -> I:
-        return self.input_value
+    async def convert(self, result: Any, /, *args: Any, **kwargs: Any) -> I:
+        return self.message
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
@@ -308,13 +304,13 @@ class _AsyncContextPipelineConverter[I, O](
 
     async def convert(
         self,
-        output_value: O,
+        result: O,
         /,
         context: object,
         context_type: type | None,
     ) -> I:
         method = self.converter.__get__(context, context_type)
-        return await method(output_value)
+        return await method(result)
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
@@ -325,10 +321,10 @@ class _SyncContextPipelineConverter[I, O](
 
     async def convert(
         self,
-        output_value: O,
+        result: O,
         /,
         context: object,
         context_type: type | None,
     ) -> I:
         method = self.converter.__get__(context, context_type)
-        return method(output_value)
+        return method(result)

{python_cq-0.17.0 → python_cq-0.18.0}/cq/_core/handler.py

@@ -50,13 +50,13 @@ class HandlerRegistry[I, O](Protocol):
     __slots__ = ()
 
     @abstractmethod
-    def handlers_from(self, input_type: type[I]) -> Iterator[HandleFunction[[I], O]]:
+    def handlers_from(self, message_type: type[I]) -> Iterator[HandleFunction[[I], O]]:
         raise NotImplementedError
 
     @abstractmethod
     def subscribe(
         self,
-        input_type: type[I],
+        message_type: type[I],
         handler_factory: HandlerFactory[[I], O],
         handler_type: HandlerType[[I], O] | None = ...,
         fail_silently: bool = ...,
@@ -71,20 +71,20 @@ class MultipleHandlerRegistry[I, O](HandlerRegistry[I, O]):
         init=False,
     )
 
-    def handlers_from(self, input_type: type[I]) -> Iterator[HandleFunction[[I], O]]:
-        for key_type in _iter_key_types(input_type):
+    def handlers_from(self, message_type: type[I]) -> Iterator[HandleFunction[[I], O]]:
+        for key_type in _iter_key_types(message_type):
             yield from self.__values.get(key_type, ())
 
     def subscribe(
         self,
-        input_type: type[I],
+        message_type: type[I],
         handler_factory: HandlerFactory[[I], O],
         handler_type: HandlerType[[I], O] | None = None,
         fail_silently: bool = False,
     ) -> Self:
         function = HandleFunction.create(handler_factory, handler_type, fail_silently)
 
-        for key_type in _build_key_types(input_type):
+        for key_type in _build_key_types(message_type):
             self.__values[key_type].append(function)
 
         return self
@@ -97,26 +97,26 @@ class SingleHandlerRegistry[I, O](HandlerRegistry[I, O]):
         init=False,
     )
 
-    def handlers_from(self, input_type: type[I]) -> Iterator[HandleFunction[[I], O]]:
-        for key_type in _iter_key_types(input_type):
+    def handlers_from(self, message_type: type[I]) -> Iterator[HandleFunction[[I], O]]:
+        for key_type in _iter_key_types(message_type):
             function = self.__values.get(key_type, None)
             if function is not None:
                 yield function
 
     def subscribe(
         self,
-        input_type: type[I],
+        message_type: type[I],
         handler_factory: HandlerFactory[[I], O],
         handler_type: HandlerType[[I], O] | None = None,
         fail_silently: bool = False,
     ) -> Self:
         function = HandleFunction.create(handler_factory, handler_type, fail_silently)
-        entries = {key_type: function for key_type in _build_key_types(input_type)}
+        entries = {key_type: function for key_type in _build_key_types(message_type)}
 
         for key_type in entries:
             if key_type in self.__values:
                 raise RuntimeError(
-                    f"A handler is already registered for the input type: `{key_type}`."
+                    f"A handler is already registered for the message type: `{key_type}`."
                 )
 
         self.__values.update(entries)
@@ -133,7 +133,7 @@ class HandlerDecorator[I, O]:
         @overload
         def __call__(
             self,
-            input_or_handler_type: type[I],
+            message_or_handler_type: type[I],
             /,
             *,
             fail_silently: bool = ...,
@@ -142,7 +142,7 @@ class HandlerDecorator[I, O]:
         @overload
         def __call__[T](
             self,
-            input_or_handler_type: T,
+            message_or_handler_type: T,
             /,
             *,
             fail_silently: bool = ...,
@@ -151,7 +151,7 @@ class HandlerDecorator[I, O]:
         @overload
         def __call__(
             self,
-            input_or_handler_type: None = ...,
+            message_or_handler_type: None = ...,
             /,
             *,
             fail_silently: bool = ...,
@@ -159,24 +159,24 @@ class HandlerDecorator[I, O]:
 
     def __call__[T](
         self,
-        input_or_handler_type: type[I] | T | None = None,
+        message_or_handler_type: type[I] | T | None = None,
         /,
         *,
         fail_silently: bool = False,
     ) -> Any:
         if (
-            input_or_handler_type is not None
-            and isclass(input_or_handler_type)
-            and issubclass(input_or_handler_type, Handler)
+            message_or_handler_type is not None
+            and isclass(message_or_handler_type)
+            and issubclass(message_or_handler_type, Handler)
         ):
             return self.__decorator(
-                input_or_handler_type,
+                message_or_handler_type,
                 fail_silently=fail_silently,
             )
 
         return partial(
             self.__decorator,
-            input_type=input_or_handler_type,  # type: ignore[arg-type]
+            message_type=message_or_handler_type,  # type: ignore[arg-type]
             fail_silently=fail_silently,
         )
 
@@ -185,42 +185,42 @@ class HandlerDecorator[I, O]:
         wrapped: HandlerType[[I], O],
         /,
         *,
-        input_type: type[I] | None = None,
+        message_type: type[I] | None = None,
         fail_silently: bool = False,
     ) -> HandlerType[[I], O]:
         factory = self.di.wire(wrapped)
-        input_type = input_type or _resolve_input_type(wrapped)
-        self.registry.subscribe(input_type, factory, wrapped, fail_silently)
+        message_type = message_type or _resolve_message_type(wrapped)
+        self.registry.subscribe(message_type, factory, wrapped, fail_silently)
         return wrapped
 
 
-def _build_key_types(input_type: Any) -> tuple[Any, ...]:
+def _build_key_types(message_type: Any) -> tuple[Any, ...]:
     config = MatchingTypesConfig(ignore_none=True)
-    return matching_types(input_type, config)
+    return matching_types(message_type, config)
 
 
-def _iter_key_types(input_type: Any) -> Iterator[Any]:
+def _iter_key_types(message_type: Any) -> Iterator[Any]:
     config = MatchingTypesConfig(
         with_bases=True,
         with_origin=True,
         with_type_alias_value=True,
     )
-    return iter_matching_types(input_type, config)
+    return iter_matching_types(message_type, config)
 
 
-def _resolve_input_type[I, O](handler_type: HandlerType[[I], O]) -> type[I]:
+def _resolve_message_type[I, O](handler_type: HandlerType[[I], O]) -> type[I]:
     fake_method = handler_type.handle.__get__(NotImplemented, handler_type)
     signature = inspect_signature(fake_method, eval_str=True)
 
     for parameter in signature.parameters.values():
-        input_type = parameter.annotation
+        message_type = parameter.annotation
 
-        if input_type is Parameter.empty:
+        if message_type is Parameter.empty:
             break
 
-        return input_type
+        return message_type
 
     raise TypeError(
-        f"Unable to resolve input type for handler `{handler_type}`, "
+        f"Unable to resolve message type for handler `{handler_type}`, "
         "`handle` method must have a type annotation for its first parameter."
     )

{python_cq-0.17.0 → python_cq-0.18.0}/cq/_core/message.py

@@ -1,6 +1,6 @@
 from typing import Any
 
-from cq._core.dispatcher.base import Dispatcher
+from cq._core.dispatchers.abc import Dispatcher
 
 Command = object
 Event = object

{python_cq-0.17.0 → python_cq-0.18.0}/cq/_core/pipetools.py

@@ -3,8 +3,8 @@ from typing import TYPE_CHECKING, Any, Self, overload
 from cq import Dispatcher
 from cq._core.common.typing import Decorator
 from cq._core.di import DIAdapter
-from cq._core.dispatcher.lazy import LazyDispatcher
-from cq._core.dispatcher.pipe import (
+from cq._core.dispatchers.lazy import LazyDispatcher
+from cq._core.dispatchers.pipe import (
     ContextPipeline,
     ConvertMethod,
     ConvertMethodAsync,

python_cq-0.18.0/cq/_core/pump.py

@@ -0,0 +1,34 @@
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from typing import Any
+
+import anyio
+
+from cq._core.queues.abc import Consumer
+
+
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
+class Pump[T]:
+    consumer: Consumer[T]
+    dispatcher: Callable[[T], Awaitable[Any]]
+    fail_silently: bool = field(default=False)
+
+    async def drain(self) -> None:
+        async for message in self.consumer:
+            try:
+                await self.dispatcher(message)
+            except Exception:
+                if not self.fail_silently:
+                    raise
+
+    @asynccontextmanager
+    async def draining(self, /, *, graceful: bool = False) -> AsyncIterator[None]:
+        async with anyio.create_task_group() as task_group:
+            task_group.start_soon(self.drain)
+
+            try:
+                yield
+            finally:
+                if not graceful:
+                    task_group.cancel_scope.cancel()

python_cq-0.18.0/cq/_core/queues/abc.py

@@ -0,0 +1,29 @@
+from abc import abstractmethod
+from collections.abc import AsyncIterator
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Producer[T](Protocol):
+    __slots__ = ()
+
+    async def __call__(self, message: T, /) -> None:
+        return await self.send(message)
+
+    @abstractmethod
+    async def send(self, message: T, /) -> None:
+        raise NotImplementedError
+
+
+@runtime_checkable
+class Consumer[T](Protocol):
+    __slots__ = ()
+
+    @abstractmethod
+    def __aiter__(self) -> AsyncIterator[T]:
+        raise NotImplementedError
+
+
+@runtime_checkable
+class Queue[T](Producer[T], Consumer[T], Protocol):
+    __slots__ = ()

python_cq-0.18.0/cq/_core/queues/memory.py

@@ -0,0 +1,42 @@
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from typing import Any, Self
+
+import anyio
+from anyio.abc import ObjectReceiveStream, ObjectSendStream
+
+from cq._core.pump import Pump
+from cq._core.queues.abc import Queue
+
+
+class MemoryQueue[T](Queue[T]):
+    __slots__ = ("__consumer", "__producer")
+
+    __consumer: ObjectReceiveStream[T]
+    __producer: ObjectSendStream[T]
+
+    def __init__(self, maxsize: int = 0) -> None:
+        self.__producer, self.__consumer = anyio.create_memory_object_stream(maxsize)
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        return aiter(self.__consumer)
+
+    async def close(self) -> None:
+        await self.__producer.aclose()
+
+    @asynccontextmanager
+    async def draining(
+        self,
+        dispatcher: Callable[[T], Awaitable[Any]],
+        /,
+        *,
+        fail_silently: bool = False,
+    ) -> AsyncIterator[Self]:
+        async with Pump(self, dispatcher, fail_silently).draining(graceful=True):
+            try:
+                yield self
+            finally:
+                await self.close()
+
+    async def send(self, message: T, /) -> None:
+        await self.__producer.send(message)

{python_cq-0.17.0 → python_cq-0.18.0}/cq/_core/related_events.py

@@ -1,12 +1,13 @@
 from abc import abstractmethod
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from types import TracebackType
-from typing import Protocol, Self, runtime_checkable
+from typing import Any, Protocol, Self, runtime_checkable
 
 from anyio import create_task_group
 from anyio.abc import TaskGroup
 
-from cq._core.message import Event, EventBus
+from cq._core.message import Event
 
 
 @runtime_checkable
@@ -20,7 +21,7 @@ class RelatedEvents(Protocol):
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class AnyIORelatedEvents(RelatedEvents):
-    event_bus: EventBus
+    emit: Callable[[Event], Awaitable[Any]]
     task_group: TaskGroup = field(default_factory=create_task_group)
     history: list[Event] = field(default_factory=list, init=False)
 
@@ -41,7 +42,5 @@ class AnyIORelatedEvents(RelatedEvents):
 
     def add(self, *events: Event) -> None:
         self.history.extend(events)
-        dispatch_method = self.event_bus.dispatch
-
         for event in events:
-            self.task_group.start_soon(dispatch_method, event)
+            self.task_group.start_soon(self.emit, event)

python_cq-0.18.0/docs/index.md

@@ -0,0 +1,79 @@
+# python-cq
+
+[![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 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.
+
+## What is CQRS?
+
+CQRS (Command Query Responsibility Segregation) splits read operations from write operations. Each operation has a single, well-defined responsibility, which:
+
+* **clarifies intent**: a `CreateUserCommand` does one thing, and its name says so;
+* **keeps handlers small**: one message, one handler, easy to test in isolation;
+* **makes side effects explicit**: events fan out to subscribers without coupling the producer to them.
+
+CQRS is often discussed alongside distributed systems and Event Sourcing, but the pattern is just as useful in a local or monolithic application. The boundaries it draws are valuable on their own.
+
+## 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                  |
+
+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.
+
+## Installation
+
+Requires Python 3.12 or higher.
+
+With the default DI backend ([python-injection](https://github.com/100nm/python-injection), recommended):
+
+```bash
+pip install "python-cq[injection]"
+```
+
+Without dependency injection (you will need to implement a `DIAdapter`):
+
+```bash
+pip install python-cq
+```
+
+## Quickstart
+
+```python
+import asyncio
+from cq import CommandBus, command_handler
+from dataclasses import dataclass
+from injection import inject
+
+@dataclass
+class CreateUserCommand:
+    name: str
+    email: str
+
+@command_handler
+class CreateUserHandler:
+    async def handle(self, command: CreateUserCommand) -> int:
+        # ... persist the user, return its id
+        return 42
+
+@inject
+async def main(bus: CommandBus[int]) -> None:
+    command = CreateUserCommand(name="Ada", email="ada@example.com")
+    user_id = await bus.dispatch(command)
+    print(f"Created user {user_id}")
+
+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.
+
+## Prerequisites
+
+Familiarity with the following helps you get the most out of python-cq:
+
+* **CQRS**, in particular the distinction between Commands, Queries, and Events.
+* **Domain Driven Design (DDD)**, particularly aggregates and bounded contexts, which complement CQRS well.

{python_cq-0.17.0 → python_cq-0.18.0}/pyproject.toml

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

python_cq-0.17.0/PKG-INFO

@@ -1,78 +0,0 @@
-Metadata-Version: 2.4
-Name: python-cq
-Version: 0.17.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
-Author: remimd
-License-Expression: MIT
-License-File: LICENSE
-Keywords: cqrs
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Natural Language :: English
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
-Requires-Python: <3.15,>=3.12
-Requires-Dist: anyio
-Requires-Dist: type-analyzer
-Provides-Extra: injection
-Requires-Dist: python-injection[async]; extra == 'injection'
-Description-Content-Type: text/markdown
-
-# python-cq
-
-[![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 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?
-
-CQRS (Command Query Responsibility Segregation) is an architectural pattern that separates read operations from write operations. This separation helps to:
-
-- **Clarify intent**: each operation has a single, well-defined responsibility
-- **Improve maintainability**: smaller, focused handlers are easier to understand and modify
-- **Simplify testing**: isolated handlers are straightforward to unit test
-
-CQRS is often associated with distributed systems and Event Sourcing, but its benefits extend beyond that. Even in a local or monolithic application, adopting this pattern helps structure your code and makes the boundaries between reading and writing explicit.
-
-## Prerequisites
-
-To get the most out of **python-cq**, familiarity with the following concepts is recommended:
-
-- **CQRS** and the distinction between Commands, Queries and Events
-- **Domain Driven Design (DDD)**, particularly aggregates and bounded contexts
-
-This knowledge will help you design coherent handlers and organize your code effectively.
-
-## Message types
-
-**python-cq** provides three types of messages to model your application's operations:
-
-- **Command**: represents an intent to change the system's state. A command is handled by exactly one handler and may return a value for convenience.
-- **Query**: represents a request for information. A query is handled by exactly one handler and returns data without side effects.
-- **Event**: represents something that has happened in the system. An event can be handled by zero, one, or many handlers, enabling loose coupling between components.
-
-## 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]"
-```

python_cq-0.17.0/docs/index.md

@@ -1,47 +0,0 @@
-# python-cq
-
-[![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 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?
-
-CQRS (Command Query Responsibility Segregation) is an architectural pattern that separates read operations from write operations. This separation helps to:
-
-- **Clarify intent**: each operation has a single, well-defined responsibility
-- **Improve maintainability**: smaller, focused handlers are easier to understand and modify
-- **Simplify testing**: isolated handlers are straightforward to unit test
-
-CQRS is often associated with distributed systems and Event Sourcing, but its benefits extend beyond that. Even in a local or monolithic application, adopting this pattern helps structure your code and makes the boundaries between reading and writing explicit.
-
-## Prerequisites
-
-To get the most out of **python-cq**, familiarity with the following concepts is recommended:
-
-- **CQRS** and the distinction between Commands, Queries and Events
-- **Domain Driven Design (DDD)**, particularly aggregates and bounded contexts
-
-This knowledge will help you design coherent handlers and organize your code effectively.
-
-## Message types
-
-**python-cq** provides three types of messages to model your application's operations:
-
-- **Command**: represents an intent to change the system's state. A command is handled by exactly one handler and may return a value for convenience.
-- **Query**: represents a request for information. A query is handled by exactly one handler and returns data without side effects.
-- **Event**: represents something that has happened in the system. An event can be handled by zero, one, or many handlers, enabling loose coupling between components.
-
-## 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]"
-```