python-platform 0.1.1__py3-none-any.whl

python_platform/services/runtime.py

@@ -0,0 +1,298 @@
+"""Dishka container 构建、native graph 核对与 catalog 发布。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import get_origin
+
+from dishka import (
+    DEFAULT_COMPONENT,
+    STRICT_VALIDATION,
+    AsyncContainer,
+    DependencyKey,
+    make_async_container,
+)
+
+from ..application_services import ApplicationServiceCatalog
+from ..application_services.catalog import (
+    _build_application_service_catalog,
+)
+from ..application_services.invocation import (
+    _InvocationRuntime,
+)
+from ..authorization import 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 ..errors import CatalogNativeGraphMismatchError, ContainerValidationError
+from ..events import LocalEventCatalog
+from ..events.catalog import _build_event_catalog, _validate_event_scopes
+from ..events.contribution import EventContributionRegistry
+from ..events.discovery import _discover_event_handlers
+from ..hosted_services import HostedServiceCatalog
+from ..hosted_services.catalog import (
+    _validate_hosted_service_drafts,
+    _validate_hosted_service_entries,
+)
+from ..hosted_services.runtime import _HostedServiceCoordinator
+from ..invocation.entries import _validate_callable_entries
+from ..invocation.interception import _EntryInterceptionCatalog
+from ..modularity import ModuleKey, ModuleRegistry
+from ..modularity.discovery import _DiscoveredType
+from ..notifications import NotificationCatalog
+from ..options import Options, OptionsSnapshot
+from ..settings import SettingCatalog
+from ..settings.binding import _provide_settings
+from ..settings.store import RuntimeSettingStore
+from ..unit_of_work.contracts import _UnitOfWorkFactory
+from .application_bindings import (
+    _bind_application_services,
+    _runtime_providers,
+    _validate_application_service_dependencies,
+)
+from .arbitration import (
+    _RegistrationDraft,
+    _ServiceArbitrator,
+)
+from .contribution import ServiceContributionRegistry
+from .convention import _ConventionScanner
+from .convention_contracts import ConventionCandidate
+from .framework_provider import (
+    _framework_provider,
+)
+from .native_graph import (
+    _accepted_single_service_scopes,
+    _NativeServiceGraph,
+    _validate_interceptors,
+)
+from .registration import (
+    RegistrationDecision,
+    RegistrationKind,
+    ServiceCatalog,
+    ServiceRegistration,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _ServiceRuntime:
+    catalog: ServiceCatalog
+    application_service_catalog: ApplicationServiceCatalog
+    event_catalog: LocalEventCatalog
+    container: AsyncContainer
+
+
+class _ServiceRuntimeBuilder:
+    """完成一次 Application-local scan、仲裁、容器构建和诊断快照发布。"""
+
+    __slots__ = (
+        "_background_coordinator",
+        "_background_job_catalog",
+        "_background_worker_catalog",
+        "_cache_catalog",
+        "_configuration",
+        "_contributions",
+        "_discoveries",
+        "_event_contributions",
+        "_hosted_service_catalog",
+        "_hosted_service_coordinator",
+        "_invocation_runtime",
+        "_notification_catalog",
+        "_options",
+        "_permission_catalog",
+        "_registry",
+        "_scan_packages",
+        "_setting_catalog",
+    )
+
+    def __init__(
+        self,
+        registry: ModuleRegistry,
+        contributions: ServiceContributionRegistry,
+        event_contributions: EventContributionRegistry,
+        scan_packages: Mapping[ModuleKey, tuple[str, ...]],
+        discoveries: tuple[_DiscoveredType, ...],
+        configuration: ConfigurationRoot,
+        options: OptionsSnapshot,
+        invocation_runtime: _InvocationRuntime,
+        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,
+    ) -> None:
+        self._registry = registry
+        self._contributions = contributions
+        self._event_contributions = event_contributions
+        self._scan_packages = scan_packages
+        self._discoveries = discoveries
+        self._configuration = configuration
+        self._options = options
+        self._invocation_runtime = invocation_runtime
+        self._permission_catalog = permission_catalog
+        self._cache_catalog = cache_catalog
+        self._setting_catalog = setting_catalog
+        self._notification_catalog = notification_catalog
+        self._background_worker_catalog = background_worker_catalog
+        self._background_job_catalog = background_job_catalog
+        self._background_coordinator = background_coordinator
+        self._hosted_service_catalog = hosted_service_catalog
+        self._hosted_service_coordinator = hosted_service_coordinator
+
+    def build(self) -> _ServiceRuntime:
+        event_handler_scopes = _discover_event_handlers(
+            self._registry,
+            self._discoveries,
+            self._event_contributions,
+        )
+        scanner = _ConventionScanner(
+            self._registry,
+            self._contributions,
+            self._scan_packages,
+            self._discoveries,
+            event_handler_scopes,
+        )
+        convention_candidates = scanner.discover()
+        entries = self._contributions.freeze()
+        _validate_hosted_service_entries(entries, self._hosted_service_catalog)
+        arbitration = _ServiceArbitrator(self._registry).arbitrate(entries)
+        scanner.validate_lifetimes(arbitration.drafts)
+        _validate_hosted_service_drafts(arbitration.drafts, self._hosted_service_catalog)
+        bound_application_services = _bind_application_services(
+            scanner.application_services,
+            arbitration.drafts,
+        )
+        _validate_application_service_dependencies(
+            self._registry, bound_application_services, arbitration.drafts
+        )
+        application_service_catalog = _build_application_service_catalog(
+            tuple(item.binding for item in bound_application_services),
+            self._permission_catalog,
+            self._contributions.interceptor_rules,
+        )
+        event_catalog = _build_event_catalog(
+            self._registry,
+            self._event_contributions,
+        )
+        entry_interceptors = _EntryInterceptionCatalog(
+            self._registry, event_catalog, self._contributions.interceptor_rules
+        )
+        framework_provider = _framework_provider(
+            entry_interceptors=entry_interceptors,
+            has_unit_of_work_factory=any(
+                draft.key.type_hint is _UnitOfWorkFactory for draft in arbitration.drafts
+            ),
+            registry=self._registry,
+            options=self._options,
+            invocation_runtime=self._invocation_runtime,
+            application_service_catalog=application_service_catalog,
+            event_catalog=event_catalog,
+            permission_catalog=self._permission_catalog,
+            cache_catalog=self._cache_catalog,
+            setting_catalog=self._setting_catalog,
+            notification_catalog=self._notification_catalog,
+            background_worker_catalog=self._background_worker_catalog,
+            background_job_catalog=self._background_job_catalog,
+            background_coordinator=self._background_coordinator,
+            hosted_service_catalog=self._hosted_service_catalog,
+            hosted_service_coordinator=self._hosted_service_coordinator,
+            configuration=self._configuration,
+        )
+        _provide_settings(
+            framework_provider,
+            self._setting_catalog,
+            self._configuration,
+            # Alias 的 scope 由原生图解析，不能以 draft.scope 是否已知遗漏有效 binding。
+            has_store=any(
+                draft.key == DependencyKey(RuntimeSettingStore, DEFAULT_COMPONENT)
+                and draft.decision is RegistrationDecision.ACCEPTED
+                and draft.contribution.kind is not RegistrationKind.MULTI
+                and not draft.is_collection
+                for draft in arbitration.drafts
+            ),
+        )
+        runtime_providers = _runtime_providers(arbitration, bound_application_services)
+        try:
+            # Options 的唯一 owner 是阶段绑定快照；手工 provider 也不能为未声明类型创建旁路。
+            if any(
+                draft.key.type_hint is Options or get_origin(draft.key.type_hint) is Options
+                for draft in arbitration.drafts
+            ):
+                raise ValueError(
+                    "Options bindings must come from Module configuration declarations"
+                )
+            container = make_async_container(
+                *runtime_providers,
+                framework_provider,
+                context={
+                    Options[model_type]: Options(value)  # type: ignore[valid-type]
+                    for model_type, value in self._options.values.items()
+                },
+                validation_settings=STRICT_VALIDATION,
+            )
+        except Exception as original_error:
+            error = ContainerValidationError(
+                sources=tuple(entry.contribution.source for entry in arbitration.ordered_entries),
+                original_error=original_error,
+            )
+            raise error from original_error
+
+        native_graph = _NativeServiceGraph(container)
+        _validate_event_scopes(
+            event_catalog,
+            _accepted_single_service_scopes(arbitration.drafts, native_graph),
+        )
+        _validate_interceptors(native_graph, application_service_catalog, entry_interceptors)
+        _validate_callable_entries(
+            container,
+            self._background_job_catalog,
+            self._background_worker_catalog,
+            event_catalog,
+            event_implementations={
+                item.handler_type: native_graph.implementation_for(item.handler_type)
+                for item in event_catalog.subscriptions
+                if isinstance(item.handler_type, type)
+            },
+        )
+        differences = native_graph.differences(arbitration.drafts)
+        if differences:
+            raise CatalogNativeGraphMismatchError(differences=differences)
+        return _ServiceRuntime(
+            catalog=self._freeze_catalog(
+                arbitration.drafts,
+                native_graph,
+                convention_candidates,
+            ),
+            application_service_catalog=application_service_catalog,
+            event_catalog=event_catalog,
+            container=container,
+        )
+
+    @staticmethod
+    def _freeze_catalog(
+        drafts: tuple[_RegistrationDraft, ...],
+        native_graph: _NativeServiceGraph,
+        convention_candidates: tuple[ConventionCandidate, ...],
+    ) -> ServiceCatalog:
+        registrations = tuple(
+            ServiceRegistration(
+                key=draft.key,
+                scope=native_graph.scope_for(draft),
+                owner=draft.contribution.owner,
+                source=draft.contribution.source,
+                kind=draft.contribution.kind,
+                declaration_index=draft.contribution.declaration_index,
+                decision=draft.decision,
+                decision_reason=draft.decision_reason,
+                replaced_sources=draft.replaced_sources,
+                multi_ordinal=draft.multi_ordinal,
+            )
+            for draft in sorted(drafts, key=lambda item: item.sequence)
+        )
+        return ServiceCatalog(registrations, convention_candidates)

python_platform/settings/__init__.py

@@ -0,0 +1,30 @@
+"""Global Runtime Settings 的 typed contract 与 Application-local catalog。"""
+
+from .catalog import SettingCatalog
+from .contracts import SettingDefinition
+from .definitions import SettingDefinitionContext, SettingDefinitionProvider
+from .errors import RuntimeSettingError, SettingDefinitionError
+from .handlers import SettingApplicationStatus, SettingHandler, SettingHandlerDefinition
+from .manager import SettingManager
+from .provider import SettingProvider
+from .store import RuntimeSettingStore
+from .values import SettingSnapshot, SettingValueSource, SettingWriteOutcome, StoredSetting
+
+__all__ = (
+    "RuntimeSettingError",
+    "RuntimeSettingStore",
+    "SettingApplicationStatus",
+    "SettingCatalog",
+    "SettingDefinition",
+    "SettingDefinitionContext",
+    "SettingDefinitionError",
+    "SettingDefinitionProvider",
+    "SettingHandler",
+    "SettingHandlerDefinition",
+    "SettingManager",
+    "SettingProvider",
+    "SettingSnapshot",
+    "SettingValueSource",
+    "SettingWriteOutcome",
+    "StoredSetting",
+)

python_platform/settings/application.py

@@ -0,0 +1,95 @@
+"""Settings 管理只编排正式 catalog 与 SettingManager，不拥有 provider 或值缓存。"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+from pydantic import JsonValue
+
+from ..application_services import ApplicationService, application_service
+from ..authorization import authorize
+from ..configuration.immutability import _serialization_value
+from ..errors import BusinessError, BusinessErrorDefinition, BusinessErrorField
+from ..errors.base import ResourceNotFoundError
+from .catalog import SettingCatalog
+from .contracts import SettingDefinition
+from .management import (
+    SETTINGS_READ,
+    SETTINGS_WRITE,
+    ResetSettingCommand,
+    SettingsManagementApplicationService,
+    SettingView,
+    SettingWriteResult,
+    UpdateSettingCommand,
+)
+from .manager import SettingManager
+from .values import SettingSnapshot, SettingValueSource
+
+_INVALID_VALUE = BusinessErrorDefinition("settings.invalid_value", "Invalid setting value")
+_VALUE_FIELD = BusinessErrorField(UpdateSettingCommand, "value")
+
+
+@application_service(provides=SettingsManagementApplicationService)
+class _SettingsManagementApplicationService(ApplicationService):
+    def __init__(self, catalog: SettingCatalog, settings: SettingManager) -> None:
+        self._catalog = catalog
+        self._settings = settings
+
+    @authorize(SETTINGS_READ)
+    async def get_list(self) -> tuple[SettingView, ...]:
+        return tuple(
+            [
+                _view(definition, await self.setting_provider.snapshot(definition))
+                for definition in self._catalog.definitions
+            ]
+        )
+
+    @authorize(SETTINGS_READ)
+    async def get(self, name: str) -> SettingView:
+        definition = self._definition(name)
+        return _view(definition, await self.setting_provider.snapshot(definition))
+
+    @authorize(SETTINGS_WRITE)
+    async def update(self, name: str, command: UpdateSettingCommand) -> SettingWriteResult:
+        definition = self._definition(name)
+        try:
+            # JSON 数组/日期须由 Pydantic 的 JSON 模式解释，不能误用 strict Python 输入语义。
+            value = definition._validate_json(json.dumps(command.value, allow_nan=False))
+        except (TypeError, ValueError):
+            raise BusinessError(_INVALID_VALUE, fields=(_VALUE_FIELD,)) from None
+        saved = await self._settings.update(
+            definition, value, expected_version=command.expected_version
+        )
+        return SettingWriteResult(
+            setting=_view(definition, saved.snapshot), notification=saved.notification
+        )
+
+    @authorize(SETTINGS_WRITE)
+    async def reset(self, name: str, command: ResetSettingCommand) -> SettingWriteResult:
+        definition = self._definition(name)
+        saved = await self._settings.reset(definition, expected_version=command.expected_version)
+        return SettingWriteResult(
+            setting=_view(definition, saved.snapshot), notification=saved.notification
+        )
+
+    def _definition(self, name: str) -> SettingDefinition[Any]:
+        definition = self._catalog.get(name)
+        if definition is None:
+            raise ResourceNotFoundError("Setting not found")
+        return definition
+
+
+def _view(definition: SettingDefinition[Any], snapshot: SettingSnapshot[Any]) -> SettingView:
+    # HTTP DTO 是独立 JSON 副本；不会把内部不可变快照的容器直接交给调用方。
+    value = (
+        None
+        if snapshot.source is SettingValueSource.UNSET
+        else cast(
+            JsonValue,
+            definition._adapter.dump_python(_serialization_value(snapshot.value), mode="json"),
+        )
+    )
+    return SettingView(
+        name=snapshot.name, value=value, source=snapshot.source, version=snapshot.version
+    )

python_platform/settings/binding.py

@@ -0,0 +1,33 @@
+"""按最终存储 binding 组装原生 Dishka 服务；不以 provider Module 名单推断能力。"""
+
+from __future__ import annotations
+
+from dishka import Provider, Scope
+
+from ..configuration import ConfigurationRoot
+from .catalog import SettingCatalog
+from .manager import SettingManager
+from .provider import SettingProvider
+from .store import RuntimeSettingStore
+
+
+def _provide_settings(
+    provider: Provider,
+    catalog: SettingCatalog,
+    configuration: ConfigurationRoot,
+    *,
+    has_store: bool,
+) -> None:
+    if has_store:
+
+        def reader(store: RuntimeSettingStore) -> SettingProvider:
+            return SettingProvider(catalog, configuration, store)
+
+        provider.provide(reader, scope=Scope.APP)
+        provider.provide(SettingManager, scope=Scope.APP)
+    else:
+        provider.provide(
+            lambda: SettingProvider(catalog, configuration),
+            provides=SettingProvider,
+            scope=Scope.APP,
+        )

python_platform/settings/catalog.py

@@ -0,0 +1,121 @@
+"""Module setting metadata 的 Application-local immutable catalog。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any
+
+from ..diagnostics import SourceLocation
+from ..modularity import ModuleRegistry
+from ..modularity.discovery import _DiscoveredType
+from .contracts import SettingDefinition
+from .definition_discovery import _collect_setting_definitions
+from .errors import SettingDefinitionError
+from .handlers import SettingHandlerDefinition
+
+if TYPE_CHECKING:
+    from ..services.contribution import ServiceContributionRegistry
+
+
+class SettingCatalog:
+    __slots__ = ("_definitions", "_handlers", "_sources")
+
+    def __init__(
+        self,
+        definitions: tuple[SettingDefinition[Any], ...],
+        handlers: tuple[SettingHandlerDefinition[Any], ...] = (),
+        *,
+        sources: Mapping[str, SourceLocation] | None = None,
+    ) -> None:
+        indexed: dict[str, SettingDefinition[Any]] = {}
+        for definition in definitions:
+            if not isinstance(definition, SettingDefinition):
+                raise SettingDefinitionError(
+                    setting=repr(definition),
+                    reason="catalog entries must be SettingDefinition values",
+                )
+            if definition.name in indexed:
+                raise SettingDefinitionError(
+                    setting=definition.name,
+                    reason="setting is declared more than once",
+                )
+            indexed[definition.name] = definition
+        self._definitions: Mapping[str, SettingDefinition[Any]] = MappingProxyType(
+            dict(sorted(indexed.items()))
+        )
+        seen: set[tuple[str, type[object]]] = set()
+        for handler in handlers:
+            if not isinstance(handler, SettingHandlerDefinition):
+                raise SettingDefinitionError(setting="handler", reason="invalid handler definition")
+            self.require_owned(handler.setting)
+            key = (handler.setting.name, handler.handler_type)
+            if key in seen:
+                raise SettingDefinitionError(setting=key[0], reason="handler is declared twice")
+            seen.add(key)
+        self._handlers = handlers
+        self._sources = MappingProxyType(dict(sources or {}))
+
+    @property
+    def sources(self) -> Mapping[str, SourceLocation]:
+        return self._sources
+
+    @property
+    def handlers(self) -> tuple[SettingHandlerDefinition[Any], ...]:
+        return self._handlers
+
+    @property
+    def definitions(self) -> tuple[SettingDefinition[Any], ...]:
+        return tuple(self._definitions.values())
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._definitions)
+
+    def get(self, name: str) -> SettingDefinition[Any] | None:
+        return self._definitions.get(name)
+
+    def require_owned(self, definition: SettingDefinition[Any]) -> None:
+        if self._definitions.get(definition.name) is not definition:
+            raise SettingDefinitionError(
+                setting=definition.name,
+                reason="definition is not owned by this Application",
+            )
+
+
+def _build_setting_catalog(
+    registry: ModuleRegistry, discoveries: tuple[_DiscoveredType, ...]
+) -> SettingCatalog:
+    definitions, sources = _collect_setting_definitions(discoveries)
+    handlers: list[SettingHandlerDefinition[Any]] = []
+    for descriptor in registry.dependency_order:
+        declared_handlers = descriptor.module_type.setting_handler_definitions
+        if not isinstance(declared_handlers, tuple):
+            raise SettingDefinitionError(
+                setting=str(descriptor.key), reason="setting_handler_definitions must be a tuple"
+            )
+        handlers.extend(declared_handlers)
+    return SettingCatalog(definitions, tuple(handlers), sources=sources)
+
+
+def _contribute_setting_handler_defaults(
+    registry: ModuleRegistry,
+    contributions: ServiceContributionRegistry,
+) -> None:
+    from dishka import Provider, Scope
+
+    # 声明只拥有 handler 与 setting 的关系；实例和依赖仍交给原生 Dishka APP binding。
+    registered: set[type[object]] = set()
+    for descriptor in registry.dependency_order:
+        for definition in descriptor.module_type.setting_handler_definitions:
+            handler_type = definition.handler_type
+            if handler_type in registered:
+                continue
+            registered.add(handler_type)
+            provider = Provider()
+            provider.provide(handler_type, scope=Scope.APP)
+            contributions._add_framework_default(
+                provider=provider,
+                owner=descriptor.key,
+                source=descriptor.declaration_source,
+                reason=f"Settings handler default for {definition.setting.name}",
+            )

python_platform/settings/changes.py

@@ -0,0 +1,14 @@
+"""Settings 变更只通知标识，数据库仍是有效值的唯一权威。"""
+
+from pydantic import BaseModel, ConfigDict
+
+from ..notifications import NotificationDefinition
+
+
+class SettingChanged(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+
+
+SETTINGS_CHANGED = NotificationDefinition("settings.changed", SettingChanged)