feat: ✨ Input type is now optional for HandlerDecorator

Author: remimd

cq/_core/handler.py

@@ -3,7 +3,8 @@
 from collections.abc import Awaitable, Callable, Iterator
 from dataclasses import dataclass, field
 from functools import partial
-from inspect import getmro, isclass
+from inspect import Parameter, getmro, isclass
+from inspect import signature as inspect_signature
 from typing import Any, Protocol, Self, runtime_checkable
 
 import injection
@@ -88,16 +89,50 @@ class HandlerDecorator[I, O]:
     manager: HandlerManager[I, O]
     injection_module: injection.Module = field(default_factory=injection.mod)
 
-    def __call__(self, input_type: type[I], /) -> Any:
-        def decorator(wrapped: type[Handler[[I], O]]) -> type[Handler[[I], O]]:
-            if not isclass(wrapped) or not issubclass(wrapped, Handler):
-                raise TypeError(f"`{wrapped}` isn't a valid handler.")
+    def __call__(
+        self,
+        input_or_handler_type: type[I] | HandlerType[[I], O] | None = None,
+        /,
+    ) -> Any:
+        if input_or_handler_type is None:
+            return self.__decorator
+
+        elif isclass(input_or_handler_type) and issubclass(
+            input_or_handler_type,
+            Handler,
+        ):
+            return self.__decorator(input_or_handler_type)
+
+        return partial(self.__decorator, input_type=input_or_handler_type)  # type: ignore[arg-type]
+
+    def __decorator(
+        self,
+        wrapped: HandlerType[[I], O],
+        *,
+        input_type: type[I] | None = None,
+    ) -> HandlerType[[I], O]:
+        factory = self.injection_module.make_async_factory(wrapped)
+        input_type = input_type or _resolve_input_type(wrapped)
+        self.manager.subscribe(input_type, factory)
+        return wrapped
 
-            factory = self.injection_module.make_async_factory(wrapped)
-            self.manager.subscribe(input_type, factory)
-            return wrapped
 
-        return decorator
+def _resolve_input_type[I, O](handler_type: HandlerType[[I], O]) -> type[I]:
+    fake_handle_method = handler_type.handle.__get__(NotImplemented)
+    signature = inspect_signature(fake_handle_method, eval_str=True)
+
+    for parameter in signature.parameters.values():
+        input_type = parameter.annotation
+
+        if input_type is Parameter.empty:
+            break
+
+        return input_type
+
+    raise TypeError(
+        f"Unable to resolve input type for handler `{handler_type}`, "
+        "`handle` method must have a type annotation for its first parameter."
+    )
 
 
 def _make_handle_function[I, O](
@@ -106,6 +141,6 @@ def _make_handle_function[I, O](
     return partial(__handle, factory=factory)
 
 
-async def __handle[I, O](input_value: I, factory: HandlerFactory[[I], O]) -> O:
+async def __handle[I, O](input_value: I, *, factory: HandlerFactory[[I], O]) -> O:
     handler = await factory()
     return await handler.handle(input_value)

cq/_core/message.py

@@ -36,7 +36,11 @@
 @injection.singleton(inject=False, mode="fallback")
 def new_command_bus() -> CommandBus:  # type: ignore[type-arg]
     bus = SimpleBus(command_handler.manager)
-    bus.add_middlewares(InjectionScopeMiddleware(CQScope.ON_COMMAND))
+    transaction_scope_middleware = InjectionScopeMiddleware(
+        CQScope.TRANSACTION,
+        exist_ok=True,
+    )
+    bus.add_middlewares(transaction_scope_middleware)
     return bus
 
 

cq/_core/related_events.py

@@ -23,18 +23,20 @@ def add(self, *events: Event) -> None:
 class SimpleRelatedEvents(RelatedEvents):
     items: list[Event] = field(default_factory=list)
 
+    def __bool__(self) -> bool:
+        return bool(self.items)
+
     def add(self, *events: Event) -> None:
         self.items.extend(events)
 
 
-@injection.scoped(CQScope.ON_COMMAND, mode="fallback")
+@injection.scoped(CQScope.TRANSACTION, mode="fallback")
 async def related_events_recipe(event_bus: EventBus) -> AsyncIterator[RelatedEvents]:
     yield (instance := SimpleRelatedEvents())
-    events = instance.items
 
-    if not events:
+    if not instance:
         return
 
     async with anyio.create_task_group() as task_group:
-        for event in events:
+        for event in instance.items:
             task_group.start_soon(event_bus.dispatch, event)

cq/_core/scope.py

@@ -2,4 +2,4 @@
 
 
 class CQScope(StrEnum):
-    ON_COMMAND = auto()
+    TRANSACTION = auto()

cq/middlewares/retry.py

@@ -1,4 +1,4 @@
-from collections.abc import Iterable
+from collections.abc import Sequence
 from typing import Any
 
 import anyio
@@ -19,7 +19,7 @@ def __init__(
         self,
         retry: int,
         delay: float = 0,
-        exceptions: Iterable[type[BaseException]] = (Exception,),
+        exceptions: Sequence[type[BaseException]] = (Exception,),
     ) -> None:
         self.__delay = delay
         self.__exceptions = tuple(exceptions)

cq/middlewares/scope.py

@@ -1,23 +1,32 @@
 from __future__ import annotations
 
+from contextlib import AsyncExitStack
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
 from injection import adefine_scope
+from injection.exceptions import ScopeAlreadyDefinedError
 
 if TYPE_CHECKING:  # pragma: no cover
     from cq import MiddlewareResult
 
 __all__ = ("InjectionScopeMiddleware",)
 
 
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
 class InjectionScopeMiddleware:
-    __slots__ = ("__scope_name",)
+    scope_name: str
+    exist_ok: bool = field(default=False, kw_only=True)
 
-    __scope_name: str
+    async def __call__(self, *args: Any, **kwargs: Any) -> MiddlewareResult[Any]:
+        async with AsyncExitStack() as stack:
+            try:
+                await stack.enter_async_context(
+                    adefine_scope(self.scope_name),
+                )
 
-    def __init__(self, scope_name: str) -> None:
-        self.__scope_name = scope_name
+            except ScopeAlreadyDefinedError:
+                if not self.exist_ok:
+                    raise
 
-    async def __call__(self, *args: Any, **kwargs: Any) -> MiddlewareResult[Any]:
-        async with adefine_scope(self.__scope_name):
             yield

documentation/fastapi-example.md

@@ -28,7 +28,7 @@ class ExampleCommand(BaseModel): ...
 
 class ExampleReturnType: ...
 
-@command_handler(ExampleCommand)
+@command_handler
 class ExampleHandler:
     def __init__(self, service: ExampleService) -> None:
         self.service = service

documentation/writing-application-layer.md

@@ -27,7 +27,7 @@ class UserProfileView:
 class ReadUserProfileQuery(msgspec.Struct, frozen=True):
     user_id: int
 
-@query_handler(ReadUserProfileQuery)
+@query_handler
 class ReadUserProfileHandler:
     async def handle(self, query: ReadUserProfileQuery) -> UserProfileView:
         """ User profile reading logic """
@@ -67,7 +67,7 @@ from cq import command_handler
 class UpdateUserProfileCommand:
     """ Data required to update user profile """
 
-@command_handler(UpdateUserProfileCommand)
+@command_handler
 class UpdateUserProfileHandler:
     async def handle(self, command: UpdateUserProfileCommand) -> None:
         """ User profile updating logic """
@@ -107,7 +107,7 @@ from cq import event_handler
 class UserRegistered:
     """ Data to process the event """
 
-@event_handler(UserRegistered)
+@event_handler
 class SendConfirmationEmailHandler:
     async def handle(self, event: UserRegistered) -> None:
         """ Confirmation email sending logic """
@@ -123,7 +123,7 @@ from cq import RelatedEvents, command_handler
 class UserRegistrationCommand:
     """ Data required to register a user """
 
-@command_handler(UserRegistrationCommand)
+@command_handler
 class UserRegistrationHandler:
     def __init__(self, related_events: RelatedEvents) -> None:
         self.related_events = related_events

tests/core/test_handler.py

@@ -0,0 +1,54 @@
+from typing import Any, NoReturn
+
+import pytest
+
+from cq._core.handler import HandlerDecorator, SingleHandlerManager
+
+
+class _Handler:
+    async def handle(self, input_value: str) -> NoReturn:
+        raise NotImplementedError
+
+
+class TestHandlerDecorator:
+    @pytest.fixture(scope="function")
+    def handler_decorator(self) -> HandlerDecorator[Any, Any]:
+        return HandlerDecorator(SingleHandlerManager())
+
+    def test_call_with_success_return_wrapped_type(
+        self,
+        handler_decorator: HandlerDecorator[Any, Any],
+    ) -> None:
+        assert handler_decorator(_Handler) is _Handler
+
+    def test_call_with_input_type_return_wrapped_type(
+        self,
+        handler_decorator: HandlerDecorator[Any, Any],
+    ) -> None:
+        assert handler_decorator(str)(_Handler) is _Handler
+
+    def test_call_with_no_args_return_wrapped_type(
+        self,
+        handler_decorator: HandlerDecorator[Any, Any],
+    ) -> None:
+        assert handler_decorator()(_Handler) is _Handler
+
+    def test_call_with_missing_input_type_annotation_raise_type_error(
+        self,
+        handler_decorator: HandlerDecorator[Any, Any],
+    ) -> None:
+        with pytest.raises(TypeError):
+
+            @handler_decorator
+            class Handler:
+                async def handle(self, input_value): ...  # type: ignore[no-untyped-def]
+
+    def test_call_with_missing_input_in_handle_raise_type_error(
+        self,
+        handler_decorator: HandlerDecorator[Any, Any],
+    ) -> None:
+        with pytest.raises(TypeError):
+
+            @handler_decorator
+            class Handler:
+                async def handle(self): ...  # type: ignore[no-untyped-def]

tests/test_command_bus.py

@@ -11,13 +11,13 @@ async def test_dispatch_with_related_events(
     ) -> None:
         class _Event: ...
 
-        @event_handler(_Event)
+        @event_handler
         class _EventHandler:
             async def handle(self, event: _Event) -> None: ...
 
         class _Command: ...
 
-        @command_handler(_Command)
+        @command_handler
         class _CommandHandler:
             def __init__(self, related_events: RelatedEvents) -> None:
                 self.related_events = related_events