pymediate 0.1.0__py3-none-any.whl

pymediate/__init__.py

@@ -0,0 +1,106 @@
+"""PyMediate - A type-safe mediator pattern implementation for Python.
+
+PyMediate is a modern implementation of the Mediator Pattern that provides
+type-safe request routing with automatic response type inference. It's designed
+for Python 3.12+ and integrates seamlessly with dataclasses and dependency
+injection frameworks.
+
+Key Features:
+    - Type-safe: Full runtime validation with mypy support
+    - Zero convention: Uses type inspection instead of naming conventions
+    - Async/await support: Built-in async handlers and mediators via pymediate.aio
+    - DI ready: Built-in dependency-injector integration
+    - Dataclass friendly: Works seamlessly with @dataclass and Request[T]
+    - Well tested: 95%+ coverage enforced in CI
+
+Quick Example:
+    ```python
+    from dataclasses import dataclass
+    from pymediate import Request, Handler, Mediator, Services
+
+    @dataclass
+    class UserCreated:
+        user_id: int
+        username: str
+
+    @dataclass
+    class CreateUser(Request[UserCreated]):
+        username: str
+        email: str
+
+    class CreateUserHandler(Handler[CreateUser]):
+        def __call__(self, req: CreateUser) -> UserCreated:
+            return UserCreated(user_id=1, username=req.username)
+
+    services = Services()
+    services.add(CreateUserHandler())
+    provider = services.provider()
+    mediator = Mediator(provider)
+
+    response = mediator.send(CreateUser(username="alice", email="alice@example.com"))
+    print(f"User {response.username} created with ID {response.user_id}")
+    ```
+
+Main Components:
+    - Request: Base class for all requests
+    - Handler: Base class for synchronous handlers
+    - Mediator: Routes requests to handlers (sync version)
+    - ServiceProvider: Protocol for resolving service instances
+    - Services: Builder for registering services
+
+Async Support:
+    For asynchronous operations, use the async variants from pymediate.aio:
+    ```python
+    from pymediate import Services
+    from pymediate.aio import Handler, Mediator
+
+    class AsyncHandler(Handler[CreateUser]):
+        async def __call__(self, req: CreateUser) -> UserCreated:
+            # Can use await here
+            result = await async_database_operation(req)
+            return UserCreated(user_id=result.id, username=req.username)
+
+    services = Services()
+    services.add(AsyncHandler())
+    provider = services.provider()
+    mediator = Mediator(provider)
+    response = await mediator.send(CreateUser(username="alice", email="alice@example.com"))
+    ```
+
+For more information, see the documentation at https://sina-al.github.io/pymediate/
+"""
+
+from .errors import (
+    HandlerAlreadyRegisteredError,
+    HandlerNotFoundError,
+    InvalidHandlerSignatureError,
+    InvalidRequestTypeError,
+    PyMediateError,
+    ResponseTypeMismatchError,
+)
+from .handler import Handler
+from .mediator import Mediator
+from .pipeline import PipelineBehavior
+from .request import Request
+from .service import ServiceNotFoundError, ServiceProvider, Services
+
+__all__ = [
+    "Request",
+    "Handler",
+    "Mediator",
+    # Service Provider
+    "ServiceProvider",
+    "Services",
+    "ServiceNotFoundError",
+    # Pipeline
+    "PipelineBehavior",
+    # Errors
+    "PyMediateError",
+    "HandlerNotFoundError",
+    "HandlerAlreadyRegisteredError",
+    "InvalidHandlerSignatureError",
+    "InvalidRequestTypeError",
+    "ResponseTypeMismatchError",
+]
+
+__version__ = "0.1.0"

pymediate/_internal/__init__.py

@@ -0,0 +1,10 @@
+"""Internal implementation details for PyMediate.
+
+This package contains internal utilities, base classes, and registries that are
+not part of the public API. Users should not import from this package directly.
+
+Warning:
+    The contents of this package are internal implementation details and may
+    change without notice in any release. Only import from the main `pymediate`
+    package or `pymediate.aio` for public APIs.
+"""

pymediate/_internal/handler.py

@@ -0,0 +1,195 @@
+"""Shared base logic for both sync and async handlers.
+
+This module provides HandlerBaseMixin which contains all the type extraction,
+validation, and registration logic that is common between sync and async handlers.
+"""
+
+import inspect
+from typing import Any, get_args, get_origin
+
+from .. import errors
+from . import registry
+
+
+def _validate_call_signature(
+    cls: type,
+    expected_request_type: type,
+    expected_response_type: type,
+    is_async: bool = False,
+) -> None:
+    """Validate that the handler's __call__ method has the correct signature.
+
+    Args:
+        cls: The handler class to validate
+        expected_request_type: The expected request parameter type
+        expected_response_type: The expected return type
+        is_async: Whether to expect async def __call__ or sync def __call__
+
+    Raises:
+        TypeError: If the signature doesn't match expectations
+    """
+    if "__call__" not in cls.__dict__:
+        raise errors.InvalidHandlerSignatureError(cls, "must implement __call__ method")
+
+    call_method = cls.__dict__["__call__"]
+
+    # Check if it's async when it should be (or vice versa)
+    if is_async and not inspect.iscoroutinefunction(call_method):
+        raise errors.InvalidHandlerSignatureError(
+            cls, "__call__ must be async (use 'async def __call__')"
+        )
+    elif not is_async and inspect.iscoroutinefunction(call_method):
+        raise errors.InvalidHandlerSignatureError(
+            cls, "__call__ must be sync (remove 'async' from 'def __call__')"
+        )
+
+    sig = inspect.signature(call_method)
+
+    # Validate parameters
+    params = list(sig.parameters.values())
+    if len(params) != 2:  # self, request
+        raise errors.InvalidHandlerSignatureError(
+            cls,
+            f"__call__ must accept exactly one parameter (besides self), got {len(params) - 1}",
+        )
+
+    request_param = params[1]  # Skip 'self'
+    if request_param.annotation == inspect.Parameter.empty:
+        raise errors.InvalidHandlerSignatureError(
+            cls, "__call__ request parameter must have type annotation"
+        )
+
+    if request_param.annotation != expected_request_type:
+        param_name = (
+            request_param.annotation.__name__
+            if hasattr(request_param.annotation, "__name__")
+            else str(request_param.annotation)
+        )
+        expected_name = expected_request_type.__name__
+        raise errors.InvalidHandlerSignatureError(
+            cls,
+            f"__call__ parameter must be of type {expected_name}, got {param_name}",
+        )
+
+    # Validate return type
+    if sig.return_annotation == inspect.Signature.empty:
+        raise errors.InvalidHandlerSignatureError(cls, "__call__ must have return type annotation")
+
+    if sig.return_annotation != expected_response_type:
+        raise errors.ResponseTypeMismatchError(cls, expected_response_type, sig.return_annotation)
+
+
+class HandlerBaseMixin[RequestT]:
+    """Mixin providing shared logic for both sync and async handlers.
+
+    This mixin contains all the type extraction, validation, and registration
+    logic that is common between synchronous and asynchronous handlers.
+
+    Type Parameters:
+        RequestT: The type of request this handler processes.
+
+    Attributes:
+        _request_type: Class-level attribute storing the request type.
+        _response_type: Class-level attribute storing the inferred response type.
+    """
+
+    _request_type: type | None = None
+    _response_type: type | None = None
+    _is_async: bool = False  # Set by subclass
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Extract request type and validate handler signature.
+
+        This hook is automatically called when a new Handler subclass is defined.
+        It extracts the request type from Handler[RequestType], looks up the
+        corresponding response type, validates the __call__ signature, and
+        registers the handler.
+
+        Args:
+            **kwargs: Additional keyword arguments passed to parent __init_subclass__.
+
+        Raises:
+            InvalidRequestTypeError: If the request type doesn't inherit from Request.
+            InvalidHandlerSignatureError: If __call__ signature is invalid.
+            ResponseTypeMismatchError: If return type doesn't match expected response.
+        """
+        super().__init_subclass__(**kwargs)
+
+        cls._request_type = None
+        cls._response_type = None
+
+        # Extract request type from Handler[RequestType]
+        # We need to find the right base class (could be Handler or AsyncHandler)
+        orig_bases = getattr(cls, "__orig_bases__", ())
+        for base in orig_bases:
+            origin = get_origin(base)
+            # Check if this is a Handler-like class (has HandlerBaseMixin in its mro)
+            if origin and any(hasattr(b, "_is_async") for b in getattr(origin, "__mro__", [])):
+                args = get_args(base)
+                if args:
+                    cls._request_type = args[0]
+                    break
+
+        # Look up response type from request registry
+        if cls._request_type is not None:
+            if registry.has_response_type(cls._request_type):
+                cls._response_type = registry.get_response_type(cls._request_type)
+
+                # Validate the __call__ signature
+                assert cls._response_type is not None, (
+                    "Response type should not be None after check"
+                )
+                _validate_call_signature(
+                    cls, cls._request_type, cls._response_type, is_async=cls._is_async
+                )
+
+                # Register handler
+                registry.register_handler(cls._request_type, cls)
+            else:
+                # Only raise if this isn't a base Handler class
+                if cls.__name__ not in ("Handler", "HandlerBaseMixin"):
+                    raise errors.InvalidRequestTypeError(cls._request_type)
+
+    @classmethod
+    def get_request_type(cls) -> type | None:
+        """Get the request type this handler handles.
+
+        Returns:
+            The request type class that this handler is designed to process,
+            or None if no request type was specified.
+        """
+        return cls._request_type
+
+    @classmethod
+    def get_response_type(cls) -> type | None:
+        """Get the response type this handler returns.
+
+        The response type is automatically inferred from the request's
+        Request[ResponseT] declaration.
+
+        Returns:
+            The response type class that this handler will return,
+            or None if no response type was registered.
+        """
+        return cls._response_type
+
+    @classmethod
+    def get_handler_for_request(cls, request_type: type) -> Any:
+        """Get the handler class registered for a given request type.
+
+        This is a class-level utility method for looking up which handler
+        class is registered to handle a specific request type.
+
+        Args:
+            request_type: The request type class to look up.
+
+        Returns:
+            The handler class that processes the given request type.
+
+        Raises:
+            HandlerNotFoundError: If no handler is registered for the request type.
+        """
+        if not registry.has_handler(request_type):
+            available = registry.get_all_handler_request_types()
+            raise errors.HandlerNotFoundError(request_type, available)
+        return registry.get_handler_class(request_type)

pymediate/_internal/mediator.py

@@ -0,0 +1,128 @@
+"""Base mixin for mediator implementations (sync and async)."""
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
+
+from .. import errors
+from . import registry
+
+if TYPE_CHECKING:
+    from ..request import Request
+    from ..service import ServiceProvider
+
+
+class MediatorMixin:
+    """Mixin providing shared logic for both sync and async mediators.
+
+    This mixin contains the common initialization and request processing logic
+    that is shared between the synchronous Mediator and asynchronous Mediator.
+
+    The actual send() method is implemented differently in each variant:
+    - Synchronous: def send(...) -> ResponseT
+    - Asynchronous: async def send(...) -> ResponseT
+
+    Attributes:
+        _services: The services instance used to obtain handler and behavior instances.
+    """
+
+    _services: "ServiceProvider"
+
+    def __init__(self, services: "ServiceProvider") -> None:
+        """Initialize mediator with services for obtaining handler and behavior instances.
+
+        Args:
+            services: Any object implementing the ServiceProvider protocol.
+                This can be a ServiceProvider from Services.provider(),
+                a DependencyInjectorServiceProvider, or your own custom implementation.
+
+        Examples:
+            ```python
+            from pymediate import Mediator
+            from pymediate.service import Services
+
+            services = Services()
+            services.add(CreateUserHandler())
+            provider = services.provider()
+
+            mediator = Mediator(provider)
+            ```
+
+            With dependency injection:
+            ```python
+            from pymediate.providers import DependencyInjectorServiceProvider
+
+            container = AppContainer()
+            provider = DependencyInjectorServiceProvider(container)
+            mediator = Mediator(provider)
+            ```
+        """
+        self._services = services
+
+    def _resolve_handler(self, request: "Request[Any]") -> Any:
+        """Resolve the handler for a request.
+
+        Args:
+            request: The request instance to process
+
+        Returns:
+            Handler instance for the request
+
+        Raises:
+            HandlerNotFoundError: If no handler is registered for the request type
+        """
+        # Look up handler type from registry
+        request_type = type(request)
+        handler_class = registry.get_handler_class(request_type)
+        if handler_class is None:
+            raise errors.HandlerNotFoundError(request_type, [])
+
+        # Get handler instance
+        return self._services.get(handler_class)
+
+    def _resolve_behaviors(
+        self, request: "Request[Any]", pipeline_behavior_type: type
+    ) -> list[Any]:
+        """Resolve applicable behaviors for a request.
+
+        Args:
+            request: The request instance to process
+            pipeline_behavior_type: The PipelineBehavior type (sync or async variant)
+
+        Returns:
+            List of applicable behavior instances
+        """
+        # Get all registered pipeline behaviors
+        all_behaviors: Sequence[Any] = self._services.get_all(pipeline_behavior_type)
+
+        # Filter behaviors to only those that apply to this request
+        return [behavior for behavior in all_behaviors if type(behavior).should_apply(request)]
+
+    def _get_dispatch(
+        self,
+        request: "Request[Any]",
+        handler: Any,
+        behaviors: list[Any],
+        pipeline_class: type,
+    ) -> Callable[[], Any]:
+        """Get a dispatch callable for executing the request through behaviors and handler.
+
+        This method creates a callable that, when invoked, will execute the request
+        through the pipeline of behaviors and the handler. The callable can be called
+        synchronously or asynchronously depending on the pipeline class.
+
+        Args:
+            request: The request instance to process
+            handler: The handler instance
+            behaviors: List of applicable behaviors
+            pipeline_class: The Pipeline class (sync or async variant)
+
+        Returns:
+            Callable that executes the pipeline
+        """
+        # Fast path: if no behaviors, return handler directly
+        if not behaviors:
+            return lambda: handler(request)
+
+        # Construct and return pipeline callable
+        pipeline: Any = pipeline_class(behaviors, handler)
+        return lambda: pipeline(request)