python-cq 0.12.2__tar.gz → 0.13.0__tar.gz

python_cq-0.13.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: python-cq
+Version: 0.13.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: python-injection
+Requires-Dist: type-analyzer
+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 builds on top of [python-injection](https://github.com/100nm/python-injection) for dependency injection.
+
+## 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.
+```bash
+pip install python-cq
+```

{python_cq-0.12.2 → python_cq-0.13.0}/cq/_core/dispatcher/bus.py

@@ -8,9 +8,9 @@ from anyio.abc import TaskGroup
 from cq._core.dispatcher.base import BaseDispatcher, Dispatcher
 from cq._core.handler import (
     HandlerFactory,
-    HandlerManager,
-    MultipleHandlerManager,
-    SingleHandlerManager,
+    HandlerRegistry,
+    MultipleHandlerRegistry,
+    SingleHandlerRegistry,
 )
 from cq._core.middleware import Middleware
 
@@ -35,29 +35,29 @@ class Bus[I, O](Dispatcher[I, O], Protocol):
 
 
 class BaseBus[I, O](BaseDispatcher[I, O], Bus[I, O], ABC):
-    __slots__ = ("__listeners", "__manager")
+    __slots__ = ("__listeners", "__registry")
 
     __listeners: list[Listener[I]]
-    __manager: HandlerManager[I, O]
+    __registry: HandlerRegistry[I, O]
 
-    def __init__(self, manager: HandlerManager[I, O]) -> None:
+    def __init__(self, registry: HandlerRegistry[I, O], /) -> None:
         super().__init__()
         self.__listeners = []
-        self.__manager = manager
+        self.__registry = registry
 
     def add_listeners(self, *listeners: Listener[I]) -> Self:
         self.__listeners.extend(listeners)
         return self
 
     def subscribe(self, input_type: type[I], factory: HandlerFactory[[I], O]) -> Self:
-        self.__manager.subscribe(input_type, factory)
+        self.__registry.subscribe(input_type, factory)
         return self
 
     def _handlers_from(
         self,
         input_type: type[I],
     ) -> Iterator[Callable[[I], Awaitable[O]]]:
-        return self.__manager.handlers_from(input_type)
+        return self.__registry.handlers_from(input_type)
 
     def _trigger_listeners(self, input_value: I, /, task_group: TaskGroup) -> None:
         for listener in self.__listeners:
@@ -67,8 +67,8 @@ class BaseBus[I, O](BaseDispatcher[I, O], Bus[I, O], ABC):
 class SimpleBus[I, O](BaseBus[I, O]):
     __slots__ = ()
 
-    def __init__(self, manager: HandlerManager[I, O] | None = None) -> None:
-        super().__init__(manager or SingleHandlerManager())
+    def __init__(self, registry: HandlerRegistry[I, O] | None = None, /) -> None:
+        super().__init__(registry or SingleHandlerRegistry())
 
     async def dispatch(self, input_value: I, /) -> O:
         async with anyio.create_task_group() as task_group:
@@ -83,8 +83,8 @@ class SimpleBus[I, O](BaseBus[I, O]):
 class TaskBus[I](BaseBus[I, None]):
     __slots__ = ()
 
-    def __init__(self, manager: HandlerManager[I, None] | None = None) -> None:
-        super().__init__(manager or MultipleHandlerManager())
+    def __init__(self, registry: HandlerRegistry[I, None] | None = None, /) -> None:
+        super().__init__(registry or MultipleHandlerRegistry())
 
     async def dispatch(self, input_value: I, /) -> None:
         async with anyio.create_task_group() as task_group:

{python_cq-0.12.2 → python_cq-0.13.0}/cq/_core/handler.py

@@ -24,7 +24,7 @@ class Handler[**P, T](Protocol):
 
 
 @runtime_checkable
-class HandlerManager[I, O](Protocol):
+class HandlerRegistry[I, O](Protocol):
     __slots__ = ()
 
     @abstractmethod
@@ -40,7 +40,7 @@ class HandlerManager[I, O](Protocol):
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
-class MultipleHandlerManager[I, O](HandlerManager[I, O]):
+class MultipleHandlerRegistry[I, O](HandlerRegistry[I, O]):
     __factories: dict[type[I], list[HandlerFactory[[I], O]]] = field(
         default_factory=partial(defaultdict, list),
         init=False,
@@ -62,7 +62,7 @@ class MultipleHandlerManager[I, O](HandlerManager[I, O]):
 
 
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
-class SingleHandlerManager[I, O](HandlerManager[I, O]):
+class SingleHandlerRegistry[I, O](HandlerRegistry[I, O]):
     __factories: dict[type[I], HandlerFactory[[I], O]] = field(
         default_factory=dict,
         init=False,
@@ -90,9 +90,13 @@ class SingleHandlerManager[I, O](HandlerManager[I, O]):
         return self
 
 
+class _Decorator(Protocol):
+    def __call__[T](self, wrapped: T, /) -> T: ...
+
+
 @dataclass(repr=False, eq=False, frozen=True, slots=True)
 class HandlerDecorator[I, O]:
-    manager: HandlerManager[I, O]
+    registry: HandlerRegistry[I, O]
     injection_module: injection.Module = field(default_factory=injection.mod)
 
     if TYPE_CHECKING:  # pragma: no cover
@@ -104,16 +108,16 @@ class HandlerDecorator[I, O]:
             /,
             *,
             threadsafe: bool | None = ...,
-        ) -> Callable[[HandlerType[[I], O]], HandlerType[[I], O]]: ...
+        ) -> _Decorator: ...
 
         @overload
-        def __call__(
+        def __call__[T](
             self,
-            input_or_handler_type: HandlerType[[I], O],
+            input_or_handler_type: T,
             /,
             *,
             threadsafe: bool | None = ...,
-        ) -> HandlerType[[I], O]: ...
+        ) -> T: ...
 
         @overload
         def __call__(
@@ -122,11 +126,11 @@ class HandlerDecorator[I, O]:
             /,
             *,
             threadsafe: bool | None = ...,
-        ) -> Callable[[HandlerType[[I], O]], HandlerType[[I], O]]: ...
+        ) -> _Decorator: ...
 
-    def __call__(
+    def __call__[T](
         self,
-        input_or_handler_type: type[I] | HandlerType[[I], O] | None = None,
+        input_or_handler_type: type[I] | T | None = None,
         /,
         *,
         threadsafe: bool | None = None,
@@ -154,7 +158,7 @@ class HandlerDecorator[I, O]:
     ) -> HandlerType[[I], O]:
         factory = self.injection_module.make_async_factory(wrapped, threadsafe)
         input_type = input_type or _resolve_input_type(wrapped)
-        self.manager.subscribe(input_type, factory)
+        self.registry.subscribe(input_type, factory)
         return wrapped
 
 

{python_cq-0.12.2 → python_cq-0.13.0}/cq/_core/message.py

@@ -6,8 +6,8 @@ from cq._core.dispatcher.base import Dispatcher
 from cq._core.dispatcher.bus import Bus, SimpleBus, TaskBus
 from cq._core.handler import (
     HandlerDecorator,
-    MultipleHandlerManager,
-    SingleHandlerManager,
+    MultipleHandlerRegistry,
+    SingleHandlerRegistry,
 )
 from cq._core.scope import CQScope
 from cq.middlewares.scope import InjectionScopeMiddleware
@@ -24,13 +24,13 @@ AnyCommandBus = CommandBus[Any]
 
 
 command_handler: Final[HandlerDecorator[Command, Any]] = HandlerDecorator(
-    SingleHandlerManager(),
+    SingleHandlerRegistry(),
 )
 event_handler: Final[HandlerDecorator[Event, None]] = HandlerDecorator(
-    MultipleHandlerManager(),
+    MultipleHandlerRegistry(),
 )
 query_handler: Final[HandlerDecorator[Query, Any]] = HandlerDecorator(
-    SingleHandlerManager(),
+    SingleHandlerRegistry(),
 )
 
 
@@ -41,7 +41,7 @@ query_handler: Final[HandlerDecorator[Query, Any]] = HandlerDecorator(
     mode="fallback",
 )
 def new_command_bus(*, threadsafe: bool | None = None) -> Bus[Command, Any]:
-    bus = SimpleBus(command_handler.manager)
+    bus = SimpleBus(command_handler.registry)
     transaction_scope_middleware = InjectionScopeMiddleware(
         CQScope.TRANSACTION,
         exist_ok=True,
@@ -58,7 +58,7 @@ def new_command_bus(*, threadsafe: bool | None = None) -> Bus[Command, Any]:
     mode="fallback",
 )
 def new_event_bus() -> Bus[Event, None]:
-    return TaskBus(event_handler.manager)
+    return TaskBus(event_handler.registry)
 
 
 @injection.injectable(
@@ -68,4 +68,4 @@ def new_event_bus() -> Bus[Event, None]:
     mode="fallback",
 )
 def new_query_bus() -> Bus[Query, Any]:
-    return SimpleBus(query_handler.manager)
+    return SimpleBus(query_handler.registry)

python_cq-0.13.0/cq/_core/pipetools.py

@@ -0,0 +1,66 @@
+from typing import TYPE_CHECKING, Any, Callable, overload
+
+import injection
+
+from cq import Dispatcher
+from cq._core.dispatcher.lazy import LazyDispatcher
+from cq._core.dispatcher.pipe import ContextPipeline, PipeConverterMethod
+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: PipeConverterMethod[T, Any],
+            /,
+        ) -> PipeConverterMethod[T, Any]: ...
+
+        @overload
+        def query_step[T: Query](
+            self,
+            wrapped: None = ...,
+            /,
+        ) -> Callable[[PipeConverterMethod[T, Any]], PipeConverterMethod[T, Any]]: ...
+
+    def query_step[T: Query](
+        self,
+        wrapped: PipeConverterMethod[T, Any] | None = None,
+        /,
+    ) -> Any:
+        return self.step(wrapped, dispatcher=self.__query_dispatcher)

{python_cq-0.12.2 → python_cq-0.13.0}/cq/middlewares/scope.py

@@ -21,13 +21,13 @@ class InjectionScopeMiddleware:
 
     async def __call__(self, *args: Any, **kwargs: Any) -> MiddlewareResult[Any]:
         async with AsyncExitStack() as stack:
-            cm = adefine_scope(self.scope_name, threadsafe=self.threadsafe)
             try:
-                await stack.enter_async_context(cm)
+                await stack.enter_async_context(
+                    adefine_scope(self.scope_name, threadsafe=self.threadsafe)
+                )
 
             except ScopeAlreadyDefinedError:
                 if not self.exist_ok:
                     raise
 
-            del cm
             yield

python_cq-0.13.0/docs/index.md

@@ -0,0 +1,40 @@
+# 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 builds on top of [python-injection](https://github.com/100nm/python-injection) for dependency injection.
+
+## 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.
+```bash
+pip install python-cq
+```

{python_cq-0.12.2 → python_cq-0.13.0}/pyproject.toml

@@ -8,10 +8,9 @@ dev = [
     "mypy",
     "ruff",
 ]
-example = [
-    "fastapi",
-    "msgspec",
-    "pydantic",
+docs = [
+    "mkdocs",
+    "mkdocs-material",
 ]
 test = [
     "fastapi",
@@ -23,11 +22,11 @@ test = [
 
 [project]
 name = "python-cq"
-version = "0.12.2"
-description = "Lightweight CQRS library for async Python projects."
+version = "0.13.0"
+description = "CQRS library for async Python projects."
 license = "MIT"
 license-files = ["LICENSE"]
-readme = "README.md"
+readme = "docs/index.md"
 requires-python = ">=3.12, <3.15"
 authors = [{ name = "remimd" }]
 keywords = ["cqrs"]
@@ -54,6 +53,7 @@ dependencies = [
 ]
 
 [project.urls]
+Documentation = "https://python-cq.remimd.dev"
 Repository = "https://github.com/100nm/python-cq"
 
 [tool.coverage.report]
@@ -104,5 +104,5 @@ extend-select = ["F", "I", "N"]
 fixable = ["ALL"]
 
 [tool.uv]
-default-groups = ["dev", "example", "test"]
+default-groups = ["dev", "docs", "test"]
 package = true

python_cq-0.12.2/PKG-INFO

@@ -1,55 +0,0 @@
-Metadata-Version: 2.4
-Name: python-cq
-Version: 0.12.2
-Summary: Lightweight CQRS library for async Python projects.
-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: python-injection
-Requires-Dist: type-analyzer
-Description-Content-Type: text/markdown
-
-# python-cq
-
-[![CI](https://github.com/100nm/python-cq/actions/workflows/ci.yml/badge.svg)](https://github.com/100nm/python-cq)
-[![PyPI - Version](https://img.shields.io/pypi/v/python-cq.svg?color=blue)](https://pypi.org/project/python-cq)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/python-cq.svg?color=blue)](https://pypistats.org/packages/python-cq)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-
-Lightweight library for separating Python code according to **Command and Query Responsibility Segregation** principles.
-
-Dependency injection is handled by [python-injection](https://github.com/100nm/python-injection).
-
-Easy to use with [FastAPI](https://github.com/fastapi/fastapi).
-
-## Installation
-
-⚠️ _Requires Python 3.12 or higher_
-
-```bash
-pip install python-cq
-```
-
-## Resources
-
-* [**Writing Application Layer**](https://github.com/100nm/python-cq/tree/prod/documentation/writing-application-layer.md)
-* [**Pipeline**](https://github.com/100nm/python-cq/tree/prod/documentation/pipeline.md)
-* [**FastAPI Example**](https://github.com/100nm/python-cq/tree/prod/documentation/fastapi-example.md)

python_cq-0.12.2/README.md

@@ -1,26 +0,0 @@
-# python-cq
-
-[![CI](https://github.com/100nm/python-cq/actions/workflows/ci.yml/badge.svg)](https://github.com/100nm/python-cq)
-[![PyPI - Version](https://img.shields.io/pypi/v/python-cq.svg?color=blue)](https://pypi.org/project/python-cq)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/python-cq.svg?color=blue)](https://pypistats.org/packages/python-cq)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-
-Lightweight library for separating Python code according to **Command and Query Responsibility Segregation** principles.
-
-Dependency injection is handled by [python-injection](https://github.com/100nm/python-injection).
-
-Easy to use with [FastAPI](https://github.com/fastapi/fastapi).
-
-## Installation
-
-⚠️ _Requires Python 3.12 or higher_
-
-```bash
-pip install python-cq
-```
-
-## Resources
-
-* [**Writing Application Layer**](https://github.com/100nm/python-cq/tree/prod/documentation/writing-application-layer.md)
-* [**Pipeline**](https://github.com/100nm/python-cq/tree/prod/documentation/pipeline.md)
-* [**FastAPI Example**](https://github.com/100nm/python-cq/tree/prod/documentation/fastapi-example.md)

python_cq-0.12.2/cq/_core/pipetools.py

@@ -1,31 +0,0 @@
-import injection
-
-from cq._core.dispatcher.lazy import LazyDispatcher
-from cq._core.dispatcher.pipe import ContextPipeline
-from cq._core.message import AnyCommandBus, Command
-from cq._core.scope import CQScope
-from cq.middlewares.scope import InjectionScopeMiddleware
-
-
-class ContextCommandPipeline[I: Command](ContextPipeline[I]):
-    __slots__ = ()
-
-    def __init__(
-        self,
-        /,
-        *,
-        injection_module: injection.Module | None = None,
-        threadsafe: bool | None = None,
-    ) -> None:
-        dispatcher = LazyDispatcher(
-            AnyCommandBus,
-            injection_module=injection_module,
-            threadsafe=threadsafe,
-        )
-        super().__init__(dispatcher)
-        transaction_scope_middleware = InjectionScopeMiddleware(
-            CQScope.TRANSACTION,
-            exist_ok=True,
-            threadsafe=threadsafe,
-        )
-        self.add_middlewares(transaction_scope_middleware)