python-cq 0.15.2__tar.gz → 0.16.0__tar.gz

{python_cq-0.15.2 → python_cq-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cq
-Version: 0.15.2
+Version: 0.16.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
@@ -24,8 +24,9 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.12
 Requires-Dist: anyio
-Requires-Dist: python-injection
 Requires-Dist: type-analyzer
+Provides-Extra: injection
+Requires-Dist: python-injection[async]; extra == 'injection'
 Description-Content-Type: text/markdown
 
 # python-cq
@@ -33,7 +34,7 @@ Description-Content-Type: text/markdown
 [![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?
 
@@ -65,6 +66,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]"
+```

python_cq-0.16.0/cq/__init__.py

@@ -0,0 +1,75 @@
+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.message import (
+    AnyCommandBus,
+    Command,
+    CommandBus,
+    Event,
+    EventBus,
+    Query,
+    QueryBus,
+)
+from ._core.middleware import Middleware, MiddlewareResult, resolve_handler_source
+from ._core.pipetools import ContextCommandPipeline as _ContextCommandPipeline
+from ._core.related_events import AnyIORelatedEvents, RelatedEvents
+
+__all__ = (
+    "AnyCommandBus",
+    "AnyIORelatedEvents",
+    "Bus",
+    "CQ",
+    "Command",
+    "CommandBus",
+    "ContextCommandPipeline",
+    "ContextPipeline",
+    "DIAdapter",
+    "Dispatcher",
+    "Event",
+    "EventBus",
+    "Middleware",
+    "MiddlewareResult",
+    "Pipe",
+    "Query",
+    "QueryBus",
+    "RelatedEvents",
+    "command_handler",
+    "event_handler",
+    "new_command_bus",
+    "new_event_bus",
+    "new_query_bus",
+    "query_handler",
+    "resolve_handler_source",
+)
+
+try:
+    from cq.ext.injection import InjectionAdapter as _InjectionAdapter
+
+except ImportError:  # pragma: no cover
+    _default = CQ(_NoDI())
+
+else:
+    _default = CQ(_InjectionAdapter())
+
+_default.register_defaults()
+
+command_handler = _default.command_handler
+event_handler = _default.event_handler
+query_handler = _default.query_handler
+
+new_command_bus = _default.new_command_bus
+new_event_bus = _default.new_event_bus
+new_query_bus = _default.new_query_bus
+
+
+class ContextCommandPipeline[C: Command](_ContextCommandPipeline[C]):
+    __slots__ = ()
+
+    def __init__(self, di: DIAdapter = _default.di) -> None:
+        super().__init__(di)
+
+
+del _default

python_cq-0.16.0/cq/_core/cq.py

@@ -0,0 +1,63 @@
+from typing import Any, Self
+
+from cq._core.di import DIAdapter
+from cq._core.dispatcher.bus import Bus, SimpleBus, TaskBus
+from cq._core.handler import (
+    HandlerDecorator,
+    HandlerRegistry,
+    MultipleHandlerRegistry,
+    SingleHandlerRegistry,
+)
+from cq._core.message import Command, Event, Query
+from cq._core.middlewares.scope import CommandDispatchScopeMiddleware
+
+
+class CQ:
+    __slots__ = ("__command_registry", "__di", "__event_registry", "__query_registry")
+
+    __command_registry: HandlerRegistry[Command, Any]
+    __di: DIAdapter
+    __event_registry: HandlerRegistry[Event, Any]
+    __query_registry: HandlerRegistry[Query, Any]
+
+    def __init__(self, di: DIAdapter, /) -> None:
+        self.__di = di
+        self.__command_registry = SingleHandlerRegistry()
+        self.__event_registry = MultipleHandlerRegistry()
+        self.__query_registry = SingleHandlerRegistry()
+
+    @property
+    def di(self) -> DIAdapter:
+        return self.__di
+
+    @property
+    def command_handler(self) -> HandlerDecorator[Command, Any]:
+        return HandlerDecorator(self.__command_registry, self.__di)
+
+    @property
+    def event_handler(self) -> HandlerDecorator[Event, Any]:
+        return HandlerDecorator(self.__event_registry, self.__di)
+
+    @property
+    def query_handler(self) -> HandlerDecorator[Query, Any]:
+        return HandlerDecorator(self.__query_registry, self.__di)
+
+    def new_command_bus(self) -> Bus[Command, Any]:
+        bus = SimpleBus(self.__command_registry)
+        command_middleware = CommandDispatchScopeMiddleware(self.__di)
+        bus.add_middlewares(command_middleware)
+        return bus
+
+    def new_event_bus(self) -> Bus[Event, None]:
+        return TaskBus(self.__event_registry)
+
+    def new_query_bus(self) -> Bus[Query, Any]:
+        return SimpleBus(self.__query_registry)
+
+    def register_defaults(self) -> Self:
+        self.__di.register_defaults(
+            self.new_command_bus,
+            self.new_event_bus,
+            self.new_query_bus,
+        )
+        return self

python_cq-0.16.0/cq/_core/di.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Awaitable, Callable
+from contextlib import nullcontext
+from typing import TYPE_CHECKING, Any, AsyncContextManager, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from cq import CommandBus, EventBus, QueryBus
+
+
+@runtime_checkable
+class DIAdapter(Protocol):
+    """
+    Protocol for integrating a dependency injection container with python-cq.
+
+    Implement this protocol to connect your DI framework to the CQ buses.
+    A concrete implementation (``InjectionAdapter``) is provided via the
+    ``python-cq[injection]`` extra for projects that use *python-injection*.
+    """
+
+    __slots__ = ()
+
+    @abstractmethod
+    def command_scope(self) -> AsyncContextManager[None]:
+        """
+        Return an async context manager that delimits the lifetime of a
+        command dispatch.
+
+        **Responsibilities**
+
+        The scope must at minimum manage the lifecycle of a ``RelatedEvents``
+        instance and register it so that it is resolvable via injection for
+        the duration of the scope.
+
+        **Nested calls**
+
+        ``command_scope`` is entered in two distinct situations:
+
+        1. Around a standard command dispatch (via
+           ``CommandDispatchScopeMiddleware``).
+        2. Around each step of a ``ContextCommandPipeline``, which itself
+           wraps a command dispatch.
+
+        This means two nested calls can occur for a single logical command.
+        Implementations must detect re-entrant activation (e.g. a scope
+        already active on the current task) and silently ignore the inner
+        call instead of opening a second, conflicting scope.
+        """
+
+        raise NotImplementedError
+
+    @abstractmethod
+    def lazy[T](self, tp: type[T]) -> Callable[[], Awaitable[T]]:
+        """
+        Return a callable that resolves an instance of ``tp`` in two steps.
+
+        1. ``lazy(tp)`` obtains a resolver from the DI framework for ``tp``.
+        2. Calling and awaiting the returned callable performs the actual
+           resolution and returns the instance.
+        """
+
+        raise NotImplementedError
+
+    def register_defaults(
+        self,
+        command_bus: Callable[..., CommandBus[Any]],
+        event_bus: Callable[..., EventBus],
+        query_bus: Callable[..., QueryBus[Any]],
+    ) -> None:
+        """
+        Register the CQ buses as default providers in the DI container.
+
+        Called once during setup so that handlers and middlewares can
+        declare ``CommandBus``, ``EventBus``, or ``QueryBus`` as
+        constructor dependencies and receive the configured instances.
+
+        The default implementation is a no-op for adapters that do not
+        need automatic bus registration.
+        """
+
+        return
+
+    @abstractmethod
+    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 whose dependencies are
+        resolved by the container.
+        """
+
+        raise NotImplementedError
+
+
+class NoDI(DIAdapter):
+    __slots__ = ()
+
+    def command_scope(self) -> AsyncContextManager[None]:
+        return nullcontext()
+
+    def lazy[T](self, tp: type[T], /) -> Callable[[], Awaitable[T]]:
+        tp_str = getattr(tp, "__name__", str(tp))
+        raise RuntimeError(
+            f"Can't lazily resolve {tp_str}: no DI container configured."
+        )
+
+    def wire[T](self, tp: type[T], /) -> Callable[..., Awaitable[T]]:
+        async def factory() -> T:
+            return tp()
+
+        return factory

{python_cq-0.15.2 → python_cq-0.16.0}/cq/_core/dispatcher/base.py

@@ -15,15 +15,6 @@ class Dispatcher[I, O](Protocol):
         raise NotImplementedError
 
 
-@runtime_checkable
-class DeferredDispatcher[I](Protocol):
-    __slots__ = ()
-
-    @abstractmethod
-    async def defer(self, input_value: I, /) -> None:
-        raise NotImplementedError
-
-
 class BaseDispatcher[I, O](Dispatcher[I, O], ABC):
     __slots__ = ("__middleware_group",)
 

python_cq-0.16.0/cq/_core/dispatcher/lazy.py

@@ -0,0 +1,24 @@
+from collections.abc import Awaitable, Callable
+from types import GenericAlias
+from typing import TypeAliasType
+
+from cq._core.di import DIAdapter
+from cq._core.dispatcher.base import Dispatcher
+
+
+class LazyDispatcher[I, O](Dispatcher[I, O]):
+    __slots__ = ("__resolve",)
+
+    __resolve: Callable[[], Awaitable[Dispatcher[I, O]]]
+
+    def __init__(
+        self,
+        dispatcher_type: type[Dispatcher[I, O]] | TypeAliasType | GenericAlias,
+        /,
+        di: DIAdapter,
+    ) -> None:
+        self.__resolve = di.lazy(dispatcher_type)  # type: ignore[arg-type]
+
+    async def dispatch(self, input_value: I, /) -> O:
+        dispatcher = await self.__resolve()
+        return await dispatcher.dispatch(input_value)

{python_cq-0.15.2 → python_cq-0.16.0}/cq/_core/handler.py

@@ -7,10 +7,10 @@ from inspect import Parameter, isclass, unwrap
 from inspect import signature as inspect_signature
 from typing import TYPE_CHECKING, Any, Protocol, Self, overload, runtime_checkable
 
-import injection
 from type_analyzer import MatchingTypesConfig, iter_matching_types, matching_types
 
 from cq._core.common.typing import Decorator
+from cq._core.di import DIAdapter, NoDI
 
 type HandlerType[**P, T] = type[Handler[P, T]]
 type HandlerFactory[**P, T] = Callable[..., Awaitable[Handler[P, T]]]
@@ -126,7 +126,7 @@ class SingleHandlerRegistry[I, O](HandlerRegistry[I, O]):
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class HandlerDecorator[I, O]:
     registry: HandlerRegistry[I, O]
-    injection_module: injection.Module = field(default_factory=injection.mod)
+    di: DIAdapter = field(default_factory=NoDI)
 
     if TYPE_CHECKING:  # pragma: no cover
 
@@ -137,7 +137,6 @@ class HandlerDecorator[I, O]:
             /,
             *,
             fail_silently: bool = ...,
-            threadsafe: bool | None = ...,
         ) -> Decorator: ...
 
         @overload
@@ -147,7 +146,6 @@ class HandlerDecorator[I, O]:
             /,
             *,
             fail_silently: bool = ...,
-            threadsafe: bool | None = ...,
         ) -> T: ...
 
         @overload
@@ -157,7 +155,6 @@ class HandlerDecorator[I, O]:
             /,
             *,
             fail_silently: bool = ...,
-            threadsafe: bool | None = ...,
         ) -> Decorator: ...
 
     def __call__[T](
@@ -166,7 +163,6 @@ class HandlerDecorator[I, O]:
         /,
         *,
         fail_silently: bool = False,
-        threadsafe: bool | None = None,
     ) -> Any:
         if (
             input_or_handler_type is not None
@@ -176,14 +172,12 @@ class HandlerDecorator[I, O]:
             return self.__decorator(
                 input_or_handler_type,
                 fail_silently=fail_silently,
-                threadsafe=threadsafe,
             )
 
         return partial(
             self.__decorator,
             input_type=input_or_handler_type,  # type: ignore[arg-type]
             fail_silently=fail_silently,
-            threadsafe=threadsafe,
         )
 
     def __decorator(
@@ -193,9 +187,8 @@ class HandlerDecorator[I, O]:
         *,
         input_type: type[I] | None = None,
         fail_silently: bool = False,
-        threadsafe: bool | None = None,
     ) -> HandlerType[[I], O]:
-        factory = self.injection_module.make_async_factory(wrapped, threadsafe)
+        factory = self.di.wire(wrapped)
         input_type = input_type or _resolve_input_type(wrapped)
         self.registry.subscribe(input_type, factory, wrapped, fail_silently)
         return wrapped

python_cq-0.16.0/cq/_core/message.py

@@ -0,0 +1,13 @@
+from typing import Any
+
+from cq._core.dispatcher.base import Dispatcher
+
+Command = object
+Event = object
+Query = object
+
+type CommandBus[T] = Dispatcher[Command, T]
+type EventBus = Dispatcher[Event, None]
+type QueryBus[T] = Dispatcher[Query, T]
+
+AnyCommandBus = CommandBus[Any]

{python_cq-0.15.2 → python_cq-0.16.0}/cq/_core/middleware.py

@@ -9,7 +9,8 @@ from cq.exceptions import MiddlewareError
 type MiddlewareResult[T] = AsyncGenerator[None, T]
 type GeneratorMiddleware[**P, T] = Callable[P, MiddlewareResult[T]]
 type ClassicMiddleware[**P, T] = Callable[
-    Concatenate[Callable[P, Awaitable[T]], P], Awaitable[T]
+    Concatenate[Callable[P, Awaitable[T]], P],
+    Awaitable[T],
 ]
 
 type Middleware[**P, T] = ClassicMiddleware[P, T] | GeneratorMiddleware[P, T]

python_cq-0.16.0/cq/_core/middlewares/scope.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+from typing import Any
+
+from cq._core.di import DIAdapter
+from cq._core.middleware import MiddlewareResult
+
+
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
+class CommandDispatchScopeMiddleware:
+    di: DIAdapter
+
+    async def __call__(self, /, *args: Any, **kwargs: Any) -> MiddlewareResult[Any]:
+        async with self.di.command_scope():
+            yield

python_cq-0.16.0/cq/_core/pipetools.py

@@ -0,0 +1,52 @@
+from typing import TYPE_CHECKING, Any, 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 (
+    ContextPipeline,
+    ConvertMethod,
+    ConvertMethodAsync,
+    ConvertMethodSync,
+)
+from cq._core.message import Command, CommandBus, Query, QueryBus
+from cq._core.middlewares.scope import CommandDispatchScopeMiddleware
+
+
+class ContextCommandPipeline[C: Command](ContextPipeline[C]):
+    __slots__ = ("__query_dispatcher",)
+
+    __query_dispatcher: Dispatcher[Query, Any]
+
+    def __init__(self, di: DIAdapter) -> None:
+        super().__init__(LazyDispatcher(CommandBus, di))
+        self.__query_dispatcher = LazyDispatcher(QueryBus, di)
+        command_middleware = CommandDispatchScopeMiddleware(di)
+        self.add_middlewares(command_middleware)
+
+    if TYPE_CHECKING:  # pragma: no cover
+
+        @overload
+        def query_step[Q: Query](
+            self,
+            wrapped: ConvertMethodAsync[Q, Any],
+            /,
+        ) -> ConvertMethodAsync[Q, Any]: ...
+
+        @overload
+        def query_step[Q: Query](
+            self,
+            wrapped: ConvertMethodSync[Q, Any],
+            /,
+        ) -> ConvertMethodSync[Q, Any]: ...
+
+        @overload
+        def query_step(self, wrapped: None = ..., /) -> Decorator: ...
+
+    def query_step[Q: Query](  # type: ignore[misc]
+        self,
+        wrapped: ConvertMethod[Q, Any] | None = None,
+        /,
+    ) -> Any:
+        return self.step(wrapped, dispatcher=self.__query_dispatcher)

{python_cq-0.15.2 → python_cq-0.16.0}/cq/_core/related_events.py

@@ -1,14 +1,12 @@
 from abc import abstractmethod
-from collections.abc import AsyncIterator
 from dataclasses import dataclass, field
-from typing import Protocol, runtime_checkable
+from types import TracebackType
+from typing import Any, Protocol, Self, runtime_checkable
 
-import anyio
-import injection
+from anyio import create_task_group
 from anyio.abc import TaskGroup
 
 from cq._core.message import Event, EventBus
-from cq._core.scope import CQScope
 
 
 @runtime_checkable
@@ -23,21 +21,27 @@ class RelatedEvents(Protocol):
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class AnyIORelatedEvents(RelatedEvents):
     event_bus: EventBus
-    task_group: TaskGroup
+    task_group: TaskGroup = field(default_factory=create_task_group)
     history: list[Event] = field(default_factory=list, init=False)
 
     def __bool__(self) -> bool:  # pragma: no cover
         return bool(self.history)
 
+    async def __aenter__(self) -> Self:
+        await self.task_group.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> Any:
+        return await self.task_group.__aexit__(exc_type, exc_value, traceback)
+
     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)
-
-
-@injection.scoped(CQScope.TRANSACTION, mode="fallback")
-async def related_events_recipe(event_bus: EventBus) -> AsyncIterator[RelatedEvents]:
-    async with anyio.create_task_group() as task_group:
-        yield AnyIORelatedEvents(event_bus, task_group)

python_cq-0.16.0/cq/ext/injection.py

@@ -0,0 +1,102 @@
+from collections.abc import AsyncIterator
+from contextlib import AsyncExitStack, asynccontextmanager
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any, AsyncContextManager, Awaitable, Callable
+
+from injection import Module, adefine_scope, mod
+from injection.exceptions import ScopeAlreadyDefinedError
+
+from cq._core.di import DIAdapter
+from cq._core.message import CommandBus, EventBus, QueryBus
+from cq._core.middleware import MiddlewareResult
+from cq._core.related_events import AnyIORelatedEvents, RelatedEvents
+
+__all__ = ("CQScope", "InjectionAdapter", "InjectionScopeMiddleware")
+
+
+class CQScope(StrEnum):
+    COMMAND_DISPATCH = "__cq_command_dispatch__"
+
+
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
+class InjectionAdapter(DIAdapter):
+    module: Module = field(default_factory=mod)
+    threadsafe: bool | None = field(default=None)
+
+    def command_scope(self) -> AsyncContextManager[None]:
+        return InjectionScopeMiddleware(  # type: ignore[return-value]
+            CQScope.COMMAND_DISPATCH,
+            exist_ok=True,
+            threadsafe=self.threadsafe,
+        )._cm
+
+    def lazy[T](self, tp: type[T], /) -> Callable[[], Awaitable[T]]:
+        awaitable = self.module.aget_lazy_instance(tp, threadsafe=self.threadsafe)
+        return lambda: awaitable
+
+    def register_defaults(
+        self,
+        command_bus: Callable[..., CommandBus[Any]],
+        event_bus: Callable[..., EventBus],
+        query_bus: Callable[..., QueryBus[Any]],
+    ) -> None:
+        self.module.injectable(
+            command_bus,
+            ignore_type_hint=True,
+            inject=False,
+            on=CommandBus,
+            mode="fallback",
+        )
+        self.module.injectable(
+            event_bus,
+            ignore_type_hint=True,
+            inject=False,
+            on=EventBus,
+            mode="fallback",
+        )
+        self.module.injectable(
+            query_bus,
+            ignore_type_hint=True,
+            inject=False,
+            on=QueryBus,
+            mode="fallback",
+        )
+        self.module.scoped(
+            CQScope.COMMAND_DISPATCH,
+            mode="fallback",
+        )(self.__new_related_events)
+
+    def wire[T](self, tp: type[T], /) -> Callable[..., Awaitable[T]]:
+        return self.module.make_async_factory(tp, self.threadsafe)
+
+    @staticmethod
+    async def __new_related_events(event_bus: EventBus) -> AsyncIterator[RelatedEvents]:
+        async with AnyIORelatedEvents(event_bus) as events:
+            yield events
+
+
+@dataclass(repr=False, eq=False, frozen=True, slots=True)
+class InjectionScopeMiddleware:
+    scope_name: str
+    exist_ok: bool = field(default=False, kw_only=True)
+    threadsafe: bool | None = field(default=None, kw_only=True)
+
+    async def __call__(self, /, *args: Any, **kwargs: Any) -> MiddlewareResult[Any]:
+        async with self._cm:  # type: ignore[attr-defined]
+            yield
+
+    @property
+    @asynccontextmanager
+    async def _cm(self) -> AsyncIterator[None]:
+        async with AsyncExitStack() as stack:
+            try:
+                await stack.enter_async_context(
+                    adefine_scope(self.scope_name, threadsafe=self.threadsafe)
+                )
+
+            except ScopeAlreadyDefinedError:
+                if not self.exist_ok:
+                    raise
+
+            yield

{python_cq-0.15.2 → python_cq-0.16.0}/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]"
+```

{python_cq-0.15.2 → python_cq-0.16.0}/pyproject.toml

@@ -13,8 +13,6 @@ docs = [
     "mkdocs-material",
 ]
 test = [
-    "fastapi",
-    "httpx",
     "pytest",
     "pytest-asyncio",
     "pytest-cov",
@@ -22,7 +20,7 @@ test = [
 
 [project]
 name = "python-cq"
-version = "0.15.2"
+version = "0.16.0"
 description = "CQRS library for async Python projects."
 license = "MIT"
 license-files = ["LICENSE"]
@@ -48,10 +46,14 @@ classifiers = [
 ]
 dependencies = [
     "anyio",
-    "python-injection",
     "type-analyzer",
 ]
 
+[project.optional-dependencies]
+injection = [
+    "python-injection[async]",
+]
+
 [project.urls]
 Documentation = "https://python-cq.remimd.dev"
 Repository = "https://github.com/100nm/python-cq"

python_cq-0.15.2/cq/__init__.py

@@ -1,51 +0,0 @@
-from ._core.dispatcher.base import DeferredDispatcher, Dispatcher
-from ._core.dispatcher.bus import Bus
-from ._core.dispatcher.lazy import LazyDispatcher
-from ._core.dispatcher.pipe import ContextPipeline, Pipe
-from ._core.message import (
-    AnyCommandBus,
-    Command,
-    CommandBus,
-    Event,
-    EventBus,
-    Query,
-    QueryBus,
-    command_handler,
-    event_handler,
-    new_command_bus,
-    new_event_bus,
-    new_query_bus,
-    query_handler,
-)
-from ._core.middleware import Middleware, MiddlewareResult, resolve_handler_source
-from ._core.pipetools import ContextCommandPipeline
-from ._core.related_events import RelatedEvents
-from ._core.scope import CQScope
-
-__all__ = (
-    "AnyCommandBus",
-    "Bus",
-    "CQScope",
-    "Command",
-    "CommandBus",
-    "ContextCommandPipeline",
-    "ContextPipeline",
-    "DeferredDispatcher",
-    "Dispatcher",
-    "Event",
-    "EventBus",
-    "LazyDispatcher",
-    "Middleware",
-    "MiddlewareResult",
-    "Pipe",
-    "Query",
-    "QueryBus",
-    "RelatedEvents",
-    "command_handler",
-    "event_handler",
-    "new_command_bus",
-    "new_event_bus",
-    "new_query_bus",
-    "query_handler",
-    "resolve_handler_source",
-)

python_cq-0.15.2/cq/_core/dispatcher/lazy.py

@@ -1,28 +0,0 @@
-from collections.abc import Awaitable
-from types import GenericAlias
-from typing import TypeAliasType
-
-import injection
-
-from cq._core.dispatcher.base import Dispatcher
-
-
-class LazyDispatcher[I, O](Dispatcher[I, O]):
-    __slots__ = ("__value",)
-
-    __value: Awaitable[Dispatcher[I, O]]
-
-    def __init__(
-        self,
-        dispatcher_type: type[Dispatcher[I, O]] | TypeAliasType | GenericAlias,
-        /,
-        *,
-        injection_module: injection.Module | None = None,
-        threadsafe: bool | None = None,
-    ) -> None:
-        module = injection_module or injection.mod()
-        self.__value = module.aget_lazy_instance(dispatcher_type, threadsafe=threadsafe)
-
-    async def dispatch(self, input_value: I, /) -> O:
-        dispatcher = await self.__value
-        return await dispatcher.dispatch(input_value)

python_cq-0.15.2/cq/_core/message.py

@@ -1,71 +0,0 @@
-from typing import Any, Final
-
-import injection
-
-from cq._core.dispatcher.base import Dispatcher
-from cq._core.dispatcher.bus import Bus, SimpleBus, TaskBus
-from cq._core.handler import (
-    HandlerDecorator,
-    MultipleHandlerRegistry,
-    SingleHandlerRegistry,
-)
-from cq._core.scope import CQScope
-from cq.middlewares.scope import InjectionScopeMiddleware
-
-Command = object
-Event = object
-Query = object
-
-type CommandBus[T] = Dispatcher[Command, T]
-type EventBus = Dispatcher[Event, None]
-type QueryBus[T] = Dispatcher[Query, T]
-
-AnyCommandBus = CommandBus[Any]
-
-
-command_handler: Final[HandlerDecorator[Command, Any]] = HandlerDecorator(
-    SingleHandlerRegistry(),
-)
-event_handler: Final[HandlerDecorator[Event, Any]] = HandlerDecorator(
-    MultipleHandlerRegistry(),
-)
-query_handler: Final[HandlerDecorator[Query, Any]] = HandlerDecorator(
-    SingleHandlerRegistry(),
-)
-
-
-@injection.injectable(
-    ignore_type_hint=True,
-    inject=False,
-    on=CommandBus,
-    mode="fallback",
-)
-def new_command_bus(*, threadsafe: bool | None = None) -> Bus[Command, Any]:
-    bus = SimpleBus(command_handler.registry)
-    transaction_scope_middleware = InjectionScopeMiddleware(
-        CQScope.TRANSACTION,
-        exist_ok=True,
-        threadsafe=threadsafe,
-    )
-    bus.add_middlewares(transaction_scope_middleware)
-    return bus
-
-
-@injection.injectable(
-    ignore_type_hint=True,
-    inject=False,
-    on=EventBus,
-    mode="fallback",
-)
-def new_event_bus() -> Bus[Event, None]:
-    return TaskBus(event_handler.registry)
-
-
-@injection.injectable(
-    ignore_type_hint=True,
-    inject=False,
-    on=QueryBus,
-    mode="fallback",
-)
-def new_query_bus() -> Bus[Query, Any]:
-    return SimpleBus(query_handler.registry)

python_cq-0.15.2/cq/_core/pipetools.py

@@ -1,75 +0,0 @@
-from typing import TYPE_CHECKING, Any, overload
-
-import injection
-
-from cq import Dispatcher
-from cq._core.common.typing import Decorator
-from cq._core.dispatcher.lazy import LazyDispatcher
-from cq._core.dispatcher.pipe import (
-    ContextPipeline,
-    ConvertMethod,
-    ConvertMethodAsync,
-    ConvertMethodSync,
-)
-from cq._core.message import AnyCommandBus, Command, Query, QueryBus
-from cq._core.scope import CQScope
-from cq.middlewares.scope import InjectionScopeMiddleware
-
-
-class ContextCommandPipeline[I: Command](ContextPipeline[I]):
-    __slots__ = ("__query_dispatcher",)
-
-    __query_dispatcher: Dispatcher[Query, Any]
-
-    def __init__(
-        self,
-        /,
-        *,
-        injection_module: injection.Module | None = None,
-        threadsafe: bool | None = None,
-    ) -> None:
-        command_dispatcher = LazyDispatcher(
-            AnyCommandBus,
-            injection_module=injection_module,
-            threadsafe=threadsafe,
-        )
-        super().__init__(command_dispatcher)
-
-        self.__query_dispatcher = LazyDispatcher(
-            QueryBus,
-            injection_module=injection_module,
-            threadsafe=threadsafe,
-        )
-
-        transaction_scope_middleware = InjectionScopeMiddleware(
-            CQScope.TRANSACTION,
-            exist_ok=True,
-            threadsafe=threadsafe,
-        )
-        self.add_middlewares(transaction_scope_middleware)
-
-    if TYPE_CHECKING:  # pragma: no cover
-
-        @overload
-        def query_step[T: Query](
-            self,
-            wrapped: ConvertMethodAsync[T, Any],
-            /,
-        ) -> ConvertMethodAsync[T, Any]: ...
-
-        @overload
-        def query_step[T: Query](
-            self,
-            wrapped: ConvertMethodSync[T, Any],
-            /,
-        ) -> ConvertMethodSync[T, Any]: ...
-
-        @overload
-        def query_step(self, wrapped: None = ..., /) -> Decorator: ...
-
-    def query_step[T: Query](  # type: ignore[misc]
-        self,
-        wrapped: ConvertMethod[T, Any] | None = None,
-        /,
-    ) -> Any:
-        return self.step(wrapped, dispatcher=self.__query_dispatcher)

python_cq-0.15.2/cq/_core/scope.py

@@ -1,5 +0,0 @@
-from enum import StrEnum
-
-
-class CQScope(StrEnum):
-    TRANSACTION = "__cq_transaction__"

python_cq-0.15.2/cq/ext/fastapi.py

@@ -1,73 +0,0 @@
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Annotated, Any
-
-from fastapi import BackgroundTasks, Depends
-from injection.ext.fastapi import Inject
-
-from cq import (
-    Command,
-    CommandBus,
-    DeferredDispatcher,
-    Dispatcher,
-    Event,
-    EventBus,
-    Query,
-    QueryBus,
-)
-
-__all__ = (
-    "DeferredCommandBus",
-    "DeferredEventBus",
-    "DeferredQueryBus",
-    "FastAPIDeferredDispatcher",
-)
-
-
-@dataclass(repr=False, eq=False, frozen=True, slots=True)
-class FastAPIDeferredDispatcher[I](DeferredDispatcher[I]):
-    background_tasks: BackgroundTasks
-    dispatcher: Dispatcher[I, Any]
-
-    async def defer(self, input_value: I, /) -> None:
-        self.background_tasks.add_task(self.dispatcher.dispatch, input_value)
-
-
-async def new_deferred_command_bus[T](
-    background_tasks: BackgroundTasks,
-    command_bus: Inject[CommandBus[T]],
-) -> DeferredDispatcher[Command]:
-    return FastAPIDeferredDispatcher(background_tasks, command_bus)
-
-
-async def new_deferred_event_bus(
-    background_tasks: BackgroundTasks,
-    event_bus: Inject[EventBus],
-) -> DeferredDispatcher[Event]:
-    return FastAPIDeferredDispatcher(background_tasks, event_bus)
-
-
-async def new_deferred_query_bus[T](
-    background_tasks: BackgroundTasks,
-    query_bus: Inject[QueryBus[T]],
-) -> DeferredDispatcher[Query]:
-    return FastAPIDeferredDispatcher(background_tasks, query_bus)
-
-
-if TYPE_CHECKING:  # pragma: no cover
-    type DeferredCommandBus = DeferredDispatcher[Command]
-    type DeferredEventBus = DeferredDispatcher[Event]
-    type DeferredQueryBus = DeferredDispatcher[Query]
-
-else:
-    DeferredCommandBus = Annotated[
-        DeferredDispatcher[Command],
-        Depends(new_deferred_command_bus, use_cache=False),
-    ]
-    DeferredEventBus = Annotated[
-        DeferredDispatcher[Event],
-        Depends(new_deferred_event_bus, use_cache=False),
-    ]
-    DeferredQueryBus = Annotated[
-        DeferredDispatcher[Query],
-        Depends(new_deferred_query_bus, use_cache=False),
-    ]

python_cq-0.15.2/cq/middlewares/scope.py

@@ -1,33 +0,0 @@
-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:
-    scope_name: str
-    exist_ok: bool = field(default=False, kw_only=True)
-    threadsafe: bool | None = field(default=None, kw_only=True)
-
-    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, threadsafe=self.threadsafe)
-                )
-
-            except ScopeAlreadyDefinedError:
-                if not self.exist_ok:
-                    raise
-
-            yield