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

python_ddd_framework/services/native_graph.py

@@ -0,0 +1,201 @@
+"""只读投影原生 Dishka 图，核对平台 catalog 与实际 binding 的一致性。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import get_origin
+
+from dishka import (
+    DEFAULT_COMPONENT,
+    AsyncContainer,
+    BaseScope,
+    DependencyKey,
+    Scope,
+)
+from dishka.dependency_source import Factory
+from dishka.entities.factory_type import FactoryType
+
+from ..application_services import ApplicationService, ApplicationServiceCatalog
+from ..application_services.errors import ApplicationServiceDefinitionError
+from ..application_services.interceptors import InterceptionStage
+from ..errors import CatalogNativeGraphMismatchError, InvalidConventionDefinitionError
+from ..invocation.interception import _EntryInterceptionCatalog
+from .arbitration import (
+    _RegistrationDraft,
+)
+from .fixed_lifetime import _fixed_scope, _validate_fixed_lifetime
+from .registration import (
+    RegistrationDecision,
+    RegistrationKind,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _NativeGraphRegistration:
+    key: DependencyKey
+    scope: BaseScope
+    factory: Factory
+
+
+class _NativeServiceGraph:
+    """只读投影 Dishka 已构建图，用于证明 catalog 与真实容器一致。"""
+
+    __slots__ = ("_rows",)
+
+    def __init__(self, container: AsyncContainer) -> None:
+        rows: list[_NativeGraphRegistration] = []
+        native_registry = container.registry
+        while True:
+            rows.extend(
+                _NativeGraphRegistration(
+                    key=key,
+                    scope=native_registry.scope,
+                    factory=factory,
+                )
+                for key, factory in native_registry.factories.items()
+            )
+            child_registry = native_registry.child_registry
+            if child_registry is None:
+                break
+            native_registry = child_registry
+        self._rows = tuple(rows)
+
+    def differences(self, drafts: tuple[_RegistrationDraft, ...]) -> tuple[str, ...]:
+        return tuple(
+            f"missing accepted {draft.contribution.kind.value} registration for {draft.key}"
+            for draft in drafts
+            if draft.decision is RegistrationDecision.ACCEPTED and not self._matches(draft)
+        )
+
+    def validate_fixed_lifetimes(self) -> None:
+        for row in self._rows:
+            for candidate in (row.key.type_hint, row.factory.source):
+                # 闭合泛型仍受原始角色契约约束，函数 factory 不提供可替代的类信息。
+                candidate = get_origin(candidate) or candidate
+                scope = _fixed_scope(candidate)
+                if scope is None or not isinstance(candidate, type):
+                    continue
+                _validate_fixed_lifetime(candidate)
+                if (
+                    issubclass(candidate, ApplicationService)
+                    and row.key.component == DEFAULT_COMPONENT
+                ):
+                    # 公开 REQUEST proxy 由框架提供；其实际实现已移入私有 ACTION component。
+                    continue
+                factory = row.factory
+                # Alias 自身不缓存；沿 Dishka 已验证的链核对真正创建实例的 factory。
+                while factory.type is FactoryType.ALIAS:
+                    factory = next(
+                        item.factory for item in self._rows if item.key == factory.dependencies[0]
+                    )
+                if row.scope is not scope or not factory.cache:
+                    raise InvalidConventionDefinitionError(
+                        symbol=str(row.key.type_hint),
+                        reason=f"final fixed role binding requires cached {scope.name} lifetime",
+                    )
+
+    def scope_for(self, draft: _RegistrationDraft) -> BaseScope:
+        if draft.scope is not None:
+            return draft.scope
+        for row in self._rows:
+            if row.key == draft.key:
+                return row.scope
+        raise CatalogNativeGraphMismatchError(
+            differences=(f"native scope unavailable for {draft.key}",)
+        )
+
+    def interceptor_scope(self, interceptor: type[object]) -> BaseScope | None:
+        return next(
+            (
+                row.scope
+                for row in self._rows
+                if row.key == DependencyKey(interceptor, DEFAULT_COMPONENT)
+            ),
+            None,
+        )
+
+    def implementation_for(self, target: type[object]) -> type[object]:
+        key = DependencyKey(target, DEFAULT_COMPONENT)
+        while True:
+            factory = next(row.factory for row in self._rows if row.key == key)
+            if factory.type is FactoryType.ALIAS:
+                # 原生图已验证 alias 链及循环；沿真实依赖取得最终 class factory。
+                key = factory.dependencies[0]
+                continue
+            # 动态工厂只承诺注册契约，不能在 build 执行它来猜测运行实例。
+            return factory.source if isinstance(factory.source, type) else target
+
+    def _matches(self, draft: _RegistrationDraft) -> bool:
+        if draft.is_collection:
+            return any(
+                row.key == draft.key and row.factory.type is FactoryType.COLLECTION
+                for row in self._rows
+            )
+        assert draft.factory is not None
+        if draft.alias is not None:
+            return any(
+                row.key == draft.key
+                and row.factory.type is FactoryType.ALIAS
+                and row.factory.dependencies == draft.factory.dependencies
+                for row in self._rows
+            )
+        if draft.contribution.kind is RegistrationKind.MULTI:
+            return any(
+                row.key.type_hint == draft.key.type_hint
+                and row.key.component == draft.key.component
+                and row.factory.source is draft.factory.source
+                and row.scope is draft.scope
+                for row in self._rows
+            )
+        return any(
+            row.key == draft.key
+            and row.factory.source is draft.factory.source
+            and row.scope is draft.scope
+            for row in self._rows
+        )
+
+
+def _validate_interceptors(
+    graph: _NativeServiceGraph,
+    catalog: ApplicationServiceCatalog,
+    entries: _EntryInterceptionCatalog,
+) -> None:
+    # 匹配结果和实际入口 scope 来自同一编译 catalog，不另建后台类型或规则清单。
+    requirements = (
+        (
+            registration,
+            Scope.ACTION if registration.before is InterceptionStage.METHOD else Scope.REQUEST,
+        )
+        for service in catalog.registrations
+        for method in service.methods
+        for registration in method.interceptors
+    )
+    for registration, available in (*requirements, *entries.interceptor_scopes):
+        scope = graph.interceptor_scope(registration.interceptor)
+        if scope not in (Scope.APP, Scope.REQUEST, Scope.ACTION) or scope > available:
+            raise ApplicationServiceDefinitionError(
+                symbol=registration.interceptor.__qualname__,
+                reason=(
+                    f"interceptor scope is unavailable before {registration.before.value}; "
+                    f"owner={registration.owner}"
+                ),
+            )
+
+
+def _accepted_single_service_scopes(
+    drafts: tuple[_RegistrationDraft, ...],
+    native_graph: _NativeServiceGraph,
+) -> Mapping[type[object], BaseScope]:
+    accepted: dict[type[object], BaseScope] = {}
+    for draft in drafts:
+        key_type = draft.key.type_hint
+        if (
+            draft.decision is RegistrationDecision.ACCEPTED
+            and draft.contribution.kind is not RegistrationKind.MULTI
+            and draft.factory is not None
+            and isinstance(key_type, type)
+            and draft.key.component == DEFAULT_COMPONENT
+        ):
+            accepted[key_type] = native_graph.scope_for(draft)
+    return accepted

python_ddd_framework/services/provider.py

@@ -0,0 +1,204 @@
+"""Dishka native Provider 的受支持边界、结构验证与 mutation fingerprint。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import MethodType
+
+from dishka import BaseScope, DependencyKey, Provider
+from dishka.dependency_source import Alias, Factory, FactoryUnionMode
+from dishka.entities.factory_type import FactoryType
+from dishka.entities.marker import BoolMarker
+
+from ..diagnostics import SourceLocation
+from ..errors import RegistrationConflictError
+from .registration import SUPPORTED_SCOPE_LABEL, SUPPORTED_SCOPES, RegistrationKind
+
+
+@dataclass(frozen=True, slots=True)
+class _FactorySignature:
+    key: DependencyKey
+    scope: BaseScope | None
+    source_identity: tuple[int, int | None]
+    factory_type: FactoryType
+    dependencies: tuple[DependencyKey, ...]
+    keyword_dependencies: tuple[tuple[str, DependencyKey], ...]
+    cache: bool
+    allow_static_evaluation: bool
+    is_to_bind: bool
+    native_override: bool
+
+
+@dataclass(frozen=True, slots=True)
+class _CollectionSignature:
+    source_key: DependencyKey
+    key: DependencyKey
+    scope: BaseScope | None
+    cache: bool
+    collect: bool
+
+
+@dataclass(frozen=True, slots=True)
+class _ProviderSignature:
+    factories: tuple[_FactorySignature, ...]
+    collections: tuple[_CollectionSignature, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class _FactoryDefinition:
+    factory: Factory
+    key: DependencyKey
+    scope: BaseScope | None
+    native_override: bool
+    alias: Alias | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class _CollectionDefinition:
+    collection: FactoryUnionMode
+    source_key: DependencyKey
+    key: DependencyKey
+    scope: BaseScope | None
+
+
+@dataclass(frozen=True, slots=True)
+class _ValidatedProvider:
+    factories: tuple[_FactoryDefinition, ...]
+    collections: tuple[_CollectionDefinition, ...]
+    signature: _ProviderSignature
+
+
+class _NativeProviderInspector:
+    """隔离 Dishka private dependency-source shape，返回框架拥有的稳定事实。"""
+
+    __slots__ = ("_kind", "_source")
+
+    def __init__(self, *, source: SourceLocation, kind: RegistrationKind) -> None:
+        self._source = source
+        self._kind = kind
+
+    def inspect(self, provider: Provider) -> _ValidatedProvider:
+        if provider.decorators or provider.activators:
+            raise RegistrationConflictError(
+                key=None,
+                sources=(self._source,),
+                reason=(
+                    "service composition supports native provide/provide_all/alias/collect/"
+                    "from_context; "
+                    "decorator and activator sources are not catalog-safe"
+                ),
+            )
+        if not (
+            provider.factories
+            or provider.factory_union_mode
+            or provider.aliases
+            or provider.context_vars
+        ):
+            raise RegistrationConflictError(
+                key=None,
+                sources=(self._source,),
+                reason="native Provider contribution contains no dependency source",
+            )
+        # Alias 的执行与缓存仍使用 Dishka 原生模型；这里只归一化用于仲裁和指纹。
+        factories = (
+            *(
+                self._inspect_factory(provider, item.as_factory(provider.component))
+                for item in provider.context_vars
+            ),
+            *(self._inspect_factory(provider, item) for item in provider.factories),
+            *(
+                self._inspect_factory(provider, alias.as_factory(None, provider.component), alias)
+                for alias in provider.aliases
+            ),
+        )
+        collections = tuple(
+            self._inspect_collection(provider, item) for item in provider.factory_union_mode
+        )
+        signature = _ProviderSignature(
+            factories=tuple(
+                _FactorySignature(
+                    key=item.key,
+                    scope=item.scope,
+                    source_identity=self.source_identity(item.factory.source),
+                    factory_type=item.factory.type,
+                    dependencies=tuple(item.factory.dependencies),
+                    keyword_dependencies=tuple(sorted(item.factory.kw_dependencies.items())),
+                    cache=item.factory.cache,
+                    allow_static_evaluation=item.factory.allow_static_evaluation,
+                    is_to_bind=item.factory.is_to_bind,
+                    native_override=item.native_override,
+                )
+                for item in factories
+            ),
+            collections=tuple(
+                _CollectionSignature(
+                    source_key=item.source_key,
+                    key=item.key,
+                    scope=item.scope,
+                    cache=item.collection.cache,
+                    collect=item.collection.collect,
+                )
+                for item in collections
+            ),
+        )
+        return _ValidatedProvider(factories, collections, signature)
+
+    def _inspect_factory(
+        self,
+        provider: Provider,
+        factory: Factory,
+        alias: Alias | None = None,
+    ) -> _FactoryDefinition:
+        key = factory.provides.with_component(provider.component)
+        scope = factory.scope
+        if scope not in SUPPORTED_SCOPES and not (alias is not None and scope is None):
+            self._conflict(key, f"service scope must be {SUPPORTED_SCOPE_LABEL}")
+        if factory.allow_static_evaluation:
+            self._conflict(
+                key,
+                "native static evaluation would execute a service factory during "
+                "Application.build()",
+            )
+        if (
+            factory.when_active is not None and factory.type is not FactoryType.CONTEXT
+        ) or factory.when_dependencies:
+            self._conflict(
+                key, "conditional native factories are outside the service arbitration contract"
+            )
+        native_override = factory.when_override == BoolMarker(True)
+        if factory.when_override is not None and not native_override:
+            self._conflict(
+                key, "conditional native override is outside the service arbitration contract"
+            )
+        if (self._kind is RegistrationKind.OVERRIDE) != native_override:
+            expected = "must" if self._kind is RegistrationKind.OVERRIDE else "must not"
+            self._conflict(
+                key, f"{self._kind.value} contribution {expected} use native override=True"
+            )
+        return _FactoryDefinition(factory, key, scope, native_override, alias)
+
+    def _inspect_collection(
+        self, provider: Provider, collection: FactoryUnionMode
+    ) -> _CollectionDefinition:
+        source_key = collection.source.with_component(provider.component)
+        key = collection.provides.with_component(provider.component)
+        if self._kind is not RegistrationKind.MULTI:
+            self._conflict(
+                source_key, "native collect() must be contributed with RegistrationKind.MULTI"
+            )
+        if not collection.collect:
+            self._conflict(source_key, "multi contribution must retain native collect() semantics")
+        if collection.scope is not None and collection.scope not in SUPPORTED_SCOPES:
+            self._conflict(key, f"collection scope must be {SUPPORTED_SCOPE_LABEL}")
+        return _CollectionDefinition(collection, source_key, key, collection.scope)
+
+    def _conflict(self, key: DependencyKey, reason: str) -> None:
+        raise RegistrationConflictError(key=key, sources=(self._source,), reason=reason)
+
+    @staticmethod
+    def source_identity(source: object) -> tuple[int, int | None]:
+        if isinstance(source, MethodType):
+            # bound method 的稳定 identity 同时由 function 与 receiver 决定；
+            # 不同 Provider instance 复用同一 method 定义不是重复 factory。
+            return id(source.__func__), id(source.__self__)
+        return id(source), None

python_ddd_framework/services/registration.py

@@ -0,0 +1,101 @@
+"""Service registration intent、provenance 与 immutable catalog contracts。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import Enum
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+from dishka import BaseScope, DependencyKey, Provider, Scope
+
+from ..diagnostics import SourceLocation
+from ..modularity import ModuleKey
+
+if TYPE_CHECKING:
+    from .convention_contracts import ConventionCandidate
+
+
+SUPPORTED_SCOPES = (Scope.APP, Scope.SESSION, Scope.REQUEST, Scope.ACTION)
+SUPPORTED_SCOPE_LABEL = " or ".join(
+    f"{type(scope).__name__}.{scope.name}" for scope in SUPPORTED_SCOPES
+)
+
+
+class RegistrationKind(str, Enum):
+    DEFAULT = "default"
+    CONVENTION = "convention"
+    EXPLICIT = "explicit"
+    OVERRIDE = "override"
+    MULTI = "multi"
+
+
+class RegistrationDecision(str, Enum):
+    ACCEPTED = "accepted"
+    BACKED_OFF = "backed_off"
+    OVERRIDDEN = "overridden"
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderContribution:
+    provider: Provider
+    owner: ModuleKey
+    kind: RegistrationKind
+    source: SourceLocation
+    reason: str
+    declaration_index: int
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderContributionView:
+    owner: ModuleKey
+    kind: RegistrationKind
+    source: SourceLocation
+    reason: str
+    declaration_index: int
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceRegistration:
+    key: DependencyKey
+    scope: BaseScope
+    owner: ModuleKey
+    source: SourceLocation
+    kind: RegistrationKind
+    declaration_index: int
+    decision: RegistrationDecision
+    decision_reason: str
+    replaced_sources: tuple[SourceLocation, ...]
+    multi_ordinal: int | None
+
+
+class ServiceCatalog:
+    """Application-local 诊断目录；不保存 factory，也不参与 service resolution。"""
+
+    __slots__ = ("_by_key", "_convention_candidates", "_registrations")
+
+    def __init__(
+        self,
+        registrations: tuple[ServiceRegistration, ...],
+        convention_candidates: tuple[ConventionCandidate, ...] = (),
+    ) -> None:
+        by_key: dict[DependencyKey, list[ServiceRegistration]] = {}
+        for registration in registrations:
+            by_key.setdefault(registration.key, []).append(registration)
+        self._registrations = registrations
+        self._convention_candidates = convention_candidates
+        self._by_key: Mapping[DependencyKey, tuple[ServiceRegistration, ...]] = MappingProxyType(
+            {key: tuple(values) for key, values in by_key.items()}
+        )
+
+    @property
+    def registrations(self) -> tuple[ServiceRegistration, ...]:
+        return self._registrations
+
+    @property
+    def convention_candidates(self) -> tuple[ConventionCandidate, ...]:
+        return self._convention_candidates
+
+    def for_key(self, key: DependencyKey) -> tuple[ServiceRegistration, ...]:
+        return self._by_key.get(key, ())

python_ddd_framework/services/repository.py

@@ -0,0 +1,38 @@
+"""provider-neutral 的业务仓储契约与名义发现边界。"""
+
+from typing import Protocol
+
+from ..errors import InvalidConventionDefinitionError
+from .convention_contracts import _SERVICE_DEFINITION_ATTRIBUTE, _ServiceDefinition
+from .exposure import _business_interfaces
+
+
+class RepositoryContract(Protocol):
+    """仓储接口的正式角色；实例由选中 Module 的 REQUEST scope 缓存。"""
+
+
+def _repository_contract(candidate: type[object]) -> type[object] | None:
+    if RepositoryContract not in candidate.__mro__:
+        return None
+    contracts = tuple(
+        base
+        for base in _business_interfaces(candidate)
+        if base is not RepositoryContract and RepositoryContract in base.__mro__
+    )
+    if len(contracts) != 1:
+        raise InvalidConventionDefinitionError(
+            symbol=f"{candidate.__module__}.{candidate.__qualname__}",
+            reason="repository implementation requires one unambiguous RepositoryContract",
+        )
+    contract = contracts[0]
+    metadata = getattr(candidate, _SERVICE_DEFINITION_ATTRIBUTE, None)
+    if (
+        isinstance(metadata, _ServiceDefinition)
+        and metadata.provides is not None
+        and metadata.provides is not contract
+    ):
+        raise InvalidConventionDefinitionError(
+            symbol=f"{candidate.__module__}.{candidate.__qualname__}",
+            reason="repository service metadata cannot replace its inherited contract",
+        )
+    return contract