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

python_ddd_framework/modularity/discovery.py

@@ -8,10 +8,11 @@ import pkgutil
 from collections.abc import Mapping
 from dataclasses import dataclass
 from types import MappingProxyType, ModuleType
+from typing import get_origin
 
 from ..diagnostics import SourceLocation
 from ..errors import ConventionScanError
-from .contracts import ModuleKey
+from .contracts import AppModule, ModuleKey, _module_declarations
 from .registry import ModuleDescriptor, ModuleRegistry
 
 
@@ -26,7 +27,7 @@ class _DiscoveredType:
 def _discover_types(
     registry: ModuleRegistry, packages: Mapping[ModuleKey, tuple[str, ...]]
 ) -> tuple[_DiscoveredType, ...]:
-    return tuple(
+    discoveries = tuple(
         _DiscoveredType(
             descriptor.key, package, candidate, _class_source(candidate, descriptor.key)
         )
@@ -35,6 +36,24 @@ def _discover_types(
         for module in _import_modules(descriptor, package)
         for candidate in _module_candidates(module)
     )
+    for discovery in discoveries:
+        if _is_concrete_implementation(discovery.candidate):
+            _require_type_dependencies(
+                registry, discovery.owner, discovery.candidate, source=discovery.source
+            )
+    return discoveries
+
+
+def _require_type_dependencies(
+    registry: ModuleRegistry, owner: ModuleKey, candidate: object, *, source: SourceLocation
+) -> None:
+    candidate = get_origin(candidate) or candidate
+    # 原生注册与扫描共用角色声明；Host 的同级能力不能补足贡献 owner 的依赖。
+    # Module 类本身只由正式图解释，不作为扫描/Provider owner 的服务角色。
+    if not isinstance(candidate, type) or issubclass(candidate, AppModule):
+        return
+    for declaration in _module_declarations(candidate).values():
+        registry.require_dependency(owner, declaration.required_module, source=source)
 
 
 def _import_modules(

python_ddd_framework/modularity/graph.py

@@ -7,6 +7,7 @@ import inspect
 from collections.abc import Mapping
 from graphlib import CycleError, TopologicalSorter
 from itertools import pairwise
+from types import MappingProxyType
 from typing import TypeGuard
 
 from ..diagnostics import SourceLocation
@@ -18,7 +19,15 @@ from ..errors import (
     ModuleInstantiationError,
     ModuleResolutionError,
 )
-from .contracts import AppModule, ModuleDependency, ModuleDependencyEdge, ModuleKey, ModuleRef
+from .contracts import (
+    AppModule,
+    ModuleDeclaration,
+    ModuleDependency,
+    ModuleDependencyEdge,
+    ModuleKey,
+    ModuleRef,
+    _module_declarations,
+)
 from .registry import ModuleDescriptor, ModuleRegistry
 
 
@@ -50,6 +59,7 @@ class _ModuleGraphBuilder:
         )
         self._discover(startup_type, startup_key, (), ())
         dependency_keys = self._stable_dependency_order(startup_key)
+        declarations = self._validate_declarations(dependency_keys)
         instances = self._instantiate(dependency_keys)
         descriptors = {
             key: ModuleDescriptor(
@@ -64,6 +74,7 @@ class _ModuleGraphBuilder:
                 ),
                 discovery_index=self._discovery_indices[key],
                 declaration_source=self._sources[key],
+                declarations=declarations[key],
             )
             for key in dependency_keys
         }
@@ -74,6 +85,39 @@ class _ModuleGraphBuilder:
             dependency_order=dependency_order,
         )
 
+    def _validate_declarations(
+        self, dependency_keys: tuple[ModuleKey, ...]
+    ) -> dict[ModuleKey, Mapping[str, ModuleDeclaration]]:
+        declarations: dict[ModuleKey, Mapping[str, ModuleDeclaration]] = {}
+        reachable: dict[ModuleKey, set[type[AppModule]]] = {}
+        for key in dependency_keys:
+            module_type = self._module_types[key]
+            available = {module_type}
+            for dependency in self._predecessors[key]:
+                available.update(reachable[dependency])
+            reachable[key] = available
+            # 按 Python MRO 取有效属性；声明名称和能力种类均不成为内核第二清单。
+            attributes = _module_declarations(module_type)
+            for name, value in attributes.items():
+                required, _ = self._resolve_module(
+                    value.required_module,
+                    owner=key,
+                    owner_source=self._sources[key],
+                    resolution_chain=(str(key), name),
+                )
+                if required not in available:
+                    raise InvalidModuleReferenceError(
+                        owner=key,
+                        reference=name,
+                        source=self._sources[key],
+                        reason=(
+                            f"declaration requires a dependency on "
+                            f"{required.__module__}:{required.__qualname__}"
+                        ),
+                    )
+            declarations[key] = MappingProxyType(attributes)
+        return declarations
+
     def _discover(
         self,
         module_type: type[AppModule],

python_ddd_framework/modularity/registry.py

@@ -3,12 +3,23 @@
 from __future__ import annotations
 
 from collections.abc import Iterator, Mapping
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from types import MappingProxyType
+from typing import TypeVar, cast
 
 from ..diagnostics import SourceLocation
-from ..errors import UnknownModuleError
-from .contracts import AppModule, ModuleDependencyEdge, ModuleKey
+from ..errors import InvalidModuleReferenceError, UnknownModuleError
+from .contracts import (
+    AppModule,
+    ModuleDeclaration,
+    ModuleDependency,
+    ModuleDependencyEdge,
+    ModuleKey,
+    _module_declarations,
+)
+
+_TDeclaration = TypeVar("_TDeclaration", bound=ModuleDeclaration)
+_TModule = TypeVar("_TModule", bound=AppModule)
 
 
 @dataclass(frozen=True, slots=True)
@@ -21,6 +32,9 @@ class ModuleDescriptor:
     dependency_edges: tuple[ModuleDependencyEdge, ...]
     discovery_index: int
     declaration_source: SourceLocation
+    declarations: Mapping[str, ModuleDeclaration] = field(
+        default_factory=lambda: MappingProxyType({})
+    )
 
 
 @dataclass(frozen=True, slots=True)
@@ -93,6 +107,72 @@ class ModuleRegistry:
         except KeyError:
             raise UnknownModuleError(key) from None
 
+    def declarations(
+        self, declaration_type: type[_TDeclaration]
+    ) -> tuple[tuple[ModuleDescriptor, _TDeclaration], ...]:
+        """只读取本次图冻结的声明，避免生命周期中改写 class 属性改变组装事实。"""
+        return tuple(
+            (descriptor, declaration)
+            for descriptor in self._dependency_order
+            for declaration in descriptor.declarations.values()
+            if isinstance(declaration, declaration_type)
+        )
+
+    def instance(self, module_type: type[_TModule]) -> _TModule:
+        """取得图内的 Module 组装 owner，不解析或创建任何 DI 服务。"""
+        key = ModuleKey(module_type.__module__, module_type.__qualname__)
+        descriptor = self[key]
+        if descriptor.module_type is not module_type:
+            raise UnknownModuleError(key)
+        return cast(_TModule, descriptor.instance)
+
+    def require_dependency(
+        self,
+        owner: ModuleKey,
+        dependency: ModuleDependency,
+        *,
+        source: SourceLocation,
+    ) -> None:
+        from .graph import _ModuleGraphBuilder
+
+        required, key = _ModuleGraphBuilder._resolve_module(
+            dependency,
+            owner=owner,
+            owner_source=source,
+            resolution_chain=(str(owner),),
+        )
+        pending = [owner]
+        visited: set[ModuleKey] = set()
+        while pending:
+            current = pending.pop()
+            if current in visited:
+                continue
+            visited.add(current)
+            descriptor = self[current]
+            if current == key and descriptor.module_type is required:
+                return
+            pending.extend(descriptor.dependencies)
+        raise InvalidModuleReferenceError(
+            owner=owner,
+            reference=str(key),
+            source=source,
+            reason="capability declaration requires an explicit Module dependency",
+        )
+
+    def assert_declarations_unchanged(self) -> None:
+        for descriptor in self._dependency_order:
+            current = _module_declarations(descriptor.module_type)
+            frozen = descriptor.declarations
+            if current.keys() != frozen.keys() or any(
+                current[name] is not value for name, value in frozen.items()
+            ):
+                raise InvalidModuleReferenceError(
+                    owner=descriptor.key,
+                    reference=str(descriptor.key),
+                    source=descriptor.declaration_source,
+                    reason="Module declarations changed after the Application snapshot",
+                )
+
     def __iter__(self) -> Iterator[ModuleKey]:
         return iter(self._descriptors)
 

python_ddd_framework/notifications/__init__.py

@@ -8,11 +8,13 @@ from .contracts import (
     NotificationPublishStatus,
     Notifications,
 )
+from .declarations import NotificationDefinitions
 
 __all__ = (
     "NotificationCatalog",
     "NotificationDefinition",
     "NotificationDefinitionError",
+    "NotificationDefinitions",
     "NotificationPayloadError",
     "NotificationPublishStatus",
     "Notifications",

python_ddd_framework/notifications/catalog.py

@@ -8,6 +8,7 @@ from typing import Any
 
 from ..modularity import ModuleRegistry
 from .contracts import NotificationDefinition, NotificationDefinitionError
+from .declarations import NotificationDefinitions
 
 
 class NotificationCatalog:
@@ -36,8 +37,8 @@ class NotificationCatalog:
 
 def _build_notification_catalog(registry: ModuleRegistry) -> NotificationCatalog:
     definitions: list[NotificationDefinition[Any]] = []
-    for descriptor in registry.dependency_order:
-        declared = descriptor.module_type.notification_definitions
+    for _, declaration in registry.declarations(NotificationDefinitions):
+        declared = declaration.definitions
         if not isinstance(declared, tuple):
             raise NotificationDefinitionError(
                 "Module notification_definitions must be an immutable tuple"

python_ddd_framework/notifications/declarations.py

@@ -0,0 +1,18 @@
+"""通知声明由通知能力解释，传输选择仍归 Host。"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from ..modularity import AppModule, ModuleDeclaration
+from .contracts import NotificationDefinition
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationDefinitions(ModuleDeclaration):
+    definitions: tuple[NotificationDefinition[Any], ...]
+
+    @property
+    def required_module(self) -> type[AppModule]:
+        from .module import NotificationsModule
+
+        return NotificationsModule

python_ddd_framework/notifications/module.py

@@ -0,0 +1,21 @@
+"""通知目录的组装 owner；不选择或创建传输资源。"""
+
+from dishka import Provider, Scope
+
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+from ..services.composition import ServiceBindingContext, ServiceComposition
+from .catalog import NotificationCatalog, _build_notification_catalog
+
+
+class NotificationsModule(AppModule):
+    catalog: NotificationCatalog
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.services.add_composition(ServiceComposition(bind=self._bind))
+
+    def _bind(self, context: ServiceBindingContext) -> None:
+        self.catalog = _build_notification_catalog(context.modules)
+        provider = Provider()
+        provider.provide(lambda: self.catalog, provides=NotificationCatalog, scope=Scope.APP)
+        context.add_provider(provider)

python_ddd_framework/observability/logging.py

@@ -10,6 +10,7 @@ from pythonjsonlogger.json import JsonFormatter
 from python_ddd_framework import ConfigureContext
 
 from ..application_services.invocation import _InvocationRuntime
+from ..invocation.module import InvocationModule
 from ..lifecycle import PreInitializeContext, ShutdownContext
 from ..modularity import AppModule
 from .formatting import _DIAGNOSTIC_FIELDS, _SafeTextFormatter
@@ -65,6 +66,8 @@ class _SafeJsonFormatter(_SafeTextFormatter, JsonFormatter):
 
 
 class StructuredLoggingModule(AppModule):
+    dependencies = (InvocationModule,)
+
     def configure(self, context: ConfigureContext) -> None:
         context.configure(LoggingOptions, section="logging")
 

python_ddd_framework/observability/tracing.py

@@ -12,6 +12,7 @@ from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
 
 from ..application_services.invocation import _InvocationRuntime
+from ..invocation.module import InvocationModule
 from ..lifecycle import ConfigureContext, PreInitializeContext, ShutdownContext
 from ..modularity import AppModule
 from ..options import Options
@@ -22,6 +23,8 @@ _LOGGER = logging.getLogger(__name__)
 
 
 class TracingModule(AppModule):
+    dependencies = (InvocationModule,)
+
     def __init__(self) -> None:
         self._provider: TracerProvider | None = None
         self._export_filter: _ExportDiagnosticFilter | None = None

python_ddd_framework/options/contribution.py

@@ -60,3 +60,15 @@ class _OptionsContributor:
 
     def _close(self) -> None:
         self._active = False
+
+    def default(self, model_type: type[TOptions], *, section: str) -> None:
+        """贡献能力默认选项；显式声明仍在全局阶段屏障后优先生效。"""
+        if not self._active:
+            raise OptionsContributionClosedError(option_kind=self._kind, stage=self._stage.value)
+        self._registry.declare_default(model_type, section, owner=self._owner)
+
+    def section(self, section: str) -> None:
+        """登记由该能力自行验证的配置节，不生成第二套 Options 模型。"""
+        if not self._active:
+            raise OptionsContributionClosedError(option_kind=self._kind, stage=self._stage.value)
+        self._registry.declare_section(section)

python_ddd_framework/options/registry.py

@@ -10,7 +10,7 @@ from pydantic import BaseModel, ValidationError
 
 from ..configuration.immutability import freeze_typed_value
 from ..configuration.root import ConfigurationRoot
-from ..configuration.values import MISSING, freeze_value, normalize_mapping
+from ..configuration.values import MISSING, canonical_path, freeze_value, normalize_mapping
 from ..diagnostics import LifecycleStage
 from ..errors import (
     DuplicateOptionDefinitionError,
@@ -42,7 +42,15 @@ from .validation import _validate_input
 class _OptionsRegistry:
     """一次 Application build 的 definitions 与 append-only patch owner。"""
 
-    __slots__ = ("_claims", "_definitions", "_kind", "_ordered", "_patches")
+    __slots__ = (
+        "_claims",
+        "_defaults",
+        "_definitions",
+        "_kind",
+        "_ordered",
+        "_patches",
+        "_sections",
+    )
 
     def __init__(
         self,
@@ -55,10 +63,15 @@ class _OptionsRegistry:
         self._claims = claims
         self._kind = kind
         self._patches: list[_OptionPatch] = []
+        self._defaults: list[_OwnedOptionDefinition] = []
+        self._sections: set[str] = set()
 
     @property
     def sections(self) -> frozenset[str]:
-        return frozenset(owned.definition.section for owned in self._ordered)
+        return frozenset(owned.definition.section for owned in self._ordered) | self._sections
+
+    def declare_section(self, section: str) -> None:
+        self._sections.add(".".join(canonical_path(section)))
 
     def mapping_paths(
         self,
@@ -126,14 +139,20 @@ class _OptionsRegistry:
     def declare_default(
         self, model_type: type[BaseModel], section: str, *, owner: ModuleDescriptor
     ) -> None:
-        if model_type not in self._definitions:
-            self.declare(
-                model_type,
-                section,
-                secret_paths=frozenset(),
-                owner=owner,
-                stage=LifecycleStage.POST_CONFIGURE,
-            )
+        definition = _validate_definition(
+            _OptionDefinition(model_type, section, frozenset()), owner=owner, kind=self._kind
+        )
+        for existing in self._defaults:
+            if existing.definition.model_type is model_type:
+                raise DuplicateOptionDefinitionError(
+                    model_type=model_type,
+                    option_kind=self._kind,
+                    first_owner=existing.owner.key,
+                    second_owner=owner.key,
+                )
+        self._defaults.append(
+            _OwnedOptionDefinition(definition, owner, LifecycleStage.CONFIGURE, None)
+        )
 
     def patch(
         self,
@@ -174,10 +193,24 @@ class _OptionsRegistry:
     def bind_options(self, configuration: ConfigurationRoot) -> OptionsSnapshot:
         return OptionsSnapshot(self._bind(configuration), kind=self._kind)
 
+    def _apply_defaults(self) -> None:
+        # 默认声明归能力模块；等所有显式声明和覆盖完成后再补齐，不能依赖 configure 顺序抢占。
+        for default in self._defaults:
+            definition = default.definition
+            if definition.model_type not in self._definitions:
+                self.declare(
+                    definition.model_type,
+                    definition.section,
+                    secret_paths=definition.secret_paths,
+                    owner=default.owner,
+                    stage=default.stage,
+                )
+
     def _bind(
         self,
         configuration: ConfigurationRoot,
     ) -> Mapping[type[BaseModel], BaseModel]:
+        self._apply_defaults()
         configuration = configuration._bind_input_keys(self.mapping_paths, sections=self.sections)
         for patch in self._patches:
             if patch.model_type not in self._definitions:

python_ddd_framework/realtime/__init__.py

@@ -2,11 +2,12 @@
 
 from .contracts import RealtimePublisher
 from .diagnostics import RealtimeDeliveryReport, RealtimeSnapshot
-from .messages import RealtimeEnvelope
+from .messages import RealtimeEnvelope, RealtimeMessage
 
 __all__ = (
     "RealtimeDeliveryReport",
     "RealtimeEnvelope",
+    "RealtimeMessage",
     "RealtimePublisher",
     "RealtimeSnapshot",
 )

python_ddd_framework/realtime/contracts.py

@@ -2,11 +2,11 @@
 
 from __future__ import annotations
 
-from collections.abc import Mapping
 from typing import Protocol, runtime_checkable
 from uuid import UUID
 
 from .diagnostics import RealtimeDeliveryReport
+from .messages import RealtimeMessage
 
 
 @runtime_checkable
@@ -14,15 +14,11 @@ class RealtimePublisher(Protocol):
     async def send_to_connection(
         self,
         connection_id: UUID,
-        *,
-        message_type: str,
-        payload: Mapping[str, object],
+        message: RealtimeMessage,
     ) -> RealtimeDeliveryReport: ...
 
     async def send_to_user(
         self,
         user_id: UUID,
-        *,
-        message_type: str,
-        payload: Mapping[str, object],
+        message: RealtimeMessage,
     ) -> RealtimeDeliveryReport: ...

python_ddd_framework/realtime/messages.py

@@ -9,15 +9,40 @@ from collections.abc import Mapping
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from types import MappingProxyType
-from typing import Final, Literal
+from typing import ClassVar, Final, Literal
 from uuid import UUID, uuid4
 
+from pydantic import BaseModel, ConfigDict
+
 from ..invocation.contracts import _is_safe_correlation_id
+from ..validation.models import _revalidate_model
 
 _MESSAGE_TYPE_PATTERN = re.compile(r"^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*\.v[1-9][0-9]*$")
 _REALTIME_SCHEMA_VERSION: Final = 1
 
 
+class RealtimeMessage(BaseModel):
+    """业务消息类型拥有稳定名称与 payload schema；envelope 仍归传输边界。"""
+
+    model_config = ConfigDict(frozen=True)
+    message_type: ClassVar[str]
+
+
+def _message_envelope(message: RealtimeMessage, correlation_id: str) -> RealtimeEnvelope:
+    if not isinstance(message, RealtimeMessage):
+        raise TypeError("realtime message must be a RealtimeMessage")
+    message_type = getattr(type(message), "message_type", None)
+    if not isinstance(message_type, str) or _MESSAGE_TYPE_PATTERN.fullmatch(message_type) is None:
+        raise ValueError("realtime message_type must be a versioned dotted name")
+    # 即使没有在线接收者也重验；model_construct 和可变嵌套字段不能绕过 schema。
+    validated = _revalidate_model(type(message), message)
+    return RealtimeEnvelope(
+        message_type=message_type,
+        correlation_id=correlation_id,
+        payload=validated.model_dump(mode="json", by_alias=True, warnings="error"),
+    )
+
+
 @dataclass(frozen=True, slots=True)
 class RealtimeEnvelope:
     """不可变、可序列化且不携带 transport/provider object 的消息。"""