python-cq 0.25.2__tar.gz → 0.27.0__tar.gz

{python_cq-0.25.2 → python_cq-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-cq
-Version: 0.25.2
+Version: 0.27.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
@@ -26,6 +26,7 @@ Classifier: Typing :: Typed
 Requires-Python: <3.16,>=3.12
 Requires-Dist: anyio
 Requires-Dist: type-analyzer
+Requires-Dist: typing-extensions; python_version < '3.13'
 Provides-Extra: injection
 Requires-Dist: python-injection[async]; extra == 'injection'
 Description-Content-Type: text/markdown
@@ -84,7 +85,8 @@ pip install python-cq
 
 ```python
 import asyncio
-from cq import CommandBus, command_handler
+from cq import CommandBus
+from cq.default import command_handler
 from dataclasses import dataclass
 from injection import inject
 

{python_cq-0.25.2 → python_cq-0.27.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
@@ -45,36 +50,7 @@ __all__ = (
     "Queue",
     "RelatedEvents",
     "Router",
-    "__router__",
-    "command_handler",
     "dispatch_sequentially",
-    "event_handler",
-    "new_command_bus",
-    "new_event_bus",
-    "new_query_bus",
-    "query_handler",
     "resolve_handler_source",
+    "through_middlewares",
 )
-
-
-try:
-    from .ext.injection import InjectionAdapter
-
-except ImportError:  # pragma: no cover
-    __router__ = Router()
-
-else:
-    __router__ = Router(InjectionAdapter())
-    del InjectionAdapter
-
-__router__.register_defaults()
-
-command_handler = __router__.command_handler
-event_handler = __router__.event_handler
-query_handler = __router__.query_handler
-
-new_command_bus = __router__.new_command_bus
-new_event_bus = __router__.new_event_bus
-new_query_bus = __router__.new_query_bus
-
-ContextCommandPipeline._set_default_di(__router__.di)

{python_cq-0.25.2 → python_cq-0.27.0}/cq/_core/middleware.py

@@ -1,9 +1,10 @@
 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
 
-from cq._core.routing.handler import HandleFunction, HandlerType
+from cq._core.routing.handler import HandlerEntry, HandlerType
 from cq.exceptions import MiddlewareError
 
 type MiddlewareResult[T] = AsyncGenerator[None, T]
@@ -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]]
@@ -66,15 +86,13 @@ class _BoundMiddleware[**P, T]:
 
 
 def resolve_handler_source[**P, T](
-    call_next: Callable[P, Awaitable[T]]
-    | _BoundMiddleware[P, T]
-    | HandleFunction[P, T],
+    call_next: Callable[P, Awaitable[T]] | _BoundMiddleware[P, T] | HandlerEntry[P, T],
     /,
 ) -> HandlerType[P, T] | Any:
     while isinstance(call_next, _BoundMiddleware):
         call_next = call_next.call_next
 
-    if isinstance(call_next, HandleFunction):
+    if isinstance(call_next, HandlerEntry):
         return call_next.source
 
     return call_next

{python_cq-0.25.2 → python_cq-0.27.0}/cq/_core/routing/command_pipeline.py

@@ -21,7 +21,14 @@ class ContextCommandPipeline[C: Command](ContextPipeline[C]):
     __default_di: ClassVar[DIAdapter]
 
     def __init__(self, di: DIAdapter | None = None, /) -> None:
-        di = di or self.__default_di
+        try:
+            di = di or self.__default_di
+        except AttributeError as exc:
+            raise RuntimeError(
+                "No DI adapter: import `cq.default` to use the default router, "
+                "or build the pipeline with `router.command_pipeline()`."
+            ) from exc
+
         super().__init__(LazyDispatcher(CommandBus, di))
         self.__query_dispatcher = LazyDispatcher(QueryBus, di)
 

{python_cq-0.25.2 → python_cq-0.27.0}/cq/_core/routing/dispatchers/bus.py

@@ -1,3 +1,4 @@
+import sys
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable, Iterator
 from typing import Any, Concatenate, Protocol, Self, runtime_checkable
@@ -8,13 +9,17 @@ from anyio.abc import TaskGroup
 from cq._core.middleware import Middleware
 from cq._core.routing.dispatchers.abc import BaseDispatcher, Dispatcher
 from cq._core.routing.handler import (
-    HandleFunction,
-    HandlerFactory,
+    HandlerEntry,
     HandlerRegistry,
     MultipleHandlerRegistry,
     SingleHandlerRegistry,
 )
 
+if sys.version_info >= (3, 13):  # pragma: no cover
+    from warnings import deprecated
+else:  # pragma: no cover
+    from typing_extensions import deprecated
+
 type Listener[T] = Callable[[T], Awaitable[Any]]
 
 
@@ -30,11 +35,16 @@ class Bus[I, O](Dispatcher[I, O], Protocol):
     def add_middlewares(self, *middlewares: Middleware[Concatenate[I, ...], O]) -> Self:
         raise NotImplementedError
 
+    @deprecated(
+        "`Bus.subscribe` is intended for tests, register handlers with the router "
+        "decorators (`command_handler`, `event_handler`, `query_handler`) instead.",
+        category=None,
+    )
     @abstractmethod
     def subscribe(
         self,
         message_type: type[I],
-        factory: HandlerFactory[Concatenate[I, ...], O],
+        function: Callable[Concatenate[I, ...], Awaitable[O]],
         fail_silently: bool = ...,
     ) -> Self:
         raise NotImplementedError
@@ -58,16 +68,19 @@ class BaseBus[I, O](BaseDispatcher[I, O], Bus[I, O], ABC):
     def subscribe(
         self,
         message_type: type[I],
-        factory: HandlerFactory[Concatenate[I, ...], O],
+        function: Callable[Concatenate[I, ...], Awaitable[O]],
         fail_silently: bool = False,
     ) -> Self:
-        self.__registry.subscribe(message_type, factory, fail_silently=fail_silently)
+        self.__registry.subscribe(
+            message_type,
+            HandlerEntry.from_function(function, fail_silently),
+        )
         return self
 
     def _handlers_from(
         self,
         message_type: type[I],
-    ) -> Iterator[HandleFunction[Concatenate[I, ...], O]]:
+    ) -> Iterator[HandlerEntry[Concatenate[I, ...], O]]:
         return self.__registry.handlers_from(message_type)
 
     def _trigger_listeners(self, message: I, /, task_group: TaskGroup) -> None:

{python_cq-0.25.2 → python_cq-0.27.0}/cq/_core/routing/handler.py

@@ -3,7 +3,7 @@ from collections import defaultdict
 from collections.abc import Awaitable, Callable, Iterator, KeysView
 from dataclasses import dataclass, field
 from functools import partial
-from inspect import Parameter, isclass, unwrap
+from inspect import Parameter, isclass, isfunction, unwrap
 from inspect import signature as inspect_signature
 from typing import (
     TYPE_CHECKING,
@@ -34,23 +34,43 @@ class Handler[**P, T](Protocol):
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
-class HandleFunction[**P, T]:
-    factory: HandlerFactory[P, T]
+class HandlerEntry[**P, T]:
+    function: Callable[P, Awaitable[T]]
     source: HandlerType[P, T] | Any
     fail_silently: bool
 
     async def __call__(self, /, *args: P.args, **kwargs: P.kwargs) -> T:
-        handler = await self.factory()
-        return await handler.handle(*args, **kwargs)
+        return await self.function(*args, **kwargs)
 
     @classmethod
-    def create(
+    def from_factory(
         cls,
         factory: HandlerFactory[P, T],
+        /,
         source: HandlerType[P, T] | None = None,
         fail_silently: bool = False,
     ) -> Self:
-        return cls(factory, source or unwrap(factory), fail_silently)
+        function = partial(cls.__handle_with, factory)
+        return cls(function, source or unwrap(factory), fail_silently)
+
+    @classmethod
+    def from_function(
+        cls,
+        function: Callable[P, Awaitable[T]],
+        /,
+        fail_silently: bool = False,
+    ) -> Self:
+        return cls(function, function, fail_silently)
+
+    @staticmethod
+    async def __handle_with(
+        factory: HandlerFactory[P, T],
+        /,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> T:
+        handler = await factory()
+        return await handler.handle(*args, **kwargs)
 
 
 @runtime_checkable
@@ -66,23 +86,21 @@ class HandlerRegistry[I, O](Protocol):
     def handlers_from(
         self,
         message_type: type[I],
-    ) -> Iterator[HandleFunction[Concatenate[I, ...], O]]:
+    ) -> Iterator[HandlerEntry[Concatenate[I, ...], O]]:
         raise NotImplementedError
 
     @abstractmethod
     def subscribe(
         self,
         message_type: type[I],
-        handler_factory: HandlerFactory[Concatenate[I, ...], O],
-        handler_type: HandlerType[Concatenate[I, ...], O] | None = ...,
-        fail_silently: bool = ...,
+        entry: HandlerEntry[Concatenate[I, ...], O],
     ) -> Self:
         raise NotImplementedError
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class MultipleHandlerRegistry[I, O](HandlerRegistry[I, O]):
-    __values: dict[type[I], list[HandleFunction[Concatenate[I, ...], O]]] = field(
+    __values: dict[type[I], list[HandlerEntry[Concatenate[I, ...], O]]] = field(
         default_factory=partial(defaultdict, list),
         init=False,
     )
@@ -94,28 +112,24 @@ class MultipleHandlerRegistry[I, O](HandlerRegistry[I, O]):
     def handlers_from(
         self,
         message_type: type[I],
-    ) -> Iterator[HandleFunction[Concatenate[I, ...], O]]:
+    ) -> Iterator[HandlerEntry[Concatenate[I, ...], O]]:
         for key_type in _iter_key_types(message_type):
             yield from self.__values.get(key_type, ())
 
     def subscribe(
         self,
         message_type: type[I],
-        handler_factory: HandlerFactory[Concatenate[I, ...], O],
-        handler_type: HandlerType[Concatenate[I, ...], O] | None = None,
-        fail_silently: bool = False,
+        entry: HandlerEntry[Concatenate[I, ...], O],
     ) -> Self:
-        function = HandleFunction.create(handler_factory, handler_type, fail_silently)
-
         for key_type in _build_key_types(message_type):
-            self.__values[key_type].append(function)
+            self.__values[key_type].append(entry)
 
         return self
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class SingleHandlerRegistry[I, O](HandlerRegistry[I, O]):
-    __values: dict[type[I], HandleFunction[Concatenate[I, ...], O]] = field(
+    __values: dict[type[I], HandlerEntry[Concatenate[I, ...], O]] = field(
         default_factory=dict,
         init=False,
     )
@@ -127,21 +141,18 @@ class SingleHandlerRegistry[I, O](HandlerRegistry[I, O]):
     def handlers_from(
         self,
         message_type: type[I],
-    ) -> Iterator[HandleFunction[Concatenate[I, ...], O]]:
+    ) -> Iterator[HandlerEntry[Concatenate[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
+            entry = self.__values.get(key_type, None)
+            if entry is not None:
+                yield entry
 
     def subscribe(
         self,
         message_type: type[I],
-        handler_factory: HandlerFactory[Concatenate[I, ...], O],
-        handler_type: HandlerType[Concatenate[I, ...], O] | None = None,
-        fail_silently: bool = False,
+        entry: HandlerEntry[Concatenate[I, ...], O],
     ) -> Self:
-        function = HandleFunction.create(handler_factory, handler_type, fail_silently)
-        entries = {key_type: function for key_type in _build_key_types(message_type)}
+        entries = {key_type: entry for key_type in _build_key_types(message_type)}
 
         for key_type in entries:
             if key_type in self.__values:
@@ -163,7 +174,7 @@ class HandlerDecorator[I, O]:
         @overload
         def __call__(
             self,
-            message_or_handler_type: type[I],
+            message_type: type[I],
             /,
             *,
             fail_silently: bool = ...,
@@ -172,7 +183,7 @@ class HandlerDecorator[I, O]:
         @overload
         def __call__[T](
             self,
-            message_or_handler_type: T,
+            handler: T,
             /,
             *,
             fail_silently: bool = ...,
@@ -181,7 +192,7 @@ class HandlerDecorator[I, O]:
         @overload
         def __call__(
             self,
-            message_or_handler_type: None = ...,
+            nothing: None = ...,
             /,
             *,
             fail_silently: bool = ...,
@@ -189,40 +200,55 @@ class HandlerDecorator[I, O]:
 
     def __call__[T](
         self,
-        message_or_handler_type: type[I] | T | None = None,
+        message_or_handler: type[I] | T | None = None,
         /,
         *,
         fail_silently: bool = False,
     ) -> Any:
-        if (
-            message_or_handler_type is not None
-            and isclass(message_or_handler_type)
-            and issubclass(message_or_handler_type, Handler)
-        ):
-            return self.__decorator(
-                message_or_handler_type,  # type: ignore[arg-type]
-                fail_silently=fail_silently,
-            )
+        if self.__try_subscribe(message_or_handler, None, fail_silently):
+            return message_or_handler
 
         return partial(
             self.__decorator,
-            message_type=message_or_handler_type,  # type: ignore[arg-type]
+            message_type=message_or_handler,  # type: ignore[arg-type]
             fail_silently=fail_silently,
         )
 
-    def __decorator(
+    def __decorator[T](
         self,
-        wrapped: HandlerType[Concatenate[I, ...], O],
+        wrapped: T,
         /,
         *,
-        message_type: type[I] | None = None,
-        fail_silently: bool = False,
-    ) -> HandlerType[Concatenate[I, ...], O]:
-        factory = self.di.wire(wrapped)
-        message_type = message_type or _resolve_message_type(wrapped)
-        self.registry.subscribe(message_type, factory, wrapped, fail_silently)
+        message_type: type[I] | None,
+        fail_silently: bool,
+    ) -> T:
+        if not self.__try_subscribe(wrapped, message_type, fail_silently):
+            raise TypeError(f"`{wrapped}` isn't a handler.")
+
         return wrapped
 
+    def __try_subscribe(
+        self,
+        handler: Any,
+        message_type: type[I] | None,
+        fail_silently: bool,
+    ) -> bool:
+        if isfunction(handler):
+            entry = HandlerEntry.from_function(handler, fail_silently)
+            callee = handler
+
+        elif isclass(handler) and issubclass(handler, Handler):
+            factory = self.di.wire(handler)
+            entry = HandlerEntry.from_factory(factory, handler, fail_silently)
+            callee = handler.handle.__get__(NotImplemented, handler)
+
+        else:
+            return False
+
+        message_type = message_type or _resolve_message_type(callee)
+        self.registry.subscribe(message_type, entry)
+        return True
+
 
 def _build_key_types(message_type: Any) -> tuple[Any, ...]:
     config = MatchingTypesConfig(ignore_none=True)
@@ -239,10 +265,9 @@ def _iter_key_types(message_type: Any) -> Iterator[Any]:
 
 
 def _resolve_message_type[I, O](
-    handler_type: HandlerType[Concatenate[I, ...], O],
+    handler: Callable[Concatenate[I, ...], Awaitable[O]],
 ) -> type[I]:
-    fake_method = handler_type.handle.__get__(NotImplemented, handler_type)
-    signature = inspect_signature(fake_method, eval_str=True)
+    signature = inspect_signature(handler, eval_str=True)
 
     for parameter in signature.parameters.values():
         message_type = parameter.annotation
@@ -253,6 +278,6 @@ def _resolve_message_type[I, O](
         return message_type
 
     raise TypeError(
-        f"Unable to resolve message type for handler `{handler_type}`, "
+        f"Unable to resolve message type for handler `{handler}`, "
         "`handle` method must have a type annotation for its first parameter."
     )

python_cq-0.27.0/cq/default.py

@@ -0,0 +1,37 @@
+from contextlib import suppress
+
+from ._core.routing.command_pipeline import ContextCommandPipeline
+from ._core.routing.di import DIAdapter
+from ._core.routing.router import Router
+
+__all__ = (
+    "command_handler",
+    "event_handler",
+    "new_command_bus",
+    "new_event_bus",
+    "new_query_bus",
+    "query_handler",
+    "router",
+)
+
+
+def __detect_di_adapter() -> DIAdapter | None:
+    with suppress(ImportError):
+        from .ext.injection import InjectionAdapter
+
+        return InjectionAdapter()
+
+    return None  # pragma: no cover
+
+
+router = Router(__detect_di_adapter()).register_defaults()
+
+command_handler = router.command_handler
+event_handler = router.event_handler
+query_handler = router.query_handler
+
+new_command_bus = router.new_command_bus
+new_event_bus = router.new_event_bus
+new_query_bus = router.new_query_bus
+
+ContextCommandPipeline._set_default_di(router.di)

{python_cq-0.25.2 → python_cq-0.27.0}/docs/index.md

@@ -52,7 +52,8 @@ pip install python-cq
 
 ```python
 import asyncio
-from cq import CommandBus, command_handler
+from cq import CommandBus
+from cq.default import command_handler
 from dataclasses import dataclass
 from injection import inject
 

{python_cq-0.25.2 → python_cq-0.27.0}/pyproject.toml

@@ -20,7 +20,7 @@ test = [
 
 [project]
 name = "python-cq"
-version = "0.25.2"
+version = "0.27.0"
 description = "CQRS library for async Python projects."
 license = "MIT"
 license-files = ["LICENSE"]
@@ -48,6 +48,7 @@ classifiers = [
 dependencies = [
     "anyio",
     "type-analyzer",
+    "typing-extensions; python_version < '3.13'",
 ]
 
 [project.optional-dependencies]