python-platform 0.1.1__py3-none-any.whl

python_platform/services/convention.py

@@ -0,0 +1,292 @@
+"""受 Module-owned metadata 控制且完整可诊断的 Convention discovery。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Mapping
+from typing import cast
+
+from dishka import Provider, Scope
+
+from ..application_services.catalog import _DiscoveredApplicationService
+from ..application_services.contracts import (
+    _APPLICATION_SERVICE_DEFINITION_ATTRIBUTE,
+    ApplicationService,
+    _ApplicationServiceDefinition,
+)
+from ..application_services.contracts import (
+    _definition_for as _application_service_definition,
+)
+from ..application_services.errors import ApplicationServiceDefinitionError
+from ..diagnostics import SourceLocation
+from ..errors import ConventionScanError, InvalidConventionDefinitionError
+from ..modularity import ModuleKey, ModuleRegistry
+from ..modularity.discovery import _DiscoveredType
+from .arbitration import _RegistrationDraft
+from .contribution import ServiceContributionRegistry
+from .convention_contracts import (
+    _SERVICE_DEFINITION_ATTRIBUTE,
+    ConventionalService,
+    ConventionCandidate,
+    ConventionCandidateDecision,
+    ConventionDiscoveryKind,
+    ScopedDependency,
+    SingletonDependency,
+    TransientDependency,
+    _ServiceDefinition,
+)
+from .exposure import _business_interfaces
+from .registration import RegistrationDecision, RegistrationKind
+
+
+class _ConventionScanner:
+    """拥有一次 Application scan 的顺序、去重状态和 candidate diagnostics。"""
+
+    __slots__ = (
+        "_application_services",
+        "_contributions",
+        "_discoveries",
+        "_event_handler_scopes",
+        "_lifetime_conflicts",
+        "_records",
+        "_registry",
+        "_scan_packages",
+    )
+
+    def __init__(
+        self,
+        registry: ModuleRegistry,
+        contributions: ServiceContributionRegistry,
+        scan_packages: Mapping[ModuleKey, tuple[str, ...]],
+        discoveries: tuple[_DiscoveredType, ...],
+        event_handler_scopes: Mapping[type[object], Scope],
+    ) -> None:
+        self._discoveries = discoveries
+        self._event_handler_scopes = event_handler_scopes
+        self._registry = registry
+        self._contributions = contributions
+        self._scan_packages = scan_packages
+        self._records: list[ConventionCandidate] = []
+        self._application_services: list[_DiscoveredApplicationService] = []
+        self._lifetime_conflicts: set[type[object]] = set()
+
+    def validate_lifetimes(self, drafts: tuple[_RegistrationDraft, ...]) -> None:
+        for draft in drafts:
+            if (
+                draft.factory is not None
+                and isinstance(draft.factory.source, type)
+                and draft.factory.source in self._lifetime_conflicts
+                and draft.contribution.kind is RegistrationKind.CONVENTION
+                and draft.decision is RegistrationDecision.ACCEPTED
+            ):
+                candidate = draft.factory.source
+                raise InvalidConventionDefinitionError(
+                    symbol=f"{candidate.__module__}.{candidate.__qualname__}",
+                    reason="conflicting lifetime markers require explicit service metadata",
+                )
+
+    def discover(self) -> tuple[ConventionCandidate, ...]:
+        for descriptor in self._registry.dependency_order:
+            if descriptor.module_type.scan_packages != self._scan_packages[descriptor.key]:
+                raise ConventionScanError(
+                    owner=descriptor.key,
+                    package=None,
+                    source=descriptor.declaration_source,
+                    reason="scan_packages metadata was mutated after the Application snapshot",
+                    original_error=None,
+                )
+        seen: dict[ModuleKey, set[type[object]]] = {}
+        for discovery in self._discoveries:
+            self._record_candidate(discovery, seen.setdefault(discovery.owner, set()))
+        return tuple(self._records)
+
+    @property
+    def application_services(self) -> tuple[_DiscoveredApplicationService, ...]:
+        return tuple(self._application_services)
+
+    def _record_candidate(self, discovery: _DiscoveredType, seen_types: set[type[object]]) -> None:
+        candidate = discovery.candidate
+        source = discovery.source
+        owner = discovery.owner
+        package_name = discovery.package
+        definition, application_definition, discovered_by, reason = self._definition(candidate)
+        if candidate in seen_types:
+            self._append_record(
+                owner,
+                package_name,
+                source,
+                discovered_by,
+                ConventionCandidateDecision.DUPLICATE,
+                "candidate already interpreted from an earlier scan package",
+            )
+            return
+        seen_types.add(candidate)
+        if definition is None:
+            self._append_record(
+                owner,
+                package_name,
+                source,
+                discovered_by,
+                ConventionCandidateDecision.REJECTED,
+                reason,
+            )
+            return
+        provider = Provider(scope=definition.scope)
+        provider.provide(
+            candidate,
+            provides=definition.provides if definition.provides is not None else candidate,
+            scope=definition.scope,
+            cache=definition.cache,
+        )
+        if definition.provides is None:
+            for interface in _business_interfaces(candidate):
+                provider.alias(candidate, provides=interface, cache=False)
+        self._contributions.add_convention(
+            provider=provider,
+            owner=owner,
+            source=source,
+            reason=reason,
+        )
+        if application_definition is not None:
+            # 分层模块的公开契约由实际扫描它的 Module 拥有；实现 DI 的 owner 仍由上面的
+            # contribution 保留。HTTP 因此可只依赖 Contracts，不反向引用应用实现。
+            declarations = {
+                item.owner: item
+                for item in self._discoveries
+                if item.candidate is application_definition.contract
+            }
+            if len(declarations) > 1:
+                raise ApplicationServiceDefinitionError(
+                    symbol=str(application_definition.contract),
+                    reason="application service contract is scanned by multiple Modules",
+                )
+            declaration = next(iter(declarations.values()), discovery)
+            self._application_services.append(
+                _DiscoveredApplicationService(
+                    service_type=cast(type[ApplicationService], candidate),
+                    definition=application_definition,
+                    owner=declaration.owner,
+                    source=declaration.source,
+                    declaration_index=len(self._application_services),
+                )
+            )
+        self._append_record(
+            owner,
+            package_name,
+            source,
+            discovered_by,
+            ConventionCandidateDecision.ACCEPTED,
+            reason,
+        )
+
+    def _append_record(
+        self,
+        owner: ModuleKey,
+        package: str,
+        source: SourceLocation,
+        discovered_by: ConventionDiscoveryKind,
+        decision: ConventionCandidateDecision,
+        reason: str,
+    ) -> None:
+        self._records.append(
+            ConventionCandidate(
+                owner=owner,
+                package=package,
+                source=source,
+                discovered_by=discovered_by,
+                decision=decision,
+                reason=reason,
+                ordinal=len(self._records),
+            )
+        )
+
+    def _definition(
+        self,
+        candidate: type[object],
+    ) -> tuple[
+        _ServiceDefinition | None,
+        _ApplicationServiceDefinition | None,
+        ConventionDiscoveryKind,
+        str,
+    ]:
+        application_definition = _application_service_definition(candidate)
+        if application_definition is not None:
+            if _SERVICE_DEFINITION_ATTRIBUTE in candidate.__dict__:
+                raise ApplicationServiceDefinitionError(
+                    symbol=f"{candidate.__module__}.{candidate.__qualname__}",
+                    reason="application_service and service metadata cannot be combined",
+                )
+            decorated = _APPLICATION_SERVICE_DEFINITION_ATTRIBUTE in candidate.__dict__
+            discovered_by = (
+                ConventionDiscoveryKind.APPLICATION_SERVICE_DECORATOR
+                if decorated
+                else ConventionDiscoveryKind.FRAMEWORK_MARKER
+            )
+            reason = (
+                "accepted from immutable application_service decorator metadata"
+                if decorated
+                else "accepted from unique inherited ApplicationService contract"
+            )
+            return (
+                _ServiceDefinition(
+                    provides=application_definition.contract or candidate,
+                    scope=Scope.ACTION,
+                ),
+                application_definition,
+                discovered_by,
+                reason,
+            )
+        metadata = candidate.__dict__.get(_SERVICE_DEFINITION_ATTRIBUTE)
+        if metadata is not None:
+            if not isinstance(metadata, _ServiceDefinition):
+                raise InvalidConventionDefinitionError(
+                    symbol=f"{candidate.__module__}.{candidate.__qualname__}",
+                    reason="service decorator metadata has an invalid runtime shape",
+                )
+            return (
+                metadata,
+                None,
+                ConventionDiscoveryKind.DECORATOR_METADATA,
+                "accepted from immutable service decorator metadata",
+            )
+        if candidate in self._event_handler_scopes:
+            return (
+                _ServiceDefinition(provides=candidate, scope=self._event_handler_scopes[candidate]),
+                None,
+                ConventionDiscoveryKind.DECORATOR_METADATA,
+                "accepted from immutable local_event_handler metadata",
+            )
+        lifetimes = tuple(
+            (marker, scope, cache)
+            for marker, scope, cache in (
+                (SingletonDependency, Scope.APP, True),
+                (ScopedDependency, Scope.REQUEST, True),
+                (TransientDependency, Scope.REQUEST, False),
+            )
+            if candidate is not marker and issubclass(candidate, marker)
+        )
+        if lifetimes and not inspect.isabstract(candidate):
+            if len(lifetimes) != 1:
+                # 冲突先挂起到统一仲裁后；若约定 factory 胜出，容器构建前必定拒绝。
+                # 显式覆盖链可以让它退让，扫描阶段不自行挑选有效注册。
+                self._lifetime_conflicts.add(candidate)
+            marker, scope, cache = lifetimes[0]
+            return (
+                _ServiceDefinition(provides=None, scope=scope, cache=cache),
+                None,
+                ConventionDiscoveryKind.FRAMEWORK_MARKER,
+                f"accepted from {marker.__name__} marker",
+            )
+        if issubclass(candidate, ConventionalService) and candidate is not ConventionalService:
+            return (
+                _ServiceDefinition(provides=candidate, scope=Scope.APP),
+                None,
+                ConventionDiscoveryKind.FRAMEWORK_MARKER,
+                "accepted from ConventionalService marker",
+            )
+        return (
+            None,
+            None,
+            ConventionDiscoveryKind.NONE,
+            "rejected because no service decorator metadata or framework marker exists",
+        )

python_platform/services/convention_contracts.py

@@ -0,0 +1,94 @@
+"""Convention metadata、candidate diagnostics 与显式 marker contract。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import TypeVar
+
+from dishka import BaseScope, Scope
+
+from ..diagnostics import SourceLocation
+from ..errors import InvalidConventionDefinitionError
+from ..modularity import ModuleKey
+from .registration import SUPPORTED_SCOPE_LABEL, SUPPORTED_SCOPES
+
+_SERVICE_DEFINITION_ATTRIBUTE = "__python_platform_service_definition__"
+_TService = TypeVar("_TService")
+
+
+class ConventionDiscoveryKind(str, Enum):
+    DECORATOR_METADATA = "decorator_metadata"
+    FRAMEWORK_MARKER = "framework_marker"
+    APPLICATION_SERVICE_DECORATOR = "application_service_decorator"
+    NONE = "none"
+
+
+class ConventionCandidateDecision(str, Enum):
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+    DUPLICATE = "duplicate"
+
+
+@dataclass(frozen=True, slots=True)
+class ConventionCandidate:
+    owner: ModuleKey
+    package: str
+    source: SourceLocation
+    discovered_by: ConventionDiscoveryKind
+    decision: ConventionCandidateDecision
+    reason: str
+    ordinal: int
+
+
+@dataclass(frozen=True, slots=True)
+class _ServiceDefinition:
+    provides: object | None
+    scope: BaseScope
+    cache: bool = True
+
+
+class ConventionalService:
+    """只表达“按自身类型注册”的 Convention marker，不承载容器行为。"""
+
+
+class SingletonDependency:
+    """约定 APP 缓存生命周期；实例所有权仍属于 Application 的 Dishka 容器。"""
+
+
+class ScopedDependency:
+    """约定 REQUEST 缓存生命周期，不允许越过原生作用域访问。"""
+
+
+class TransientDependency:
+    """约定 REQUEST 非缓存生命周期；不缓存不等于解除作用域约束。"""
+
+
+def service(
+    *,
+    provides: object | None = None,
+    scope: BaseScope = Scope.APP,
+) -> Callable[[type[_TService]], type[_TService]]:
+    """附着 immutable definition metadata；真正解释结果仍归每个 Application。"""
+    if scope not in SUPPORTED_SCOPES:
+        raise InvalidConventionDefinitionError(
+            symbol="<decorator>", reason=f"convention scope must be {SUPPORTED_SCOPE_LABEL}"
+        )
+    definition = _ServiceDefinition(provides=provides, scope=scope)
+
+    def decorate(service_type: type[_TService]) -> type[_TService]:
+        if not isinstance(service_type, type):
+            raise InvalidConventionDefinitionError(
+                symbol=type(service_type).__qualname__,
+                reason="service decorator can only target a class",
+            )
+        if _SERVICE_DEFINITION_ATTRIBUTE in service_type.__dict__:
+            raise InvalidConventionDefinitionError(
+                symbol=f"{service_type.__module__}.{service_type.__qualname__}",
+                reason="service decorator metadata is already declared",
+            )
+        setattr(service_type, _SERVICE_DEFINITION_ATTRIBUTE, definition)
+        return service_type
+
+    return decorate

python_platform/services/exposure.py

@@ -0,0 +1,23 @@
+"""从显式继承关系解释业务接口，不按名称或结构相似度猜测注册关系。"""
+
+from __future__ import annotations
+
+import inspect
+import sys
+from abc import ABC
+from typing import Generic, Protocol
+
+
+def _business_interfaces(candidate: type[object]) -> tuple[type[object], ...]:
+    # 只接受名义继承的 Protocol/ABC；实现类和标准库角色不会成为业务契约。
+    interfaces = tuple(
+        base
+        for base in candidate.__mro__[1:]
+        if base not in (ABC, Protocol, Generic)
+        and base.__module__.partition(".")[0] not in sys.stdlib_module_names
+        and (getattr(base, "_is_protocol", False) or inspect.isabstract(base))
+    )
+    # 派生契约已经表达父契约的要求；自动契约选择只看最具体的候选。
+    return tuple(
+        base for base in interfaces if not any(base in other.__mro__[1:] for other in interfaces)
+    )

python_platform/services/framework_provider.py

@@ -0,0 +1,178 @@
+"""组装平台自有依赖与 scoped proxy；业务贡献仍由原生 Dishka 管理。"""
+
+from __future__ import annotations
+
+from dishka import (
+    Provider,
+    Scope,
+)
+
+from ..application_services import ApplicationServiceCatalog
+from ..application_services.dispatcher import _ApplicationServiceDispatcher, _proxy_factory
+from ..application_services.invocation import (
+    _InvocationRuntime,
+    _ScopedApplicationServiceInvoker,
+)
+from ..auditing.control import AuditingControl
+from ..authorization import CurrentUser, PermissionCatalog
+from ..background_jobs import BackgroundJobCatalog
+from ..background_workers import BackgroundWorkerCatalog
+from ..background_workers.runtime import _BackgroundCoordinator
+from ..caching import CacheCatalog
+from ..configuration import ConfigurationRoot
+from ..events import AggregateEventCollector, LocalEventBus, LocalEventCatalog
+from ..hosted_services import HostedServiceCatalog
+from ..hosted_services.runtime import _HostedServiceCoordinator
+from ..invocation import ApplicationInvocationContext, BackgroundSystemCaller
+from ..invocation.interception import _EntryInterceptionCatalog
+from ..modularity import ModuleRegistry
+from ..notifications import NotificationCatalog
+from ..options import Options, OptionsSnapshot
+from ..settings import SettingCatalog
+from ..unit_of_work import UnitOfWork, UnitOfWorkManager, UnitOfWorkOptions
+from ..unit_of_work.contracts import _UnitOfWorkFactory
+
+
+def _framework_provider(
+    *,
+    registry: ModuleRegistry,
+    has_unit_of_work_factory: bool,
+    entry_interceptors: _EntryInterceptionCatalog,
+    configuration: ConfigurationRoot,
+    options: OptionsSnapshot,
+    invocation_runtime: _InvocationRuntime,
+    application_service_catalog: ApplicationServiceCatalog,
+    event_catalog: LocalEventCatalog,
+    permission_catalog: PermissionCatalog,
+    cache_catalog: CacheCatalog,
+    setting_catalog: SettingCatalog,
+    notification_catalog: NotificationCatalog,
+    background_worker_catalog: BackgroundWorkerCatalog,
+    background_job_catalog: BackgroundJobCatalog,
+    background_coordinator: _BackgroundCoordinator,
+    hosted_service_catalog: HostedServiceCatalog,
+    hosted_service_coordinator: _HostedServiceCoordinator,
+) -> Provider:
+    """框架自身 contract 直接进入 Dishka；不写入业务 ServiceCatalog 第二清单。"""
+    provider = Provider()
+    provider.provide(
+        lambda: entry_interceptors, provides=_EntryInterceptionCatalog, scope=Scope.APP
+    )
+    provider.provide(AuditingControl, scope=Scope.APP)
+    _provide_unit_of_work(provider, has_unit_of_work_factory)
+    provider.provide(lambda: registry, provides=ModuleRegistry, scope=Scope.APP)
+    provider.provide(lambda: configuration, provides=ConfigurationRoot, scope=Scope.APP)
+    provider.provide(lambda: options, provides=OptionsSnapshot, scope=Scope.APP)
+    # Dishka 原生 context binding 直接发布已冻结实例，保持每个 Application 的唯一 snapshot。
+    for model_type in options.values:
+        provider.from_context(provides=Options[model_type], scope=Scope.APP)  # type: ignore[valid-type]
+    provider.provide(
+        lambda: invocation_runtime,
+        provides=_InvocationRuntime,
+        scope=Scope.APP,
+    )
+    provider.provide(
+        lambda: application_service_catalog,
+        provides=ApplicationServiceCatalog,
+        scope=Scope.APP,
+    )
+    provider.provide(lambda: event_catalog, provides=LocalEventCatalog, scope=Scope.APP)
+    provider.provide(lambda: permission_catalog, provides=PermissionCatalog, scope=Scope.APP)
+    provider.provide(lambda: cache_catalog, provides=CacheCatalog, scope=Scope.APP)
+    provider.provide(lambda: setting_catalog, provides=SettingCatalog, scope=Scope.APP)
+    provider.provide(lambda: notification_catalog, provides=NotificationCatalog, scope=Scope.APP)
+    provider.provide(
+        lambda: background_worker_catalog,
+        provides=BackgroundWorkerCatalog,
+        scope=Scope.APP,
+    )
+    provider.provide(
+        lambda: background_job_catalog,
+        provides=BackgroundJobCatalog,
+        scope=Scope.APP,
+    )
+    provider.provide(
+        lambda: background_coordinator,
+        provides=_BackgroundCoordinator,
+        scope=Scope.APP,
+    )
+    provider.provide(
+        lambda: hosted_service_catalog,
+        provides=HostedServiceCatalog,
+        scope=Scope.APP,
+    )
+    provider.provide(
+        lambda: hosted_service_coordinator,
+        provides=_HostedServiceCoordinator,
+        scope=Scope.APP,
+    )
+    provider.provide(
+        lambda: background_coordinator.system_caller,
+        provides=BackgroundSystemCaller,
+        scope=Scope.APP,
+    )
+    provider.provide(
+        _current_user,
+        provides=CurrentUser,
+        scope=Scope.REQUEST,
+    )
+    provider.from_context(provides=ApplicationInvocationContext, scope=Scope.ACTION)
+    provider.provide(
+        _ApplicationServiceDispatcher,
+        provides=_ApplicationServiceDispatcher,
+        scope=Scope.REQUEST,
+    )
+    provider.provide(
+        _ScopedApplicationServiceInvoker,
+        provides=_ScopedApplicationServiceInvoker,
+        scope=Scope.APP,
+    )
+    for registration in application_service_catalog.registrations:
+        if not registration.is_public_service:
+            continue
+        provider.provide(
+            _proxy_factory(application_service_catalog._for_registration(registration)),
+            provides=registration.contract,
+            scope=Scope.REQUEST,
+        )
+    provider.provide(LocalEventBus, provides=LocalEventBus, scope=Scope.REQUEST)
+    provider.provide(
+        AggregateEventCollector,
+        provides=AggregateEventCollector,
+        scope=Scope.ACTION,
+    )
+    for worker_type in {item.worker_type for item in background_worker_catalog.definitions}:
+        if isinstance(worker_type, type):
+            provider.provide(worker_type, provides=worker_type, scope=Scope.ACTION)
+    for handler_type in {item.handler_type for item in background_job_catalog.definitions}:
+        if isinstance(handler_type, type):
+            provider.provide(handler_type, provides=handler_type, scope=Scope.ACTION)
+    return provider
+
+
+def _current_user(invocation_runtime: _InvocationRuntime) -> CurrentUser:
+    # CurrentUser 只来自当前 Application 的 task-local request context。
+    return invocation_runtime.current_user()
+
+
+def _unit_of_work_manager(
+    runtime: _InvocationRuntime,
+    factory: _UnitOfWorkFactory,
+    options: Options[UnitOfWorkOptions],
+    catalog: LocalEventCatalog,
+) -> UnitOfWorkManager:
+    return UnitOfWorkManager(runtime, factory, options.value, catalog)
+
+
+def _current_unit_of_work(manager: UnitOfWorkManager) -> UnitOfWork:
+    return manager.require_current()
+
+
+def _provide_unit_of_work(
+    provider: Provider,
+    has_unit_of_work_factory: bool,
+) -> None:
+    if not has_unit_of_work_factory:
+        provider.provide(_UnitOfWorkFactory, scope=Scope.APP)
+    provider.provide(_unit_of_work_manager, provides=UnitOfWorkManager, scope=Scope.APP)
+    provider.provide(_current_unit_of_work, provides=UnitOfWork, scope=Scope.ACTION, cache=False)