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

python_ddd_framework/errors/configuration.py

@@ -0,0 +1,119 @@
+"""Configuration 与 typed Options 的结构化失败。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import FrameworkError
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel, ValidationError
+
+    from ..diagnostics import SourceLocation
+    from ..modularity import ModuleKey
+    from ..options import OptionsValidationIssue
+
+
+class ConfigurationSourceError(FrameworkError):
+    """配置来源加载或规范化失败；消息不复制可能含敏感值的底层异常文本。"""
+
+    def __init__(
+        self,
+        *,
+        source_id: str,
+        location: SourceLocation,
+        original_error: BaseException,
+    ) -> None:
+        self.source_id = source_id
+        self.location = location
+        self.original_error = original_error
+        self.__cause__ = original_error
+        self.__suppress_context__ = True
+        super().__init__(f"Unable to load configuration source {source_id!r}")
+
+
+class InvalidOptionDefinitionError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        owner: ModuleKey,
+        model_type: type[BaseModel] | None,
+        option_kind: str,
+        reason: str,
+    ) -> None:
+        self.owner = owner
+        self.model_type = model_type
+        self.option_kind = option_kind
+        self.reason = reason
+        model_name = (
+            f"{model_type.__module__}.{model_type.__qualname__}"
+            if model_type is not None
+            else "<invalid declaration>"
+        )
+        super().__init__(
+            f"Invalid {option_kind} definition {model_name} declared by {owner}: {reason}"
+        )
+
+
+class DuplicateOptionDefinitionError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        model_type: type[BaseModel],
+        option_kind: str,
+        first_owner: ModuleKey,
+        second_owner: ModuleKey,
+    ) -> None:
+        self.model_type = model_type
+        self.option_kind = option_kind
+        self.first_owner = first_owner
+        self.second_owner = second_owner
+        model_name = f"{model_type.__module__}.{model_type.__qualname__}"
+        super().__init__(
+            f"Duplicate {option_kind} definition for {model_name}: {first_owner} and {second_owner}"
+        )
+
+
+class UnknownOptionsError(FrameworkError, KeyError):
+    def __init__(self, model_type: type[BaseModel], *, option_kind: str) -> None:
+        self.model_type = model_type
+        self.option_kind = option_kind
+        model_name = f"{model_type.__module__}.{model_type.__qualname__}"
+        super().__init__(f"Unknown {option_kind} model {model_name}")
+
+
+class OptionsContributionClosedError(FrameworkError):
+    def __init__(self, *, option_kind: str, stage: str) -> None:
+        self.option_kind = option_kind
+        self.stage = stage
+        super().__init__(
+            f"{option_kind} configuration contribution is no longer active after {stage}"
+        )
+
+
+class OptionsValidationError(FrameworkError):
+    """对 Pydantic 错误增加 owner/source 语义，只保留已脱敏的 Pydantic cause。"""
+
+    def __init__(
+        self,
+        *,
+        model_type: type[BaseModel],
+        section: str,
+        owner: ModuleKey,
+        option_kind: str,
+        issues: tuple[OptionsValidationIssue, ...],
+        validation_error: ValidationError,
+    ) -> None:
+        self.model_type = model_type
+        self.section = section
+        self.owner = owner
+        self.option_kind = option_kind
+        self.issues = issues
+        self.validation_error = validation_error
+        self.__cause__ = validation_error
+        self.__suppress_context__ = True
+        model_name = f"{model_type.__module__}.{model_type.__qualname__}"
+        paths = ", ".join(issue.field_path for issue in issues) or "<model>"
+        super().__init__(
+            f"Invalid {option_kind} {model_name} at section {section!r}; fields: {paths}"
+        )

python_ddd_framework/errors/diagnostics.py

@@ -0,0 +1,12 @@
+"""Diagnostic contract 自身的边界错误。"""
+
+from .base import FrameworkError
+
+
+class InvalidDiagnosticCodeError(FrameworkError):
+    def __init__(self, code: str, *, max_length: int) -> None:
+        self.code = code
+        self.max_length = max_length
+        super().__init__(
+            f"Diagnostic code must be a stable identifier of at most {max_length} characters"
+        )

python_ddd_framework/errors/lifecycle.py

@@ -0,0 +1,164 @@
+"""Application state、lifecycle invocation 与运行失败归属。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from .base import FrameworkError
+
+if TYPE_CHECKING:
+    from ..diagnostics import LifecyclePhase, LifecycleStage, SourceLocation
+    from ..hosted_services.errors import HostedServiceLifecycleError
+    from ..lifecycle import ApplicationState
+    from ..modularity import ModuleKey
+    from .services import ContainerCleanupError
+
+
+class InvalidApplicationStateError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        operation: str,
+        current: ApplicationState,
+        allowed: tuple[ApplicationState, ...],
+    ) -> None:
+        self.operation = operation
+        self.current = current
+        self.allowed = allowed
+        allowed_values = ", ".join(state.value for state in allowed)
+        super().__init__(
+            f"Operation {operation!r} is invalid in state {current.value}; "
+            f"allowed: {allowed_values}"
+        )
+
+
+class CompositionResourceError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        module: ModuleKey,
+        stage: LifecycleStage,
+        resource_kind: str,
+    ) -> None:
+        self.module = module
+        self.stage = stage
+        self.resource_kind = resource_kind
+        super().__init__(
+            f"Composition hook {module}/{stage.value} returned forbidden {resource_kind}"
+        )
+
+
+class LifecycleReturnValueError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        module: ModuleKey,
+        phase: LifecyclePhase,
+        stage: LifecycleStage,
+        returned_type: str,
+    ) -> None:
+        self.module = module
+        self.phase = phase
+        self.stage = stage
+        self.returned_type = returned_type
+        super().__init__(
+            f"Lifecycle hook {module}/{stage.value} must return None, got {returned_type}"
+        )
+
+
+class LifecycleInvocationError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        failure_id: UUID,
+        module: ModuleKey,
+        phase: LifecyclePhase,
+        stage: LifecycleStage,
+        dependency_path: tuple[ModuleKey, ...],
+        duration_ns: int,
+        source: SourceLocation,
+        original_error: BaseException,
+    ) -> None:
+        self.failure_id = failure_id
+        self.module = module
+        self.phase = phase
+        self.stage = stage
+        self.dependency_path = dependency_path
+        self.duration_ns = duration_ns
+        self.source = source
+        # cleanup 为 best-effort 会收集 wrapper，因此构造时显式建立因果链。
+        self.__cause__ = original_error
+        self.__suppress_context__ = True
+        self.original_error = original_error
+        super().__init__(
+            f"Lifecycle invocation failed for {module}/{stage.value} "
+            f"with {type(original_error).__name__}"
+        )
+
+
+class _BackgroundExecutionStartFailure(FrameworkError):
+    """保留原始 background start failure，同时不伪造 Module lifecycle 位置。"""
+
+    failure_id = None
+    stage = None
+    dependency_path: tuple[ModuleKey, ...] = ()
+
+    def __init__(self, *, original_error: BaseException) -> None:
+        self.original_error = original_error
+        self.__cause__ = original_error
+        self.__suppress_context__ = True
+        super().__init__(f"Background execution start failed with {type(original_error).__name__}")
+
+
+class ApplicationRuntimeError(FrameworkError):
+    """运行期基础设施 fatal fact；不携带第三方异常正文或原始 cause。"""
+
+    def __init__(self, *, component: str, error_type: str) -> None:
+        self.component = component
+        self.error_type = error_type
+        # 标识一次失败事实，不持有原始异常、task 或 provider；同名失败仍是独立事实。
+        self._source = object()
+        super().__init__(f"Application runtime {component!r} failed with {error_type}")
+
+
+class ApplicationStartError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        primary: (
+            LifecycleInvocationError
+            | _BackgroundExecutionStartFailure
+            | HostedServiceLifecycleError
+        ),
+        cleanup_failures: tuple[
+            LifecycleInvocationError
+            | ContainerCleanupError
+            | _BackgroundExecutionStartFailure
+            | HostedServiceLifecycleError,
+            ...,
+        ],
+    ) -> None:
+        self.primary = primary
+        self.cleanup_failures = cleanup_failures
+        if isinstance(primary, LifecycleInvocationError):
+            location = f"{primary.module}/{primary.stage.value}"
+        elif isinstance(primary, _BackgroundExecutionStartFailure):
+            location = "background-execution"
+        else:
+            location = f"hosted-service:{primary.service}/{primary.operation}"
+        super().__init__(
+            f"Application start failed at {location}; cleanup failures: {len(cleanup_failures)}"
+        )
+
+
+def _exclude_runtime_failure(
+    error: BaseException, primary: ApplicationRuntimeError
+) -> BaseException | None:
+    # 发布 fatal 与观察 drain 可能竞争；终止 owner 才能确认哪个事实已成为主失败。
+    def same_source(item: BaseException) -> bool:
+        return isinstance(item, ApplicationRuntimeError) and item._source is primary._source
+
+    if isinstance(error, BaseExceptionGroup):
+        return error.split(same_source)[1]
+    return None if same_source(error) else error

python_ddd_framework/errors/modularity.py

@@ -0,0 +1,100 @@
+"""Module reference、graph 与 registry ownership 的结构化失败。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import FrameworkError
+
+if TYPE_CHECKING:
+    from ..diagnostics import SourceLocation
+    from ..modularity import AppModule, ModuleDependencyEdge, ModuleKey
+
+
+class InvalidModuleReferenceError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        owner: ModuleKey | None,
+        reference: str,
+        reason: str,
+        source: SourceLocation | None,
+    ) -> None:
+        self.owner = owner
+        self.reference = reference
+        self.reason = reason
+        self.source = source
+        super().__init__(f"Invalid module reference {reference!r}: {reason}")
+
+
+class ModuleResolutionError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        owner: ModuleKey | None,
+        reference: str,
+        resolution_chain: tuple[str, ...],
+        source: SourceLocation | None,
+        original_error: BaseException,
+    ) -> None:
+        self.owner = owner
+        self.reference = reference
+        self.resolution_chain = resolution_chain
+        self.source = source
+        self.original_error = original_error
+        super().__init__(f"Unable to resolve module reference {reference!r}")
+
+
+class ModuleCycleError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        startup: ModuleKey,
+        path: tuple[ModuleKey, ...],
+        edges: tuple[ModuleDependencyEdge, ...],
+    ) -> None:
+        self.startup = startup
+        self.path = path
+        self.edges = edges
+        rendered_path = " -> ".join(str(key) for key in path)
+        super().__init__(f"Module dependency cycle: {rendered_path}")
+
+
+class GraphInvariantError(FrameworkError):
+    def __init__(self, detail: str) -> None:
+        self.detail = detail
+        super().__init__(f"Module graph invariant failed: {detail}")
+
+
+class DuplicateModuleIdentityError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        key: ModuleKey,
+        first_type: type[AppModule],
+        second_type: type[AppModule],
+    ) -> None:
+        self.key = key
+        self.first_type = first_type
+        self.second_type = second_type
+        super().__init__(f"Different module classes resolved to the same key {key}")
+
+
+class ModuleInstantiationError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        module: ModuleKey,
+        source: SourceLocation,
+        original_error: BaseException,
+    ) -> None:
+        self.module = module
+        self.source = source
+        self.original_error = original_error
+        super().__init__(f"Unable to instantiate module {module}")
+
+
+class UnknownModuleError(FrameworkError, KeyError):
+    def __init__(self, module: ModuleKey) -> None:
+        self.module = module
+        super().__init__(f"Unknown module {module}")

python_ddd_framework/errors/services.py

@@ -0,0 +1,100 @@
+"""Service composition、Convention 与 native container 的结构化失败。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from .base import FrameworkError
+
+if TYPE_CHECKING:
+    from dishka import DependencyKey
+
+    from ..diagnostics import SourceLocation
+    from ..modularity import ModuleKey
+
+
+class InvalidConventionDefinitionError(FrameworkError):
+    def __init__(self, *, symbol: str, reason: str) -> None:
+        self.symbol = symbol
+        self.reason = reason
+        super().__init__(f"Invalid convention definition {symbol}: {reason}")
+
+
+class ConventionScanError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        owner: ModuleKey,
+        package: str | None,
+        source: SourceLocation,
+        reason: str,
+        original_error: BaseException | None,
+    ) -> None:
+        self.owner = owner
+        self.package = package
+        self.source = source
+        self.reason = reason
+        self.original_error = original_error
+        if original_error is not None:
+            self.__cause__ = original_error
+            self.__suppress_context__ = True
+        target = package if package is not None else "<invalid metadata>"
+        super().__init__(f"Convention scan failed for {owner}/{target}: {reason}")
+
+
+class ServiceContributorClosedError(FrameworkError):
+    def __init__(self, *, stage: str) -> None:
+        self.stage = stage
+        super().__init__(f"Service contributor is no longer active after {stage}")
+
+
+class RegistrationConflictError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        key: DependencyKey | None,
+        sources: tuple[SourceLocation, ...],
+        reason: str,
+    ) -> None:
+        self.key = key
+        self.sources = sources
+        self.reason = reason
+        rendered_key = str(key) if key is not None else "<provider>"
+        super().__init__(f"Service registration conflict for {rendered_key}: {reason}")
+
+
+class ContainerValidationError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        sources: tuple[SourceLocation, ...],
+        original_error: Exception,
+    ) -> None:
+        self.sources = sources
+        self.original_error = original_error
+        self.__cause__ = original_error
+        self.__suppress_context__ = True
+        super().__init__(
+            f"Dishka strict container validation failed with {type(original_error).__name__}"
+        )
+
+
+class CatalogNativeGraphMismatchError(FrameworkError):
+    def __init__(self, *, differences: tuple[str, ...]) -> None:
+        self.differences = differences
+        super().__init__(f"Service catalog/native graph mismatch: {len(differences)} difference(s)")
+
+
+class ContainerCleanupError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        failure_id: UUID,
+        original_error: BaseException,
+    ) -> None:
+        self.failure_id = failure_id
+        self.original_error = original_error
+        self.__cause__ = original_error
+        self.__suppress_context__ = True
+        super().__init__(f"Dishka container cleanup failed with {type(original_error).__name__}")

python_ddd_framework/events/__init__.py

@@ -0,0 +1,25 @@
+from .aggregate import AggregateEventCollector
+from .catalog import LocalEventCatalog, LocalEventSubscription
+from .contracts import LocalEventPhase, local_event_handler
+from .contribution import EventContributor
+from .errors import (
+    EventContributionError,
+    EventCycleError,
+    LocalEventHandlerError,
+    PostCommitEventError,
+)
+from .runtime import LocalEventBus
+
+__all__ = (
+    "AggregateEventCollector",
+    "EventContributionError",
+    "EventContributor",
+    "EventCycleError",
+    "LocalEventBus",
+    "LocalEventCatalog",
+    "LocalEventHandlerError",
+    "LocalEventPhase",
+    "LocalEventSubscription",
+    "PostCommitEventError",
+    "local_event_handler",
+)

python_ddd_framework/events/aggregate.py

@@ -0,0 +1,39 @@
+"""Aggregate pending events to UoW-owned local event queues."""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+from ..domain import AggregateRoot
+from ..unit_of_work.contracts import UnitOfWork
+from .runtime import LocalEventBus
+
+_TId = TypeVar("_TId")
+
+
+class AggregateEventCollector:
+    """同一事件进入 DOMAIN 与 AFTER_COMMIT 队列，聚合只释放一次。"""
+
+    __slots__ = ("_events",)
+
+    def __init__(self, events: LocalEventBus) -> None:
+        self._events = events
+
+    def collect(self, aggregate: AggregateRoot[_TId]) -> tuple[object, ...]:
+        if not isinstance(aggregate, AggregateRoot):
+            raise TypeError("aggregate must be AggregateRoot")
+        # 发布资格先于提取；拒绝非事务发布不能消耗聚合尚未交付的事件。
+        work = self._events._manager.require_current(transactional=True)
+        return _collect_aggregate_events(work, aggregate)
+
+
+def _collect_aggregate_events(
+    work: UnitOfWork, aggregate: AggregateRoot[_TId]
+) -> tuple[object, ...]:
+    # 两个公开入口先验证事务 owner；收集不触发 flush，也不恢复已释放事件或自动重放。
+    assert work._event_queue is not None
+    released = aggregate.release_local_events()
+    for event in released:
+        work._event_queue.publish_domain(event)
+        work._event_queue.publish_after_commit(event)
+    return released

python_ddd_framework/events/catalog.py

@@ -0,0 +1,136 @@
+"""Local Event phase、subscription provenance 与 immutable catalog。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+from dishka import BaseScope, Scope
+
+from ..diagnostics import SourceLocation
+from ..modularity import ModuleKey, ModuleRegistry
+from .contracts import LocalEventPhase
+from .errors import EventContributionError
+
+if TYPE_CHECKING:
+    from .contribution import EventContributionRegistry
+
+
+@dataclass(frozen=True, slots=True)
+class LocalEventSubscription:
+    event_type: type[object]
+    handler_type: type[object] | Callable[..., Awaitable[None]]
+    phase: LocalEventPhase
+    owner: ModuleKey
+    source: SourceLocation
+    reason: str
+    declaration_index: int
+    order: int
+
+
+class LocalEventCatalog:
+    __slots__ = ("_by_phase_and_type", "_subscriptions")
+
+    def __init__(self, subscriptions: tuple[LocalEventSubscription, ...]) -> None:
+        grouped: dict[tuple[LocalEventPhase, type[object]], list[LocalEventSubscription]] = {}
+        for subscription in subscriptions:
+            grouped.setdefault((subscription.phase, subscription.event_type), []).append(
+                subscription
+            )
+        self._subscriptions = subscriptions
+        self._by_phase_and_type: Mapping[
+            tuple[LocalEventPhase, type[object]], tuple[LocalEventSubscription, ...]
+        ] = MappingProxyType({key: tuple(values) for key, values in grouped.items()})
+
+    @property
+    def subscriptions(self) -> tuple[LocalEventSubscription, ...]:
+        return self._subscriptions
+
+    def for_event(
+        self,
+        event_type: type[object],
+        phase: LocalEventPhase,
+    ) -> tuple[LocalEventSubscription, ...]:
+        return self._by_phase_and_type.get((phase, event_type), ())
+
+
+def _build_event_catalog(
+    registry: ModuleRegistry,
+    contributions: EventContributionRegistry,
+) -> LocalEventCatalog:
+    module_positions = {
+        descriptor.key: index for index, descriptor in enumerate(registry.dependency_order)
+    }
+    entries = sorted(
+        contributions.freeze(),
+        key=lambda item: (module_positions[item.owner], not item.automatic, item.declaration_index),
+    )
+    seen: dict[tuple[type[object], object, LocalEventPhase], SourceLocation] = {}
+    subscriptions: list[LocalEventSubscription] = []
+    for entry in entries:
+        identity = (entry.event_type, entry.handler_type, entry.phase)
+        if identity in seen:
+            raise EventContributionError(
+                reason=(
+                    f"duplicate {entry.phase.value} subscription for "
+                    f"{entry.event_type.__qualname__}/{entry.handler_type.__qualname__}; "
+                    f"first={seen[identity]}, duplicate={entry.source}"
+                )
+            )
+        seen[identity] = entry.source
+        handler = (
+            inspect.getattr_static(entry.handler_type, "handle", None)
+            if isinstance(entry.handler_type, type)
+            else entry.handler_type
+        )
+        if isinstance(handler, (staticmethod, classmethod)) or not inspect.iscoroutinefunction(
+            handler
+        ):
+            raise EventContributionError(
+                reason=(
+                    f"{entry.handler_type.__module__}.{entry.handler_type.__qualname__}.handle "
+                    "must be an instance async method"
+                )
+            )
+        subscriptions.append(
+            LocalEventSubscription(
+                event_type=entry.event_type,
+                handler_type=entry.handler_type,
+                phase=entry.phase,
+                owner=entry.owner,
+                source=entry.source,
+                reason=entry.reason,
+                declaration_index=entry.declaration_index,
+                order=len(subscriptions),
+            )
+        )
+    return LocalEventCatalog(tuple(subscriptions))
+
+
+def _validate_event_scopes(
+    catalog: LocalEventCatalog,
+    accepted_single_scopes: Mapping[type[object], BaseScope],
+) -> None:
+    # 原生 alias 的生命周期只有最终 Dishka 图才能确定，不在贡献阶段猜测。
+    for subscription in catalog.subscriptions:
+        expected_scope = (
+            Scope.ACTION if subscription.phase is LocalEventPhase.DOMAIN else Scope.REQUEST
+        )
+        actual_scope = (
+            accepted_single_scopes.get(subscription.handler_type)
+            if isinstance(subscription.handler_type, type)
+            else expected_scope
+        )
+        if actual_scope is not expected_scope:
+            actual_label = "unregistered" if actual_scope is None else actual_scope.name
+            raise EventContributionError(
+                reason=(
+                    f"{subscription.handler_type.__module__}."
+                    f"{subscription.handler_type.__qualname__} must be "
+                    f"independently resolvable from an accepted single registration in "
+                    f"{expected_scope.name} scope, got {actual_label}"
+                )
+            )