python-platform 0.1.1__py3-none-any.whl

python_platform/services/contribution.py

@@ -0,0 +1,438 @@
+"""一次 Application build 的 native Provider contribution ownership。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from dishka import BaseScope, Provider, Scope
+
+from ..application_services.catalog import ApplicationServiceMethod
+from ..application_services.errors import ApplicationServiceDefinitionError
+from ..application_services.interceptors import (
+    InterceptionStage,
+    Interceptor,
+    InterceptorRegistration,
+    _InterceptorRule,
+)
+from ..diagnostics import LifecycleStage, SourceLocation
+from ..diagnostics.source import caller_source
+from ..errors import RegistrationConflictError, ServiceContributorClosedError
+from ..modularity import ModuleDescriptor, ModuleKey
+from .binding import _collection_provider, _registration_providers
+from .provider import _NativeProviderInspector, _ProviderSignature
+from .registration import ProviderContribution, ProviderContributionView, RegistrationKind
+
+
+@dataclass(frozen=True, slots=True)
+class _ContributionEntry:
+    entry_id: int
+    contribution: ProviderContribution
+    signature: _ProviderSignature
+
+
+class ServiceContributor:
+    """限定到一次 Module hook 的 native Provider contribution sink。"""
+
+    __slots__ = ("_active", "_descriptor", "_registry", "_stage")
+
+    def __init__(
+        self,
+        *,
+        registry: ServiceContributionRegistry,
+        descriptor: ModuleDescriptor,
+        stage: LifecycleStage,
+    ) -> None:
+        self._registry = registry
+        self._descriptor = descriptor
+        self._stage = stage
+        self._active = True
+
+    def contribute(
+        self,
+        provider: Provider,
+        *,
+        kind: RegistrationKind = RegistrationKind.EXPLICIT,
+        reason: str,
+    ) -> None:
+        if not self._active:
+            raise ServiceContributorClosedError(stage=self._stage.value)
+        self._registry.add_from_hook(
+            provider=provider,
+            descriptor=self._descriptor,
+            stage=self._stage,
+            kind=kind,
+            reason=reason,
+            source=caller_source(str(self._descriptor.key), depth=2),
+        )
+
+    def add_singleton(
+        self,
+        service: type[object],
+        implementation: type[object] | None = None,
+        *,
+        component: str = "",
+        multi: bool = False,
+        default: bool = False,
+        override: bool = False,
+        reason: str | None = None,
+    ) -> None:
+        self._register(
+            service,
+            implementation,
+            scope=Scope.APP,
+            cache=True,
+            component=component,
+            multi=multi,
+            default=default,
+            override=override,
+            reason=reason,
+            source=caller_source(str(self._descriptor.key), depth=2),
+        )
+
+    def add_scoped(
+        self,
+        service: type[object],
+        implementation: type[object] | None = None,
+        *,
+        scope: BaseScope = Scope.REQUEST,
+        component: str = "",
+        multi: bool = False,
+        default: bool = False,
+        override: bool = False,
+        reason: str | None = None,
+    ) -> None:
+        self._register(
+            service,
+            implementation,
+            scope=scope,
+            cache=True,
+            component=component,
+            multi=multi,
+            default=default,
+            override=override,
+            reason=reason,
+            source=caller_source(str(self._descriptor.key), depth=2),
+        )
+
+    def add_transient(
+        self,
+        service: type[object],
+        implementation: type[object] | None = None,
+        *,
+        scope: BaseScope = Scope.REQUEST,
+        component: str = "",
+        multi: bool = False,
+        default: bool = False,
+        override: bool = False,
+        reason: str | None = None,
+    ) -> None:
+        self._register(
+            service,
+            implementation,
+            scope=scope,
+            cache=False,
+            component=component,
+            multi=multi,
+            default=default,
+            override=override,
+            reason=reason,
+            source=caller_source(str(self._descriptor.key), depth=2),
+        )
+
+    def _register(
+        self,
+        service: type[object],
+        implementation: type[object] | None,
+        *,
+        scope: BaseScope,
+        cache: bool,
+        component: str,
+        multi: bool,
+        default: bool,
+        override: bool,
+        reason: str | None,
+        source: SourceLocation,
+    ) -> None:
+        if not self._active:
+            raise ServiceContributorClosedError(stage=self._stage.value)
+        if override and (reason is None or not reason.strip()):
+            raise RegistrationConflictError(
+                key=None, sources=(source,), reason="explicit override requires a non-empty reason"
+            )
+        self._registry.add_registration(
+            service,
+            implementation,
+            descriptor=self._descriptor,
+            stage=self._stage,
+            scope=scope,
+            cache=cache,
+            component=component,
+            multi=multi,
+            default=default,
+            override=override,
+            reason=reason or f"service declared by {source.symbol}",
+            source=source,
+        )
+
+    @property
+    def contributions(self) -> tuple[ProviderContributionView, ...]:
+        return self._registry.snapshot()
+
+    def _close(self) -> None:
+        self._active = False
+
+    def add_interceptor(
+        self,
+        interceptor: type[Interceptor],
+        *,
+        match: Callable[[ApplicationServiceMethod], bool],
+        before: InterceptionStage = InterceptionStage.METHOD,
+    ) -> None:
+        """只贡献匹配事实；类型及依赖仍通过原生 services 注册。"""
+        if not self._active:
+            raise ServiceContributorClosedError(stage=self._stage.value)
+        if (
+            not isinstance(interceptor, type)
+            or not issubclass(interceptor, Interceptor)
+            or inspect.isabstract(interceptor)
+            or not inspect.iscoroutinefunction(interceptor.intercept)
+        ):
+            raise ApplicationServiceDefinitionError(
+                symbol=str(interceptor), reason="interceptor must implement async intercept"
+            )
+        if (
+            not callable(match)
+            or inspect.iscoroutinefunction(match)
+            or not isinstance(before, InterceptionStage)
+        ):
+            raise ApplicationServiceDefinitionError(
+                symbol=interceptor.__qualname__,
+                reason="interceptor requires a synchronous match and valid position",
+            )
+        self._registry.add_interceptor_rule(
+            _InterceptorRule(
+                InterceptorRegistration(
+                    interceptor,
+                    before,
+                    self._descriptor.key,
+                    caller_source(str(self._descriptor.key), depth=2),
+                ),
+                match,
+            )
+        )
+
+
+class ServiceContributionRegistry:
+    """一次 build 的 append-only collector；freeze 后只由仲裁流程读取。"""
+
+    __slots__ = ("_collections", "_declaration_counts", "_entries", "_frozen", "_interceptor_rules")
+
+    def __init__(self) -> None:
+        self._entries: list[_ContributionEntry] = []
+        self._declaration_counts: dict[ModuleKey, int] = {}
+        self._frozen = False
+        self._collections: set[type[object]] = set()
+        self._interceptor_rules: list[_InterceptorRule] = []
+
+    def add_interceptor_rule(self, rule: _InterceptorRule) -> None:
+        if self._frozen:
+            raise ServiceContributorClosedError(stage="interceptor")
+        self._interceptor_rules.append(rule)
+
+    @property
+    def interceptor_rules(self) -> tuple[_InterceptorRule, ...]:
+        return tuple(self._interceptor_rules)
+
+    def add_registration(
+        self,
+        service: type[object],
+        implementation: type[object] | None,
+        *,
+        descriptor: ModuleDescriptor,
+        stage: LifecycleStage,
+        scope: BaseScope,
+        cache: bool,
+        component: str,
+        multi: bool,
+        default: bool,
+        override: bool,
+        reason: str,
+        source: SourceLocation,
+    ) -> None:
+        providers = _registration_providers(
+            service,
+            implementation,
+            scope=scope,
+            cache=cache,
+            component=component,
+            multi=multi,
+            default=default,
+            override=override,
+            identity=f"{descriptor.key}.{self._declaration_counts.get(descriptor.key, 0)}",
+            source=source,
+        )
+        if multi and service not in self._collections:
+            providers += ((_collection_provider(service), RegistrationKind.MULTI),)
+            self._collections.add(service)
+        for provider, kind in providers:
+            self.add_from_hook(
+                provider=provider,
+                descriptor=descriptor,
+                stage=stage,
+                kind=kind,
+                reason=reason,
+                source=source,
+            )
+
+    def contributor(
+        self,
+        *,
+        descriptor: ModuleDescriptor,
+        stage: LifecycleStage,
+    ) -> ServiceContributor:
+        return ServiceContributor(registry=self, descriptor=descriptor, stage=stage)
+
+    def add_from_hook(
+        self,
+        *,
+        provider: Provider,
+        descriptor: ModuleDescriptor,
+        stage: LifecycleStage,
+        kind: RegistrationKind,
+        reason: str,
+        source: SourceLocation,
+    ) -> None:
+        if self._frozen:
+            raise ServiceContributorClosedError(stage=stage.value)
+        if not isinstance(provider, Provider):
+            raise RegistrationConflictError(
+                key=None,
+                sources=(source,),
+                reason="service contribution must be a native dishka.Provider",
+            )
+        if not isinstance(kind, RegistrationKind):
+            raise RegistrationConflictError(
+                key=None,
+                sources=(source,),
+                reason="registration kind must be RegistrationKind",
+            )
+        self._validate_hook_kind(kind=kind, stage=stage, source=source)
+        if not isinstance(reason, str) or not (normalized_reason := reason.strip()):
+            raise RegistrationConflictError(
+                key=None,
+                sources=(source,),
+                reason="service contribution reason must be a non-empty string",
+            )
+        validated = _NativeProviderInspector(source=source, kind=kind).inspect(provider)
+        self._append(
+            provider=provider,
+            owner=descriptor.key,
+            kind=kind,
+            source=source,
+            reason=normalized_reason,
+            signature=validated.signature,
+        )
+
+    def add_convention(
+        self,
+        *,
+        provider: Provider,
+        owner: ModuleKey,
+        source: SourceLocation,
+        reason: str,
+    ) -> None:
+        kind = RegistrationKind.CONVENTION
+        validated = _NativeProviderInspector(source=source, kind=kind).inspect(provider)
+        self._append(
+            provider=provider,
+            owner=owner,
+            kind=kind,
+            source=source,
+            reason=reason,
+            signature=validated.signature,
+        )
+
+    def _add_framework_default(
+        self,
+        *,
+        provider: Provider,
+        owner: ModuleKey,
+        source: SourceLocation,
+        reason: str,
+    ) -> None:
+        """框架 capability 的默认 binding 仍进入同一 native 仲裁与 drift guard。"""
+
+        if self._frozen:
+            raise ServiceContributorClosedError(stage="framework-default")
+        kind = RegistrationKind.DEFAULT
+        validated = _NativeProviderInspector(source=source, kind=kind).inspect(provider)
+        self._append(
+            provider=provider,
+            owner=owner,
+            kind=kind,
+            source=source,
+            reason=reason,
+            signature=validated.signature,
+        )
+
+    def freeze(self) -> tuple[_ContributionEntry, ...]:
+        self._frozen = True
+        return tuple(self._entries)
+
+    def snapshot(self) -> tuple[ProviderContributionView, ...]:
+        return tuple(
+            ProviderContributionView(
+                owner=entry.contribution.owner,
+                kind=entry.contribution.kind,
+                source=entry.contribution.source,
+                reason=entry.contribution.reason,
+                declaration_index=entry.contribution.declaration_index,
+            )
+            for entry in self._entries
+        )
+
+    def _append(
+        self,
+        *,
+        provider: Provider,
+        owner: ModuleKey,
+        kind: RegistrationKind,
+        source: SourceLocation,
+        reason: str,
+        signature: _ProviderSignature,
+    ) -> None:
+        declaration_index = self._declaration_counts.get(owner, 0)
+        self._declaration_counts[owner] = declaration_index + 1
+        contribution = ProviderContribution(
+            provider=provider,
+            owner=owner,
+            kind=kind,
+            source=source,
+            reason=reason,
+            declaration_index=declaration_index,
+        )
+        self._entries.append(_ContributionEntry(len(self._entries), contribution, signature))
+
+    @staticmethod
+    def _validate_hook_kind(
+        *,
+        kind: RegistrationKind,
+        stage: LifecycleStage,
+        source: SourceLocation,
+    ) -> None:
+        configure_kinds = (
+            RegistrationKind.DEFAULT,
+            RegistrationKind.EXPLICIT,
+            RegistrationKind.MULTI,
+        )
+        if stage is LifecycleStage.CONFIGURE and kind in configure_kinds:
+            return
+        if stage is LifecycleStage.POST_CONFIGURE and kind is RegistrationKind.OVERRIDE:
+            return
+        raise RegistrationConflictError(
+            key=None,
+            sources=(source,),
+            reason=f"registration kind {kind.value} is not allowed during {stage.value}",
+        )