python-ddd-framework 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

python_ddd_framework/events/module.py

@@ -0,0 +1,97 @@
+"""本地事件发现、订阅目录及 UoW 阶段参与者的模块 owner。"""
+
+from dishka import DEFAULT_COMPONENT, DependencyKey, Provider, Scope
+
+from ..invocation.interception import InvocationEntry
+from ..invocation.module import InvocationModule
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+from ..services.composition import (
+    ServiceBindingContext,
+    ServiceComposition,
+    ServiceConvention,
+    ServiceDiscoveryContext,
+    ServiceValidationContext,
+)
+from ..services.convention_contracts import ConventionDiscoveryKind, _ServiceDefinition
+from ..services.native_graph import _accepted_single_service_scopes
+from ..unit_of_work.lifecycle import UnitOfWorkLifecycleFactory
+from ..unit_of_work.module import UnitOfWorkModule
+from .aggregate import AggregateEventCollector
+from .catalog import LocalEventCatalog, _build_event_catalog, _validate_event_scopes
+from .contracts import LocalEventPhase
+from .contribution import EventContributionRegistry
+from .discovery import _discover_event_handlers
+from .runtime import LocalEventBus
+from .unit_of_work import _LocalEventLifecycleFactory
+
+
+class LocalEventsModule(AppModule):
+    dependencies = (UnitOfWorkModule,)
+    catalog: LocalEventCatalog
+
+    def __init__(self) -> None:
+        self.contributions = EventContributionRegistry()
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.services.add_singleton(
+            UnitOfWorkLifecycleFactory,
+            _LocalEventLifecycleFactory,
+            multi=True,
+        )
+        context.services.add_composition(
+            ServiceComposition(
+                discover=self._discover,
+                bind=self._bind,
+                validate=self._validate,
+            )
+        )
+
+    def _discover(self, context: ServiceDiscoveryContext) -> None:
+        scopes = _discover_event_handlers(context.modules, context.discoveries, self.contributions)
+        for discovery in context.discoveries:
+            if (scope := scopes.get(discovery.candidate)) is not None:
+                context.conventions[discovery.owner, discovery.candidate] = ServiceConvention(
+                    _ServiceDefinition(provides=discovery.candidate, scope=scope),
+                    ConventionDiscoveryKind.FRAMEWORK_MARKER,
+                    "local_event_handler declaration",
+                )
+
+    def _bind(self, context: ServiceBindingContext) -> None:
+        self.catalog = _build_event_catalog(context.modules, self.contributions)
+        # 订阅入口必须有独立的最终 single binding；multi 集合不能冒充可直接解析的处理器。
+        scopes = {}
+        for item in self.catalog.subscriptions:
+            if isinstance(item.handler_type, type):
+                factory = context.arbitration.single_factory(
+                    DependencyKey(item.handler_type, DEFAULT_COMPONENT),
+                )
+                if factory is not None and factory.scope is not None:
+                    scopes[item.handler_type] = factory.scope
+        _validate_event_scopes(self.catalog, scopes)
+        invocation = context.modules.instance(InvocationModule)
+        for subscription in self.catalog.subscriptions:
+            scope = Scope.ACTION if subscription.phase is LocalEventPhase.DOMAIN else Scope.REQUEST
+            invocation.entries.append(
+                InvocationEntry(
+                    subscription.handler_type,
+                    "handle",
+                    subscription.owner,
+                    1,
+                    outer_scope=scope,
+                    method_scope=scope,
+                )
+            )
+        provider = Provider()
+        provider.provide(lambda: self.catalog, provides=LocalEventCatalog, scope=Scope.APP)
+        provider.provide(LocalEventBus, scope=Scope.REQUEST)
+        provider.provide(AggregateEventCollector, scope=Scope.ACTION)
+        context.add_provider(provider)
+
+    def _validate(self, context: ServiceValidationContext) -> None:
+        _validate_event_scopes(
+            self.catalog,
+            _accepted_single_service_scopes(
+                context.binding.arbitration.drafts, context.native_graph
+            ),
+        )

python_ddd_framework/events/runtime.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 from collections import deque
-from dataclasses import dataclass
+from contextvars import ContextVar
+from dataclasses import dataclass, field
 from typing import Protocol
 from uuid import UUID, uuid4
 
@@ -11,6 +12,7 @@ from dishka import AsyncContainer, Scope
 
 from ..invocation import ApplicationInvocationContext
 from ..unit_of_work.manager import UnitOfWorkManager
+from ..unit_of_work.options import _DEFAULT_CONNECTION_NAME
 from .catalog import LocalEventCatalog, LocalEventSubscription
 from .contracts import LocalEventPhase
 from .errors import EventCycleError, LocalEventHandlerError, PostCommitEventError
@@ -24,6 +26,7 @@ class _EventEnvelope:
     event: object
     event_type: type[object]
     ancestry: tuple[type[object], ...]
+    handled: set[object] = field(default_factory=set)
 
 
 class _EventHandler(Protocol):
@@ -55,13 +58,17 @@ class _LocalEventQueue:
         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:
+    def enqueue(
+        self, event: object, phase: LocalEventPhase | None = None, *, defer_domain: bool = True
+    ) -> _EventEnvelope:
+        envelope = self._envelope(event)
+        if phase is not LocalEventPhase.AFTER_COMMIT and defer_domain:
+            self._domain.append(envelope)
+        if phase is not LocalEventPhase.DOMAIN:
+            self._after_commit.append(envelope)
+        return envelope
+
+    async def before_commit(self) -> None:
         request = (
             self._action_container.parent_container
             if self._action_container.scope is Scope.ACTION
@@ -84,7 +91,7 @@ class _LocalEventQueue:
                 committed=False,
             )
 
-    async def _dispatch_after_commit(self) -> None:
+    async def after_commit(self) -> None:
         request_container = (
             self._action_container.parent_container
             if self._action_container.scope is Scope.ACTION
@@ -111,23 +118,34 @@ class _LocalEventQueue:
         if failures:
             raise PostCommitEventError(failures=tuple(failures))
 
-    def _publish(self, event: object, queue: deque[_EventEnvelope]) -> None:
+    def _envelope(self, event: object) -> _EventEnvelope:
         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),
-            )
+        return _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(self, event: object, phase: LocalEventPhase | None) -> None:
+        """立即派发保留 ancestry；没有 UoW 时任何阶段都不声称已提交。"""
+        envelope = self._envelope(event)
+        action = self._action_container
+        request = action.parent_container if action.scope is Scope.ACTION else action
+        assert request is not None
+        if phase is not LocalEventPhase.AFTER_COMMIT:
+            await self._dispatch_envelope(envelope, action, LocalEventPhase.DOMAIN, committed=False)
+        if phase is not LocalEventPhase.DOMAIN:
+            await self._dispatch_envelope(
+                envelope, request, LocalEventPhase.AFTER_COMMIT, committed=False
+            )
+
     async def _dispatch_envelope(
         self,
         envelope: _EventEnvelope,
@@ -152,6 +170,9 @@ class _LocalEventQueue:
         *,
         committed: bool,
     ) -> None:
+        if subscription.handler_type in envelope.handled:
+            return
+        envelope.handled.add(subscription.handler_type)
         previous = self._current
         self._current = envelope
         try:
@@ -178,15 +199,45 @@ class _LocalEventQueue:
 class LocalEventBus:
     """发布能力解析具体 UoW 的队列；注入本身不创建 UoW 或资源。"""
 
-    def __init__(self, manager: UnitOfWorkManager) -> None:
+    def __init__(self, manager: UnitOfWorkManager, catalog: LocalEventCatalog) -> None:
         self._manager = manager
+        self._catalog = catalog
+        self._immediate: ContextVar[_LocalEventQueue | None] = ContextVar(
+            "local_event_immediate", default=None
+        )
 
-    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)
+    async def publish(
+        self,
+        event: object,
+        *,
+        phase: LocalEventPhase | None = None,
+        on_unit_of_work_complete: bool = True,
+    ) -> None:
+        from .unit_of_work import _local_event_queue
+
+        if phase is not None and not isinstance(phase, LocalEventPhase):
+            raise TypeError("phase must be LocalEventPhase or None")
+        work = self._manager.current
+        if work is not None:
+            self._manager.require_current(transactional=True)
+            queue = _local_event_queue(work)
+            envelope = queue.enqueue(event, phase, defer_domain=on_unit_of_work_complete)
+            if phase is not LocalEventPhase.AFTER_COMMIT and not on_unit_of_work_complete:
+                await queue._dispatch_envelope(
+                    envelope, queue._action_container, LocalEventPhase.DOMAIN, committed=False
+                )
+            return
+        runtime = self._manager._runtime
+        async with runtime.outer_lease():
+            async with self._manager._execution_scope(_DEFAULT_CONNECTION_NAME) as action:
+                current = self._immediate.get()
+                if current is not None:
+                    await current.dispatch(event, phase)
+                    return
+                context = await action.get(ApplicationInvocationContext)
+                queue = _LocalEventQueue(action, context, self._catalog)
+                token = self._immediate.set(queue)
+                try:
+                    await queue.dispatch(event, phase)
+                finally:
+                    self._immediate.reset(token)

python_ddd_framework/events/subscription.py

@@ -0,0 +1,36 @@
+"""模块配置阶段的显式事件订阅入口。"""
+
+from collections.abc import Awaitable, Callable
+
+from ..diagnostics import LifecycleStage
+from ..diagnostics.source import caller_source
+from ..lifecycle import ConfigureContext
+from .contracts import LocalEventPhase
+from .errors import EventContributionError
+from .module import LocalEventsModule
+
+
+def subscribe_local_event(
+    context: ConfigureContext,
+    event_type: type[object],
+    handler_type: type[object] | Callable[..., Awaitable[None]],
+    phase: LocalEventPhase,
+    *,
+    reason: str,
+) -> None:
+    context.services.require_active()
+    if context.stage is not LifecycleStage.CONFIGURE:
+        raise EventContributionError(reason="subscriptions require the configure phase")
+    context.modules.require_dependency(
+        context.descriptor.key,
+        LocalEventsModule,
+        source=context.descriptor.declaration_source,
+    )
+    context.modules.instance(LocalEventsModule).contributions.add(
+        event_type=event_type,
+        handler_type=handler_type,
+        phase=phase,
+        descriptor=context.descriptor,
+        source=caller_source(str(context.descriptor.key), depth=2),
+        reason=reason,
+    )

python_ddd_framework/events/unit_of_work.py

@@ -0,0 +1,25 @@
+"""本地事件向事务生命周期贡献队列；队列仍由单个具体 UoW 持有。"""
+
+from dishka import AsyncContainer
+
+from ..invocation import ApplicationInvocationContext
+from ..unit_of_work.contracts import UnitOfWork
+from .catalog import LocalEventCatalog
+from .runtime import _LocalEventQueue
+
+
+class _LocalEventLifecycleFactory:
+    def __init__(self, catalog: LocalEventCatalog) -> None:
+        self._catalog = catalog
+
+    def create(
+        self, container: AsyncContainer, context: ApplicationInvocationContext
+    ) -> _LocalEventQueue:
+        return _LocalEventQueue(container, context, self._catalog)
+
+
+def _local_event_queue(work: UnitOfWork) -> _LocalEventQueue:
+    for lifecycle in work._lifecycles:
+        if isinstance(lifecycle, _LocalEventQueue):
+            return lifecycle
+    raise RuntimeError("Local event lifecycle is not configured for this UnitOfWork")

python_ddd_framework/extensions/__init__.py

@@ -0,0 +1,22 @@
+from .catalog import ExtensionCatalog, ExtensionContribution
+from .contracts import (
+    ExtensibleModel,
+    ExtensionPoints,
+    ExtensionProperties,
+    ExtensionTarget,
+    ModelExtension,
+    ModelExtensions,
+)
+from .module import ExtensionsModule
+
+__all__ = (
+    "ExtensibleModel",
+    "ExtensionCatalog",
+    "ExtensionContribution",
+    "ExtensionPoints",
+    "ExtensionProperties",
+    "ExtensionTarget",
+    "ExtensionsModule",
+    "ModelExtension",
+    "ModelExtensions",
+)

python_ddd_framework/extensions/catalog.py

@@ -0,0 +1,198 @@
+"""单个 Application 的有效 Pydantic 模型与扩展字段归属。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import (
+    Annotated,
+    Any,
+    TypeAliasType,
+    TypeVar,
+    cast,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from pydantic import ConfigDict, TypeAdapter, create_model
+
+from ..modularity import ModuleKey, ModuleRegistry
+from .contracts import (
+    ExtensibleModel,
+    ExtensionPoints,
+    ExtensionProperties,
+    ExtensionTarget,
+    ModelExtension,
+    ModelExtensions,
+)
+from .models import _EffectiveModels
+
+_TModel = TypeVar("_TModel", bound=ExtensibleModel)
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionContribution:
+    owner: ModuleKey
+    declaration: ModelExtension
+
+
+class ExtensionCatalog:
+    def __init__(self, modules: ModuleRegistry) -> None:
+        targets = {}
+        names: set[str] = set()
+        self._model_properties: dict[type[ExtensibleModel], type[ExtensionProperties]] = {}
+        self._properties: dict[ExtensionTarget, type[ExtensionProperties]] = {}
+        contributions: list[ExtensionContribution] = []
+        for owner, points in modules.declarations(ExtensionPoints):
+            for target in points.targets:
+                if not target.name or target.name in names or target in targets:
+                    raise ValueError("extension target must have a unique non-empty name and owner")
+                if not target.models or any(
+                    not issubclass(model, ExtensibleModel) for model in target.models
+                ):
+                    raise TypeError("extension targets require explicit ExtensibleModel DTOs")
+                targets[target] = owner
+                names.add(target.name)
+        for owner, declared in modules.declarations(ModelExtensions):
+            for extension in declared.extensions:
+                modules.require_dependency(
+                    owner.key, extension.required_module, source=owner.declaration_source
+                )
+                if extension.target not in targets:
+                    raise ValueError("extension target is not explicitly open in this Application")
+                modules.require_dependency(
+                    owner.key,
+                    targets[extension.target].module_type,
+                    source=owner.declaration_source,
+                )
+                contributions.append(ExtensionContribution(owner.key, extension))
+        self.contributions = tuple(contributions)
+        for target in targets:
+            self._build(target)
+        self._models = _EffectiveModels(self._model_properties)
+        for model in self._model_properties:
+            self._models.annotation(model)
+
+    def _build(self, target: ExtensionTarget) -> None:
+        schemas = tuple(
+            item.declaration.properties
+            for item in self.contributions
+            if item.declaration.target is target
+        )
+        core = {name for model in target.models for name in model.model_fields}
+        if target.entity_type is not None:
+            core.update(get_type_hints(target.entity_type))
+        declared: set[str] = set()
+        decorators: set[str] = set()
+        for schema in schemas:
+            _validate_schema(schema)
+            conflicts = schema.model_fields.keys() & (declared | core)
+            if conflicts:
+                raise ValueError(f"duplicate or core extension field: {sorted(conflicts)}")
+            declared.update(schema.model_fields)
+            # 原生多继承按方法名覆盖；跨贡献者同名校验/序列化方法不能静默丢失。
+            names = {
+                name
+                for base in schema.__mro__
+                if base not in ExtensionProperties.__mro__
+                for name, value in vars(base).items()
+                if not name.startswith("__") and (callable(value) or isinstance(value, classmethod))
+            }
+            if names & decorators:
+                raise ValueError("extension schemas cannot override each other's methods")
+            decorators.update(names)
+        effective = create_model(
+            target.name.replace(".", "_") + "Properties",
+            __base__=schemas or (ExtensionProperties,),
+            __config__=ConfigDict(revalidate_instances="always"),
+        )
+        assert issubclass(effective, ExtensionProperties)
+        self._properties[target] = cast(type[ExtensionProperties], effective)
+        for model in target.models:
+            if model in self._model_properties:
+                raise ValueError("a DTO cannot belong to multiple extension targets")
+            self._model_properties[model] = cast(type[ExtensionProperties], effective)
+
+    def model(self, model: type[_TModel]) -> type[_TModel]:
+        if model not in self._model_properties:
+            raise KeyError(model)
+        effective = self._models.annotation(model)
+        assert isinstance(effective, type) and issubclass(effective, model)
+        return effective
+
+    def properties(self, target: ExtensionTarget, value: object) -> ExtensionProperties:
+        return self._properties[target].model_validate(value)
+
+    def property_model(self, target: ExtensionTarget) -> type[ExtensionProperties]:
+        return self._properties[target]
+
+    def annotation(self, annotation: object) -> object:
+        return self._models.annotation(annotation)
+
+
+def _validate_schema(schema: type[ExtensionProperties]) -> None:
+    if not isinstance(schema, type) or not issubclass(schema, ExtensionProperties):
+        raise TypeError("extension declaration must use ExtensionProperties")
+    if schema.model_config.get("extra") != "forbid":
+        raise ValueError("extension properties must reject unknown fields")
+    _validate_type_schema(TypeAdapter(schema).core_schema)
+    for field in schema.model_fields.values():
+        _validate_type_parameters(field.annotation)
+        if any(
+            value is not None
+            for value in (
+                field.alias,
+                field.validation_alias,
+                field.serialization_alias,
+                field.exclude,
+            )
+        ):
+            raise ValueError("extension field identity cannot use aliases or exclusions")
+    # 原生 schema 同时拒绝不可序列化类型及改变字段归属的 serializer/computed field。
+    for mode in ("validation", "serialization"):
+        if set(schema.model_json_schema(mode=mode).get("properties", {})) != set(
+            schema.model_fields
+        ):
+            raise ValueError("extension serialization must preserve declared fields")
+
+
+def _validate_type_parameters(annotation: object) -> None:
+    # 有界 TypeVar 也不是闭合公共类型；core schema 会将其化为 bound，须保留这一声明检查。
+    if isinstance(annotation, TypeVar) or (
+        isinstance(annotation, TypeAliasType) and annotation.__type_params__
+    ):
+        raise TypeError("extension fields require concrete types")
+    args = get_args(annotation)
+    if get_origin(annotation) is Annotated:
+        args = args[:1]
+    for item in args:
+        _validate_type_parameters(item)
+
+
+def _validate_type_schema(value: Any) -> None:
+    # Pydantic 已解析别名、泛型、dataclass 和递归定义；校验同一原生 schema，
+    # 不再用 get_args 重建一套会漏掉 TypeAliasType 的类型解释器。
+    if isinstance(value, dict):
+        kind = value.get("type")
+        if isinstance(kind, str):
+            _validate_schema_node(value)
+        preserved = ("default", "metadata", "config") if isinstance(kind, str) else ()
+        for key, item in value.items():
+            if key not in preserved:
+                _validate_type_schema(item)
+    elif isinstance(value, (list, tuple)):
+        for item in value:
+            _validate_type_schema(item)
+
+
+def _validate_schema_node(schema: dict[str, Any]) -> None:
+    kind = schema["type"]
+    if kind == "any":
+        raise TypeError("extension fields require concrete types")
+    if kind == "model":
+        for field in schema["cls"].model_fields.values():
+            _validate_type_parameters(field.annotation)
+    if kind in ("model", "dataclass", "typed-dict"):
+        extra = schema.get("extra_behavior", schema.get("config", {}).get("extra_fields_behavior"))
+        if extra != "forbid" and not schema.get("root_model", False):
+            raise ValueError("nested extension models must reject unknown fields")

python_ddd_framework/extensions/contracts.py

@@ -0,0 +1,85 @@
+"""显式扩展点与类型化字段声明；不拥有解析后的应用状态或存储实现。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field, SerializeAsAny, model_validator
+
+from ..modularity import ModuleDeclaration, ModuleRef
+
+_TProperties = TypeVar("_TProperties", bound="ExtensionProperties")
+
+
+class ExtensionProperties(BaseModel):
+    """消费者继承此模型声明字段；原生 Pydantic 拥有约束、默认值和序列化。"""
+
+    model_config = ConfigDict(extra="forbid", frozen=True, validate_default=True)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _revalidate_properties(cls, value: object) -> object:
+        # 消费者静态属性类型投影为应用有效子类；保留嵌套原生值后再按有效 schema 校验。
+        if isinstance(value, ExtensionProperties) and not isinstance(value, cls):
+            return {name: getattr(value, name) for name in type(value).model_fields}
+        return value
+
+    def read(self, schema: type[_TProperties]) -> _TProperties:
+        """只读取实际有效模型包含的字段；返回消费者声明的静态类型。"""
+        if not isinstance(self, schema):
+            raise ValueError("property schema is not part of this Application's effective model")
+        return self
+
+
+class ExtensibleModel(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid", frozen=True, validate_default=True, revalidate_instances="always"
+    )
+
+    extra_properties: SerializeAsAny[ExtensionProperties] = Field(
+        default_factory=ExtensionProperties
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _revalidate_model(cls, value: object) -> object:
+        # 公共 DTO 实例进入有效子类型时也经过相同 schema，不能绕过应用隔离。
+        if isinstance(value, ExtensibleModel) and not isinstance(value, cls):
+            return {name: getattr(value, name) for name in type(value).model_fields}
+        return value
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class ExtensionTarget:
+    name: str
+    models: tuple[type[ExtensibleModel], ...]
+    entity_type: type[object] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionPoints(ModuleDeclaration):
+    targets: tuple[ExtensionTarget, ...]
+
+    @property
+    def required_module(self) -> ModuleRef:
+        return ModuleRef("python_ddd_framework.extensions.module:ExtensionsModule")
+
+
+@dataclass(frozen=True, slots=True)
+class ModelExtension(ModuleDeclaration):
+    target: ExtensionTarget
+    properties: type[ExtensionProperties]
+
+    @property
+    def required_module(self) -> ModuleRef:
+        return ModuleRef("python_ddd_framework.extensions.module:ExtensionsModule")
+
+
+@dataclass(frozen=True, slots=True)
+class ModelExtensions(ModuleDeclaration):
+    extensions: tuple[ModelExtension, ...]
+
+    @property
+    def required_module(self) -> ModuleRef:
+        return ModuleRef("python_ddd_framework.extensions.module:ExtensionsModule")