python-platform 0.1.1__py3-none-any.whl

python_platform/services/arbitration.py

@@ -0,0 +1,381 @@
+"""default/explicit/override/multi 的单一仲裁策略与稳定 provider order。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from dishka import BaseScope, DependencyKey, Provider
+from dishka.dependency_source import Alias, Factory, FactoryUnionMode
+from dishka.entities.factory_type import FactoryType
+
+from ..diagnostics import SourceLocation
+from ..errors import RegistrationConflictError
+from ..modularity import ModuleRegistry
+from .contribution import _ContributionEntry
+from .provider import _NativeProviderInspector
+from .registration import (
+    ProviderContribution,
+    RegistrationDecision,
+    RegistrationKind,
+)
+
+
+@dataclass(slots=True)
+class _RegistrationDraft:
+    sequence: int
+    entry: _ContributionEntry
+    key: DependencyKey
+    scope: BaseScope | None
+    factory: Factory | None
+    collection: FactoryUnionMode | None
+    collection_source_key: DependencyKey | None
+    is_collection: bool
+    decision: RegistrationDecision = RegistrationDecision.ACCEPTED
+    decision_reason: str = "accepted by service composition policy"
+    replaced_sources: tuple[SourceLocation, ...] = ()
+    multi_ordinal: int | None = None
+    alias: Alias | None = None
+
+    @property
+    def contribution(self) -> ProviderContribution:
+        return self.entry.contribution
+
+
+@dataclass(frozen=True, slots=True)
+class _ArbitrationResult:
+    providers: tuple[Provider, ...]
+    drafts: tuple[_RegistrationDraft, ...]
+    ordered_entries: tuple[_ContributionEntry, ...]
+
+
+class _ServiceArbitrator:
+    """拥有一次 service policy decision；只修改尚未发布的 registration drafts。"""
+
+    __slots__ = ("_registry",)
+
+    def __init__(self, registry: ModuleRegistry) -> None:
+        self._registry = registry
+
+    def arbitrate(self, entries: tuple[_ContributionEntry, ...]) -> _ArbitrationResult:
+        ordered_entries = self._order_entries(entries)
+        drafts = self._create_drafts(ordered_entries)
+        factories = tuple(draft for draft in drafts if not draft.is_collection)
+        collections = tuple(draft for draft in drafts if draft.is_collection)
+        self._validate_collection_output_keys(factories, collections)
+        self._arbitrate_multi(factories, collections)
+        self._arbitrate_single(factories)
+        retained_providers = self._retained_providers(ordered_entries, drafts)
+        return _ArbitrationResult(
+            providers=retained_providers,
+            drafts=drafts,
+            ordered_entries=ordered_entries,
+        )
+
+    def _order_entries(
+        self, entries: tuple[_ContributionEntry, ...]
+    ) -> tuple[_ContributionEntry, ...]:
+        module_positions = {
+            descriptor.key: position
+            for position, descriptor in enumerate(self._registry.dependency_order)
+        }
+        return tuple(
+            sorted(
+                entries,
+                key=lambda entry: (
+                    module_positions[entry.contribution.owner],
+                    entry.contribution.declaration_index,
+                ),
+            )
+        )
+
+    @staticmethod
+    def _create_drafts(
+        entries: tuple[_ContributionEntry, ...],
+    ) -> tuple[_RegistrationDraft, ...]:
+        drafts: list[_RegistrationDraft] = []
+        for entry in entries:
+            contribution = entry.contribution
+            validated = _NativeProviderInspector(
+                source=contribution.source, kind=contribution.kind
+            ).inspect(contribution.provider)
+            if validated.signature != entry.signature:
+                raise RegistrationConflictError(
+                    key=None,
+                    sources=(contribution.source,),
+                    reason="native Provider was mutated after contribution",
+                )
+            for factory in validated.factories:
+                drafts.append(
+                    _RegistrationDraft(
+                        sequence=len(drafts),
+                        entry=entry,
+                        key=factory.key,
+                        scope=factory.scope,
+                        factory=factory.factory,
+                        collection=None,
+                        collection_source_key=None,
+                        is_collection=False,
+                        alias=factory.alias,
+                    )
+                )
+            for collection in validated.collections:
+                drafts.append(
+                    _RegistrationDraft(
+                        sequence=len(drafts),
+                        entry=entry,
+                        key=collection.key,
+                        scope=collection.scope,
+                        factory=None,
+                        collection=collection.collection,
+                        collection_source_key=collection.source_key,
+                        is_collection=True,
+                    )
+                )
+        return tuple(drafts)
+
+    @classmethod
+    def _validate_collection_output_keys(
+        cls,
+        factories: tuple[_RegistrationDraft, ...],
+        collections: tuple[_RegistrationDraft, ...],
+    ) -> None:
+        single_by_key = cls._group_by_key(
+            tuple(
+                draft
+                for draft in factories
+                if draft.contribution.kind is not RegistrationKind.MULTI
+            )
+        )
+        for collection in collections:
+            conflicts = single_by_key.get(collection.key, ())
+            if conflicts:
+                raise RegistrationConflictError(
+                    key=collection.key,
+                    sources=(
+                        collection.contribution.source,
+                        *(item.contribution.source for item in conflicts),
+                    ),
+                    reason="native collect() output key conflicts with a single binding",
+                )
+
+    @classmethod
+    def _arbitrate_multi(
+        cls,
+        factories: tuple[_RegistrationDraft, ...],
+        collections: tuple[_RegistrationDraft, ...],
+    ) -> None:
+        multi_factories = tuple(
+            draft for draft in factories if draft.contribution.kind is RegistrationKind.MULTI
+        )
+        single_by_key = cls._group_by_key(
+            tuple(
+                draft
+                for draft in factories
+                if draft.contribution.kind is not RegistrationKind.MULTI
+            )
+        )
+        collectors_by_source: dict[DependencyKey, list[_RegistrationDraft]] = {}
+        for collection in collections:
+            assert collection.collection_source_key is not None
+            collectors_by_source.setdefault(collection.collection_source_key, []).append(collection)
+
+        for key, items in cls._group_by_key(multi_factories).items():
+            if key in single_by_key:
+                raise RegistrationConflictError(
+                    key=key,
+                    sources=tuple(
+                        item.contribution.source for item in (*items, *single_by_key[key])
+                    ),
+                    reason="a dependency key cannot be both single and multi",
+                )
+            collectors = collectors_by_source.get(key, [])
+            if len(collectors) != 1:
+                raise RegistrationConflictError(
+                    key=key,
+                    sources=tuple(item.contribution.source for item in (*items, *collectors)),
+                    reason="multi key must have exactly one native collect() definition",
+                )
+            seen_sources: dict[object, _RegistrationDraft] = {}
+            for ordinal, item in enumerate(items):
+                assert item.factory is not None
+                source_identity = (
+                    tuple(item.factory.dependencies)
+                    if item.factory.type is FactoryType.ALIAS
+                    else _NativeProviderInspector.source_identity(item.factory.source)
+                )
+                previous = seen_sources.get(source_identity)
+                if previous is not None:
+                    raise RegistrationConflictError(
+                        key=key,
+                        sources=(previous.contribution.source, item.contribution.source),
+                        reason="duplicate multi contribution uses the same native factory source",
+                    )
+                seen_sources[source_identity] = item
+                item.multi_ordinal = ordinal
+                item.decision_reason = "accepted as ordered native collect() item"
+
+        for source_key, collectors in collectors_by_source.items():
+            if len(collectors) > 1:
+                raise RegistrationConflictError(
+                    key=source_key,
+                    sources=tuple(item.contribution.source for item in collectors),
+                    reason="multi key has more than one native collect() definition",
+                )
+
+    def _arbitrate_single(self, factories: tuple[_RegistrationDraft, ...]) -> None:
+        singles = tuple(
+            draft for draft in factories if draft.contribution.kind is not RegistrationKind.MULTI
+        )
+        for key, candidates in self._group_by_key(singles).items():
+            defaults = tuple(
+                candidate
+                for candidate in candidates
+                if candidate.contribution.kind
+                in (RegistrationKind.DEFAULT, RegistrationKind.CONVENTION)
+            )
+            explicits = tuple(
+                candidate
+                for candidate in candidates
+                if candidate.contribution.kind is RegistrationKind.EXPLICIT
+            )
+            overrides = tuple(
+                candidate
+                for candidate in candidates
+                if candidate.contribution.kind is RegistrationKind.OVERRIDE
+            )
+            base = self._select_single_base(key, defaults, explicits)
+            self._apply_override_chain(key, base, overrides)
+
+    @staticmethod
+    def _select_single_base(
+        key: DependencyKey,
+        defaults: tuple[_RegistrationDraft, ...],
+        explicits: tuple[_RegistrationDraft, ...],
+    ) -> _RegistrationDraft | None:
+        if len(explicits) > 1:
+            raise RegistrationConflictError(
+                key=key,
+                sources=tuple(item.contribution.source for item in explicits),
+                reason="multiple explicit single bindings require an explicit override",
+            )
+        if explicits:
+            explicit = explicits[0]
+            for default in defaults:
+                default.decision = RegistrationDecision.BACKED_OFF
+                default.decision_reason = (
+                    f"{default.contribution.reason}; backed off because explicit contribution from "
+                    f"{explicit.contribution.owner} exists"
+                )
+            explicit.decision_reason = (
+                f"{explicit.contribution.reason}; accepted as the unique explicit single binding"
+            )
+            return explicit
+        if len(defaults) > 1:
+            raise RegistrationConflictError(
+                key=key,
+                sources=tuple(item.contribution.source for item in defaults),
+                reason="multiple default/convention single bindings are ambiguous",
+            )
+        if defaults:
+            defaults[0].decision_reason = (
+                f"{defaults[0].contribution.reason}; accepted because no explicit "
+                "single binding exists"
+            )
+            return defaults[0]
+        return None
+
+    def _apply_override_chain(
+        self,
+        key: DependencyKey,
+        base: _RegistrationDraft | None,
+        overrides: tuple[_RegistrationDraft, ...],
+    ) -> None:
+        if not overrides:
+            return
+        if base is None:
+            raise RegistrationConflictError(
+                key=key,
+                sources=tuple(item.contribution.source for item in overrides),
+                reason="override target does not exist",
+            )
+        current = base
+        chain = [base.contribution.source]
+        for override in overrides:
+            descriptor = self._registry.descriptors[override.contribution.owner]
+            if current.contribution.owner not in descriptor.dependencies:
+                raise RegistrationConflictError(
+                    key=key,
+                    sources=(current.contribution.source, override.contribution.source),
+                    reason=(
+                        f"override owner {override.contribution.owner} must directly depend on "
+                        f"current target owner {current.contribution.owner}"
+                    ),
+                )
+            current.decision = RegistrationDecision.OVERRIDDEN
+            current.decision_reason = f"overridden by {override.contribution.owner}"
+            override.replaced_sources = tuple(chain)
+            override.decision_reason = f"accepted explicit override of {current.contribution.owner}"
+            chain.append(override.contribution.source)
+            current = override
+
+    @staticmethod
+    def _retained_providers(
+        entries: tuple[_ContributionEntry, ...],
+        drafts: tuple[_RegistrationDraft, ...],
+    ) -> tuple[Provider, ...]:
+        drafts_by_entry: dict[int, list[_RegistrationDraft]] = {}
+        for draft in drafts:
+            drafts_by_entry.setdefault(draft.entry.entry_id, []).append(draft)
+        retained: list[Provider] = []
+        for entry in entries:
+            entry_drafts = drafts_by_entry[entry.entry_id]
+            active = tuple(
+                draft
+                for draft in entry_drafts
+                if draft.decision is not RegistrationDecision.BACKED_OFF
+            )
+            if not active:
+                continue
+            if len(active) == len(entry_drafts):
+                retained.append(entry.contribution.provider)
+                continue
+            # 仲裁粒度是 dependency source，而 Provider 只是 native 输入批次。
+            # 局部 back-off 时仅重组原生 source 集合，不复制 factory model。
+            retained.append(_provider_with_active_sources(entry.contribution.provider, active))
+        return tuple(retained)
+
+    @staticmethod
+    def _group_by_key(
+        drafts: tuple[_RegistrationDraft, ...],
+    ) -> dict[DependencyKey, tuple[_RegistrationDraft, ...]]:
+        grouped: dict[DependencyKey, list[_RegistrationDraft]] = {}
+        try:
+            for draft in drafts:
+                grouped.setdefault(draft.key, []).append(draft)
+        except TypeError as original_error:
+            error = RegistrationConflictError(
+                key=None,
+                sources=tuple(draft.contribution.source for draft in drafts),
+                reason="native DependencyKey must be hashable",
+            )
+            raise error from original_error
+        return {key: tuple(values) for key, values in grouped.items()}
+
+
+def _provider_with_active_sources(
+    provider: Provider,
+    drafts: tuple[_RegistrationDraft, ...],
+) -> Provider:
+    retained = Provider(
+        scope=provider.scope,
+        component=provider.component,
+        when=provider.when,
+    )
+    retained.factories.extend(
+        draft.factory for draft in drafts if draft.factory is not None and draft.alias is None
+    )
+    retained.aliases.extend(draft.alias for draft in drafts if draft.alias is not None)
+    retained.factory_union_mode.extend(
+        draft.collection for draft in drafts if draft.collection is not None
+    )
+    return retained

python_platform/services/binding.py

@@ -0,0 +1,102 @@
+"""通用注册声明到 Dishka factory/alias/collect 的原生映射。"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from dishka import BaseScope, FromComponent, Provider
+
+from ..application_services.contracts import ApplicationService
+from ..diagnostics import SourceLocation
+from ..errors import RegistrationConflictError
+from .registration import RegistrationKind
+
+_COLLECTION_COMPONENT = "python_platform.services.collection"
+_REGISTRATION_COMPONENT = "python_platform.services.registration"
+
+
+def _registration_providers(
+    service: type[object],
+    implementation: type[object] | None,
+    *,
+    scope: BaseScope,
+    cache: bool,
+    component: str,
+    multi: bool,
+    default: bool,
+    override: bool,
+    identity: str,
+    source: SourceLocation,
+) -> tuple[tuple[Provider, RegistrationKind], ...]:
+    if not isinstance(service, type) or (
+        implementation is not None and not isinstance(implementation, type)
+    ):
+        raise RegistrationConflictError(
+            key=None,
+            sources=(source,),
+            reason="registration requires service and implementation classes",
+        )
+    if not isinstance(component, str) or component.startswith(
+        (_COLLECTION_COMPONENT, _REGISTRATION_COMPONENT)
+    ):
+        raise RegistrationConflictError(
+            key=None, sources=(source,), reason="component must be a non-reserved string"
+        )
+    if override and (multi or default):
+        raise RegistrationConflictError(
+            key=None, sources=(source,), reason="override cannot also declare multi or default"
+        )
+    kind = RegistrationKind.OVERRIDE if override else RegistrationKind.EXPLICIT
+    provider = Provider(scope=scope, component=component)
+    concrete = implementation or service
+    if issubclass(concrete, ApplicationService):
+        raise RegistrationConflictError(
+            key=None,
+            sources=(source,),
+            reason=(
+                "ApplicationService registration requires convention discovery "
+                "and its contract proxy"
+            ),
+        )
+    if not multi:
+        provider.provide(concrete, provides=service, cache=cache, override=override)
+        if default and component:
+            provider.alias(service, provides=Annotated[service, FromComponent("")], cache=False)
+        # default=True 是明确选择；旧 DEFAULT contribution 的 fallback 语义不参与这里。
+        return ((provider, kind),)
+
+    # 每项只有一个创建来源。公开指定项、默认项和集合项都通过原生 alias 引用它；
+    # alias 不缓存，避免把 transient 意外提升为 scoped。
+    source_component = f"{_REGISTRATION_COMPONENT}.{identity}"
+    native_source: object = Annotated[service, FromComponent(source_component)]
+    provider.provide(concrete, provides=native_source, cache=cache)
+    if component:
+        provider.alias(service, component=source_component, provides=service, cache=False)
+    if default:
+        provider.alias(
+            service,
+            component=source_component,
+            provides=Annotated[service, FromComponent("")],
+            cache=False,
+        )
+    member = Provider(scope=scope)
+    member.alias(
+        service,
+        component=source_component,
+        provides=Annotated[service, FromComponent(_COLLECTION_COMPONENT)],
+        cache=False,
+    )
+    # collect 收集 factory；用 Alias 自己的转换保留其依赖、实例身份和失败语义。
+    member.factories.extend(alias.as_factory(scope, member.component) for alias in member.aliases)
+    member.aliases.clear()
+    return ((provider, kind), (member, RegistrationKind.MULTI))
+
+
+def _collection_provider(service: type[object]) -> Provider:
+    provider = Provider()
+    provider.collect(
+        Annotated[service, FromComponent(_COLLECTION_COMPONENT)],
+        provides=list.__class_getitem__(service),
+        cache=False,
+    )
+    return provider