python-ddd-framework 0.3.1__py3-none-any.whl

python_ddd_framework/events/contracts.py

@@ -0,0 +1,39 @@
+"""Local Event 稳定 phase contract。"""
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import TypeVar
+
+from .errors import EventContributionError
+
+
+class LocalEventPhase(str, Enum):
+    DOMAIN = "domain"
+    AFTER_COMMIT = "after_commit"
+
+
+_EVENT_HANDLER_ATTRIBUTE = "__python_ddd_framework_local_event_handler__"
+_THandler = TypeVar("_THandler")
+
+
+@dataclass(frozen=True, slots=True)
+class _LocalEventHandlerDefinition:
+    phase: LocalEventPhase
+
+
+def local_event_handler(*, phase: LocalEventPhase) -> Callable[[type[_THandler]], type[_THandler]]:
+    """只保存 class-local phase；事件类型在 Application build 由 handle 注解解释。"""
+    if not isinstance(phase, LocalEventPhase):
+        raise EventContributionError(reason="phase must be LocalEventPhase")
+
+    def decorate(handler: type[_THandler]) -> type[_THandler]:
+        if not isinstance(handler, type) or inspect.isabstract(handler):
+            raise EventContributionError(reason="local_event_handler requires a concrete class")
+        if _EVENT_HANDLER_ATTRIBUTE in handler.__dict__:
+            raise EventContributionError(reason="local_event_handler is already declared")
+        setattr(handler, _EVENT_HANDLER_ATTRIBUTE, _LocalEventHandlerDefinition(phase))
+        return handler
+
+    return decorate

python_ddd_framework/events/contribution.py

@@ -0,0 +1,128 @@
+"""一次 Application composition 的 Local Event subscription collector。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from ..diagnostics import LifecycleStage, SourceLocation
+from ..diagnostics.source import caller_source
+from ..modularity import ModuleDescriptor, ModuleKey
+from .contracts import LocalEventPhase
+from .errors import EventContributionError
+
+
+@dataclass(frozen=True, slots=True)
+class _EventContribution:
+    event_type: type[object]
+    handler_type: type[object] | Callable[..., Awaitable[None]]
+    phase: LocalEventPhase
+    owner: ModuleKey
+    source: SourceLocation
+    reason: str
+    declaration_index: int
+    automatic: bool = False
+
+
+class EventContributor:
+    """只在当前 Module.configure 有效，避免 runtime 或 global subscription mutation。"""
+
+    __slots__ = ("_active", "_descriptor", "_registry", "_stage")
+
+    def __init__(
+        self,
+        registry: EventContributionRegistry,
+        *,
+        descriptor: ModuleDescriptor,
+        stage: LifecycleStage,
+    ) -> None:
+        self._registry = registry
+        self._descriptor = descriptor
+        self._stage = stage
+        self._active = True
+
+    def subscribe(
+        self,
+        event_type: type[object],
+        handler_type: type[object] | Callable[..., Awaitable[None]],
+        phase: LocalEventPhase,
+        *,
+        reason: str,
+    ) -> None:
+        if not self._active:
+            raise EventContributionError(
+                reason=f"event contributor is closed for {self._stage.value}"
+            )
+        self._registry.add(
+            event_type=event_type,
+            handler_type=handler_type,
+            phase=phase,
+            descriptor=self._descriptor,
+            source=caller_source(str(self._descriptor.key), depth=2),
+            reason=reason,
+        )
+
+    def _close(self) -> None:
+        self._active = False
+
+
+class EventContributionRegistry:
+    """Application-owned append-only subscription state，freeze 后只读。"""
+
+    __slots__ = ("_counts", "_entries", "_frozen")
+
+    def __init__(self) -> None:
+        self._entries: list[_EventContribution] = []
+        self._counts: dict[ModuleKey, int] = {}
+        self._frozen = False
+
+    def contributor(
+        self,
+        *,
+        descriptor: ModuleDescriptor,
+        stage: LifecycleStage,
+    ) -> EventContributor:
+        return EventContributor(self, descriptor=descriptor, stage=stage)
+
+    def add(
+        self,
+        *,
+        event_type: type[object],
+        handler_type: type[object] | Callable[..., Awaitable[None]],
+        phase: LocalEventPhase,
+        descriptor: ModuleDescriptor,
+        source: SourceLocation,
+        reason: str,
+        automatic: bool = False,
+    ) -> None:
+        if self._frozen:
+            raise EventContributionError(reason="event contribution registry is already frozen")
+        if not isinstance(event_type, type) or not (
+            isinstance(handler_type, type) or inspect.iscoroutinefunction(handler_type)
+        ):
+            raise EventContributionError(
+                reason="event_type must be a class; handler must be a class or async function"
+            )
+        if not isinstance(phase, LocalEventPhase):
+            raise EventContributionError(reason="phase must be LocalEventPhase")
+        if not isinstance(reason, str) or not (normalized_reason := reason.strip()):
+            raise EventContributionError(reason="subscription reason must be a non-empty string")
+        declaration_index = self._counts.get(descriptor.key, 0)
+        self._counts[descriptor.key] = declaration_index + 1
+        self._entries.append(
+            _EventContribution(
+                event_type=event_type,
+                handler_type=handler_type,
+                phase=phase,
+                owner=descriptor.key,
+                source=source,
+                reason=normalized_reason,
+                declaration_index=declaration_index,
+                automatic=automatic,
+            )
+        )
+
+    def freeze(self) -> tuple[_EventContribution, ...]:
+        self._frozen = True
+        return tuple(self._entries)

python_ddd_framework/events/discovery.py

@@ -0,0 +1,105 @@
+"""解释冻结发现结果，形成一次 Application 的有序自动订阅贡献。"""
+
+from __future__ import annotations
+
+import inspect
+import types
+from collections.abc import Callable
+from typing import Any, Union, cast, get_args, get_origin
+
+from dishka import Scope
+
+from ..invocation.callables import _resolved_parameter_hints
+from ..modularity import ModuleKey, ModuleRegistry
+from ..modularity.discovery import _DiscoveredType
+from .contracts import _EVENT_HANDLER_ATTRIBUTE, LocalEventPhase, _LocalEventHandlerDefinition
+from .contribution import EventContributionRegistry
+from .errors import EventContributionError
+
+
+def _discover_event_handlers(
+    registry: ModuleRegistry,
+    discoveries: tuple[_DiscoveredType, ...],
+    contributions: EventContributionRegistry,
+) -> dict[type[object], Scope]:
+    positions = {item.key: index for index, item in enumerate(registry.dependency_order)}
+    owners: dict[type[object], ModuleKey] = {}
+    scopes: dict[type[object], Scope] = {}
+    for discovery in sorted(
+        discoveries,
+        key=lambda item: (
+            positions[item.owner],
+            f"{item.candidate.__module__}.{item.candidate.__qualname__}",
+        ),
+    ):
+        candidate = discovery.candidate
+        metadata = candidate.__dict__.get(_EVENT_HANDLER_ATTRIBUTE)
+        if metadata is None or inspect.isabstract(candidate):
+            continue
+        if not isinstance(metadata, _LocalEventHandlerDefinition):
+            raise EventContributionError(reason=f"{discovery.source}: invalid event metadata")
+        if candidate in owners:
+            if owners[candidate] != discovery.owner:
+                raise EventContributionError(
+                    reason=f"{discovery.source}: handler is already owned by {owners[candidate]}"
+                )
+            continue
+        owners[candidate] = discovery.owner
+        scopes[candidate] = (
+            Scope.ACTION if metadata.phase is LocalEventPhase.DOMAIN else Scope.REQUEST
+        )
+        for event_type in _handler_event_types(candidate):
+            contributions.add(
+                event_type=event_type,
+                handler_type=candidate,
+                phase=metadata.phase,
+                descriptor=registry.descriptors[discovery.owner],
+                source=discovery.source,
+                reason="local_event_handler declaration",
+                automatic=True,
+            )
+    return scopes
+
+
+def _handler_event_types(candidate: type[object]) -> tuple[type[object], ...]:
+    method = inspect.getattr_static(candidate, "handle", None)
+    if isinstance(method, (classmethod, staticmethod)) or not inspect.iscoroutinefunction(method):
+        raise EventContributionError(
+            reason=f"{candidate.__qualname__}.handle must be an instance async method"
+        )
+    parameters = tuple(inspect.signature(method).parameters.values())
+    if len(parameters) < 2 or parameters[1].kind not in (
+        inspect.Parameter.POSITIONAL_ONLY,
+        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+    ):
+        raise EventContributionError(
+            reason=f"{candidate.__qualname__}.handle requires an event argument"
+        )
+    event = parameters[1]
+    try:
+        hints = _resolved_parameter_hints(
+            cast(Callable[..., object], method), {event.name: event.annotation}
+        )
+    except TypeError as error:
+        raise EventContributionError(
+            reason=f"{candidate.__qualname__}.handle: unresolved event annotation"
+        ) from error
+    annotation = hints[event.name]
+    choices = (
+        get_args(annotation)
+        if get_origin(annotation) in (Union, types.UnionType)
+        else (annotation,)
+    )
+    if any(
+        not isinstance(item, type)
+        or item in (Any, type(None), inspect.Parameter.empty)
+        or get_origin(item) is not None
+        for item in choices
+    ):
+        raise EventContributionError(
+            reason=(
+                f"{candidate.__qualname__}.handle requires concrete event types, "
+                "without Any/None/generics"
+            )
+        )
+    return cast(tuple[type[object], ...], choices)

python_ddd_framework/events/errors.py

@@ -0,0 +1,48 @@
+"""Local Event contribution、cycle 与 phase-specific failure contracts。"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from ..errors.base import FrameworkError
+
+
+class EventContributionError(FrameworkError):
+    def __init__(self, *, reason: str) -> None:
+        self.reason = reason
+        super().__init__(f"Invalid local event contribution: {reason}")
+
+
+class EventCycleError(FrameworkError):
+    def __init__(self, *, event_type: type[object], ancestry: tuple[type[object], ...]) -> None:
+        self.event_type = event_type
+        self.ancestry = ancestry
+        rendered = " -> ".join(item.__qualname__ for item in (*ancestry, event_type))
+        super().__init__(f"Local event cycle detected: {rendered}")
+
+
+class LocalEventHandlerError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        event_type: type[object],
+        handler_type: type[object] | Callable[..., Awaitable[None]],
+        original_error: BaseException,
+        committed: bool,
+    ) -> None:
+        self.event_type = event_type
+        self.handler_type = handler_type
+        self.original_error = original_error
+        self.committed = committed
+        super().__init__(
+            f"Local event handler {handler_type.__module__}.{handler_type.__qualname__} failed "
+            f"for {event_type.__module__}.{event_type.__qualname__} "
+            f"(committed={committed}, error={type(original_error).__name__})"
+        )
+
+
+class PostCommitEventError(FrameworkError):
+    def __init__(self, *, failures: tuple[LocalEventHandlerError, ...]) -> None:
+        self.failures = failures
+        self.committed = True
+        super().__init__(f"Post-commit local event dispatch failed ({len(failures)} failure(s))")

python_ddd_framework/events/runtime.py

@@ -0,0 +1,192 @@
+"""UoW-owned FIFO envelopes 与 domain/post-commit dispatch。"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import Protocol
+from uuid import UUID, uuid4
+
+from dishka import AsyncContainer, Scope
+
+from ..invocation import ApplicationInvocationContext
+from ..unit_of_work.manager import UnitOfWorkManager
+from .catalog import LocalEventCatalog, LocalEventSubscription
+from .contracts import LocalEventPhase
+from .errors import EventCycleError, LocalEventHandlerError, PostCommitEventError
+
+
+@dataclass(frozen=True, slots=True)
+class _EventEnvelope:
+    envelope_id: UUID
+    invocation_id: UUID
+    parent_envelope_id: UUID | None
+    event: object
+    event_type: type[object]
+    ancestry: tuple[type[object], ...]
+
+
+class _EventHandler(Protocol):
+    async def handle(self, event: object) -> None: ...
+
+
+class _LocalEventQueue:
+    """队列只归一个具体 UoW；handler resolution 仍使用 Dishka 原生 scope。"""
+
+    __slots__ = (
+        "_action_container",
+        "_after_commit",
+        "_catalog",
+        "_context",
+        "_current",
+        "_domain",
+    )
+
+    def __init__(
+        self,
+        container: AsyncContainer,
+        context: ApplicationInvocationContext,
+        catalog: LocalEventCatalog,
+    ) -> None:
+        self._action_container = container
+        self._context = context
+        self._catalog = catalog
+        self._domain: deque[_EventEnvelope] = deque()
+        self._after_commit: deque[_EventEnvelope] = deque()
+        self._current: _EventEnvelope | None = None
+
+    def publish_domain(self, event: object) -> None:
+        self._publish(event, self._domain)
+
+    def publish_after_commit(self, event: object) -> None:
+        self._publish(event, self._after_commit)
+
+    async def _dispatch_domain(self) -> None:
+        request = (
+            self._action_container.parent_container
+            if self._action_container.scope is Scope.ACTION
+            else self._action_container
+        )
+        assert request is not None
+        # 每个 UoW 的 handler scope 独立；手动 UoW 的原调用 ACTION 可能已返回。
+        from ..application_services.invocation import _managed_action
+
+        async with _managed_action(request, self._context, committed=lambda: False) as action:
+            await self._drain_domain(action)
+
+    async def _drain_domain(self, action: AsyncContainer) -> None:
+        while self._domain:
+            envelope = self._domain.popleft()
+            await self._dispatch_envelope(
+                envelope,
+                action,
+                LocalEventPhase.DOMAIN,
+                committed=False,
+            )
+
+    async def _dispatch_after_commit(self) -> None:
+        request_container = (
+            self._action_container.parent_container
+            if self._action_container.scope is Scope.ACTION
+            else self._action_container
+        )
+        if request_container is None or request_container.registry.scope is not Scope.REQUEST:
+            raise RuntimeError("ACTION container has no REQUEST parent for post-commit dispatch")
+        failures: list[LocalEventHandlerError] = []
+        while self._after_commit:
+            envelope = self._after_commit.popleft()
+            for subscription in self._catalog.for_event(
+                envelope.event_type,
+                LocalEventPhase.AFTER_COMMIT,
+            ):
+                try:
+                    await self._invoke_handler(
+                        request_container,
+                        subscription,
+                        envelope,
+                        committed=True,
+                    )
+                except LocalEventHandlerError as failure:
+                    failures.append(failure)
+        if failures:
+            raise PostCommitEventError(failures=tuple(failures))
+
+    def _publish(self, event: object, queue: deque[_EventEnvelope]) -> None:
+        event_type = type(event)
+        parent = self._current
+        ancestry = parent.ancestry if parent is not None else ()
+        if event_type in ancestry:
+            raise EventCycleError(event_type=event_type, ancestry=ancestry)
+        queue.append(
+            _EventEnvelope(
+                envelope_id=uuid4(),
+                invocation_id=self._context.invocation_id,
+                parent_envelope_id=parent.envelope_id if parent is not None else None,
+                event=event,
+                event_type=event_type,
+                ancestry=(*ancestry, event_type),
+            )
+        )
+
+    async def _dispatch_envelope(
+        self,
+        envelope: _EventEnvelope,
+        container: AsyncContainer,
+        phase: LocalEventPhase,
+        *,
+        committed: bool,
+    ) -> None:
+        for subscription in self._catalog.for_event(envelope.event_type, phase):
+            await self._invoke_handler(
+                container,
+                subscription,
+                envelope,
+                committed=committed,
+            )
+
+    async def _invoke_handler(
+        self,
+        container: AsyncContainer,
+        subscription: LocalEventSubscription,
+        envelope: _EventEnvelope,
+        *,
+        committed: bool,
+    ) -> None:
+        previous = self._current
+        self._current = envelope
+        try:
+            from ..application_services.invocation import _InvocationRuntime
+            from ..invocation.interception import _EntryInterceptionCatalog
+
+            entries = await container.get(_EntryInterceptionCatalog)
+            runtime = await container.get(_InvocationRuntime)
+            await entries.invoke(
+                runtime, container, subscription.handler_type, "handle", (envelope.event,)
+            )
+        except Exception as original_error:
+            error = LocalEventHandlerError(
+                event_type=envelope.event_type,
+                handler_type=subscription.handler_type,
+                original_error=original_error,
+                committed=committed,
+            )
+            raise error from original_error
+        finally:
+            self._current = previous
+
+
+class LocalEventBus:
+    """发布能力解析具体 UoW 的队列；注入本身不创建 UoW 或资源。"""
+
+    def __init__(self, manager: UnitOfWorkManager) -> None:
+        self._manager = manager
+
+    def publish_domain(self, event: object) -> None:
+        work = self._manager.require_current(transactional=True)
+        assert work._event_queue is not None
+        work._event_queue.publish_domain(event)
+
+    def publish_after_commit(self, event: object) -> None:
+        work = self._manager.require_current(transactional=True)
+        assert work._event_queue is not None
+        work._event_queue.publish_after_commit(event)

python_ddd_framework/fastapi/__init__.py

@@ -0,0 +1,49 @@
+"""Optional FastAPI adapter public capability；不由 Kernel 根包重导出。"""
+
+from . import http as http
+from .adapter import FastApiAdapter
+from .contracts import (
+    ApplicationServiceRouteOverride,
+    RouterCatalog,
+    RouterRegistration,
+    WebSocketRouteRegistration,
+    contributes_routers,
+    exposes_application_services,
+)
+from .errors import FastApiAdapterError, RouteConflictError
+from .filters import ActionFilterContext, ServiceFilter, service_filter
+from .http import remote_service
+from .http_router import HttpRouter
+from .middleware import DiMiddleware
+from .realtime import (
+    FastApiRealtimeModule,
+    FastApiRealtimeOptions,
+    WebSocketConnection,
+    websocket_connection,
+)
+from .upload_limits import UploadLimits, upload_limits
+
+__all__ = (
+    "ActionFilterContext",
+    "ApplicationServiceRouteOverride",
+    "DiMiddleware",
+    "FastApiAdapter",
+    "FastApiAdapterError",
+    "FastApiRealtimeModule",
+    "FastApiRealtimeOptions",
+    "HttpRouter",
+    "RouteConflictError",
+    "RouterCatalog",
+    "RouterRegistration",
+    "ServiceFilter",
+    "UploadLimits",
+    "WebSocketConnection",
+    "WebSocketRouteRegistration",
+    "contributes_routers",
+    "exposes_application_services",
+    "http",
+    "remote_service",
+    "service_filter",
+    "upload_limits",
+    "websocket_connection",
+)