python-platform 0.1.1__py3-none-any.whl

python_platform/application/builder.py

@@ -0,0 +1,260 @@
+"""Startup Module 到 isolated Application object graph 的 composition root。"""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Mapping
+from pathlib import Path
+from uuid import uuid4
+
+from pydantic import BaseModel
+
+from ..application_services.invocation import _InvocationRuntime
+from ..authorization.catalog import _build_permission_catalog
+from ..background_jobs.catalog import _build_background_job_catalog
+from ..background_workers import BackgroundExecutionOptions
+from ..background_workers.catalog import _build_background_worker_catalog
+from ..background_workers.runtime import _BackgroundCoordinator
+from ..caching.catalog import _build_cache_catalog
+from ..configuration.composition import _ConfigurationComposer
+from ..configuration.contracts import _ConfigurationDefaultContribution
+from ..diagnostics.journal import _DiagnosticJournal
+from ..events.contribution import EventContributionRegistry
+from ..hosted_services import HostedServiceOptions
+from ..hosted_services.catalog import (
+    _build_hosted_service_catalog,
+    _contribute_hosted_service_defaults,
+)
+from ..hosted_services.runtime import _HostedServiceCoordinator
+from ..modularity import AppModule, ModuleDescriptor, ModuleRef
+from ..modularity.discovery import _discover_types, _snapshot_scan_packages
+from ..modularity.graph import _ModuleGraphBuilder
+from ..notifications.catalog import _build_notification_catalog
+from ..options.registry import _OptionsRegistry
+from ..services.contribution import ServiceContributionRegistry
+from ..services.runtime import _ServiceRuntimeBuilder
+from ..settings.catalog import _build_setting_catalog, _contribute_setting_handler_defaults
+from .build_spec import _ApplicationBuildSpec
+from .composition import _CompositionLifecycle
+from .runtime import Application
+from .state import _ApplicationStateRoot
+
+
+class ApplicationBuilder:
+    """以 startup Module 为唯一入口建立完整、隔离的 Application object graph。"""
+
+    __slots__ = (
+        "_base_path",
+        "_cli_args",
+        "_dotenv_path",
+        "_env_prefix",
+        "_environment",
+        "_explicit_overrides",
+        "_startup_module",
+    )
+
+    def __init__(
+        self,
+        startup_module: type[AppModule] | ModuleRef,
+        *,
+        environment: str,
+        base_path: Path,
+        env_prefix: str,
+        cli_args: tuple[str, ...] | list[str] | None = None,
+        dotenv_path: Path | None = None,
+        explicit_overrides: Mapping[str, object] | None = None,
+    ) -> None:
+        if cli_args is not None and (
+            not isinstance(cli_args, (tuple, list))
+            or any(not isinstance(arg, str) for arg in cli_args)
+        ):
+            raise TypeError("cli_args must be a sequence of strings")
+        self._cli_args = tuple(cli_args or ())
+        self._startup_module = startup_module
+        self._environment = _validate_environment(environment)
+        self._base_path = _validate_base_path(base_path)
+        self._env_prefix = _validate_env_prefix(env_prefix)
+        self._dotenv_path = _resolve_dotenv_path(
+            dotenv_path,
+            base_path=self._base_path,
+        )
+        self._explicit_overrides = _copy_explicit_overrides(explicit_overrides)
+
+    def build(self) -> Application:
+        registry = _ModuleGraphBuilder(self._startup_module).build()
+        scan_packages = _snapshot_scan_packages(registry)
+        discoveries = _discover_types(registry, scan_packages)
+        claims: dict[type[BaseModel], tuple[str, ModuleDescriptor]] = {}
+        pre_options_registry = _OptionsRegistry(kind="PreOptions", claims=claims)
+        options_registry = _OptionsRegistry(kind="Options", claims=claims)
+        permission_catalog = _build_permission_catalog(registry, discoveries)
+        cache_catalog = _build_cache_catalog(registry)
+        setting_catalog = _build_setting_catalog(registry, discoveries)
+        notification_catalog = _build_notification_catalog(registry)
+        background_worker_catalog = _build_background_worker_catalog(registry)
+        background_job_catalog = _build_background_job_catalog(registry)
+        hosted_service_catalog = _build_hosted_service_catalog(registry)
+        configuration = _ConfigurationComposer(
+            environment=self._environment,
+            base_path=self._base_path,
+            env_prefix=self._env_prefix,
+            dotenv_path=self._dotenv_path,
+            explicit_overrides=self._explicit_overrides,
+            cli_args=self._cli_args,
+        ).build(
+            tuple(
+                _ConfigurationDefaultContribution(
+                    source_location=descriptor.declaration_source,
+                    values=descriptor.module_type.configuration_defaults,
+                )
+                for descriptor in registry.dependency_order
+            )
+        )
+        root = _ApplicationStateRoot(
+            application_id=uuid4(),
+            registry=registry,
+            configuration=configuration,
+            pre_options_registry=pre_options_registry,
+            options_registry=options_registry,
+            service_registry=ServiceContributionRegistry(),
+            event_registry=EventContributionRegistry(),
+            permission_catalog=permission_catalog,
+            cache_catalog=cache_catalog,
+            setting_catalog=setting_catalog,
+            background_worker_catalog=background_worker_catalog,
+            background_job_catalog=background_job_catalog,
+            hosted_service_catalog=hosted_service_catalog,
+            journal=_DiagnosticJournal(),
+            completed_stages={descriptor.key: [] for descriptor in registry.dependency_order},
+        )
+        _CompositionLifecycle(root).run()
+        _contribute_hosted_service_defaults(hosted_service_catalog, root.service_registry)
+        _contribute_setting_handler_defaults(registry, root.service_registry)
+        root.invocation_runtime = _InvocationRuntime(
+            application_id=root.application_id,
+            state_getter=lambda: root.state,
+        )
+        root.background_coordinator = _BackgroundCoordinator(
+            worker_catalog=background_worker_catalog,
+            job_catalog=background_job_catalog,
+            options=root.require_options().get(BackgroundExecutionOptions),
+            invocation_runtime=root.require_invocation_runtime(),
+            build_spec=_ApplicationBuildSpec(
+                self._startup_module,
+                self._environment,
+                self._base_path,
+                self._env_prefix,
+                self._cli_args,
+                self._dotenv_path,
+                dict(self._explicit_overrides),
+                Path.cwd().resolve(),
+            ),
+        )
+        root.hosted_service_coordinator = _HostedServiceCoordinator(
+            catalog=hosted_service_catalog,
+            options=root.require_options().get(HostedServiceOptions),
+            state_getter=lambda: root.state,
+        )
+        service_runtime = _ServiceRuntimeBuilder(
+            registry,
+            root.service_registry,
+            root.event_registry,
+            scan_packages,
+            discoveries,
+            root.configuration,
+            root.require_options(),
+            root.require_invocation_runtime(),
+            permission_catalog,
+            cache_catalog,
+            setting_catalog,
+            notification_catalog,
+            background_worker_catalog,
+            background_job_catalog,
+            root.require_background_coordinator(),
+            hosted_service_catalog,
+            root.require_hosted_service_coordinator(),
+        ).build()
+        root.service_catalog = service_runtime.catalog
+        root.application_service_catalog = service_runtime.application_service_catalog
+        root.event_catalog = service_runtime.event_catalog
+        root.container = service_runtime.container
+        root.require_background_coordinator().attach_container(service_runtime.container)
+        root.require_hosted_service_coordinator().attach_container(
+            service_runtime.container,
+            service_runtime.application_service_catalog,
+        )
+        return Application(root)
+
+
+def _validate_environment(environment: str) -> str:
+    if not isinstance(environment, str) or not environment:
+        raise TypeError("environment must be a non-empty string")
+    if environment != environment.strip() or any(
+        not (character.isalnum() or character in "_-") for character in environment
+    ):
+        raise ValueError("environment must contain only letters, digits, '_' or '-'")
+    return environment
+
+
+def _validate_base_path(base_path: Path) -> Path:
+    if not isinstance(base_path, Path):
+        raise TypeError("base_path must be pathlib.Path")
+    resolved = base_path.resolve()
+    if not resolved.is_dir():
+        raise ValueError("base_path must be an existing directory")
+    return resolved
+
+
+def _validate_env_prefix(env_prefix: str) -> str:
+    if not isinstance(env_prefix, str) or not env_prefix:
+        raise TypeError("env_prefix must be a non-empty string")
+    if not (env_prefix[0].isalpha() or env_prefix[0] == "_") or any(
+        not (character.isalnum() or character == "_") for character in env_prefix
+    ):
+        raise ValueError("env_prefix must be a valid environment-variable prefix")
+    return env_prefix
+
+
+def _resolve_dotenv_path(
+    dotenv_path: Path | None,
+    *,
+    base_path: Path,
+) -> Path | None:
+    if dotenv_path is None:
+        return None
+    if not isinstance(dotenv_path, Path):
+        raise TypeError("dotenv_path must be pathlib.Path or None")
+    candidate = dotenv_path if dotenv_path.is_absolute() else base_path / dotenv_path
+    return candidate.resolve()
+
+
+def _copy_explicit_overrides(
+    explicit_overrides: Mapping[str, object] | None,
+) -> dict[str, object]:
+    if explicit_overrides is None:
+        return {}
+    if not isinstance(explicit_overrides, Mapping):
+        raise TypeError("explicit_overrides must be a mapping")
+    try:
+        return {key: _copy_explicit_value(value) for key, value in explicit_overrides.items()}
+    except Exception as original_error:
+        raise TypeError("explicit_overrides must be defensively copyable") from original_error
+
+
+def _copy_explicit_value(value: object) -> object:
+    # deepcopy 不支持 MappingProxyType；容器先按配置语义复制，再交给 source boundary 校验。
+    if isinstance(value, Mapping):
+        copied: object = {key: _copy_explicit_value(item) for key, item in value.items()}
+    elif isinstance(value, list):
+        copied = [_copy_explicit_value(item) for item in value]
+    elif isinstance(value, tuple):
+        copied = tuple(_copy_explicit_value(item) for item in value)
+    elif isinstance(value, set):
+        copied = {_copy_explicit_value(item) for item in value}
+    elif isinstance(value, frozenset):
+        copied = frozenset(_copy_explicit_value(item) for item in value)
+    elif isinstance(value, bytearray):
+        copied = bytearray(value)
+    else:
+        copied = copy.deepcopy(value)
+    return copied

python_platform/application/composition.py

@@ -0,0 +1,219 @@
+"""Synchronous Module composition stages 与 PreOptions/Options barriers。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import cast
+
+from ..auditing import AuditingOptions
+from ..background_workers import BackgroundExecutionOptions
+from ..diagnostics import EventStatus, LifecyclePhase, LifecycleStage
+from ..errors import (
+    CompositionResourceError,
+    LifecycleInvocationError,
+)
+from ..hosted_services import HostedServiceOptions
+from ..hosted_services.options import HOSTED_SERVICE_OPTIONS_SECTION
+from ..lifecycle import ConfigureContext, PostConfigureContext, PreConfigureContext
+from ..modularity import ModuleDescriptor
+from ..unit_of_work import UnitOfWorkOptions
+from .state import (
+    LIFECYCLE_ERROR_TYPE,
+    _ApplicationStateRoot,
+    _lifecycle_failure_message,
+)
+
+
+class _CompositionLifecycle:
+    """拥有一次全局 stage barrier 编排，不保存任何跨 Application 状态。"""
+
+    __slots__ = ("_root",)
+
+    def __init__(self, root: _ApplicationStateRoot) -> None:
+        self._root = root
+
+    def run(self) -> None:
+        # typed 调用是 lifecycle contract；不通过 getattr/string table 建第二份阶段权威。
+        for descriptor in self._root.registry.dependency_order:
+            self._invoke_pre_configure(descriptor)
+        self._root.pre_options = self._root.pre_options_registry.bind_pre_options(
+            self._root.configuration
+        )
+        for descriptor in self._root.registry.dependency_order:
+            self._invoke_configure(descriptor)
+        for descriptor in self._root.registry.dependency_order:
+            self._invoke_post_configure(descriptor)
+        options = self._root.options_registry
+        owner = self._root.registry.startup
+        # 常驻框架能力的默认声明只有此处负责；显式 Module 声明优先，默认值仍由 model 验证。
+        options.declare_default(BackgroundExecutionOptions, "background_execution", owner=owner)
+        options.declare_default(HostedServiceOptions, HOSTED_SERVICE_OPTIONS_SECTION, owner=owner)
+        options.declare_default(AuditingOptions, "auditing", owner=owner)
+        options.declare_default(UnitOfWorkOptions, "unit_of_work", owner=owner)
+        self._root.options = options.bind_options(self._root.configuration)
+        self._root.configuration = self._root.configuration._finalize(
+            sections=(
+                options.sections
+                | self._root.pre_options_registry.sections
+                | ({"settings"} if self._root.setting_catalog.definitions else set())
+            ),
+            secret_paths=options.secret_paths | self._root.pre_options_registry.secret_paths,
+            mapping_paths=lambda values, reference: (
+                options.mapping_paths(values, reference, self._root.options)
+                | self._root.pre_options_registry.mapping_paths(
+                    values, reference, self._root.pre_options
+                )
+            ),
+        )
+
+    def _invoke_pre_configure(self, descriptor: ModuleDescriptor) -> None:
+        stage = LifecycleStage.PRE_CONFIGURE
+        editor = self._root.pre_options_registry.contributor(
+            owner=descriptor,
+            stage=stage,
+        )
+        context = PreConfigureContext(
+            application_id=self._root.application_id,
+            descriptor=descriptor,
+            stage=stage,
+            application=self._root.view(None),
+            _emit=self._root.diagnostic_emitter(descriptor, stage),
+            configuration=self._root.configuration,
+            pre_configure=editor,
+        )
+        callback = cast(
+            Callable[[PreConfigureContext], object],
+            descriptor.instance.pre_configure,
+        )
+        try:
+            self._invoke(descriptor, stage, lambda: callback(context))
+        finally:
+            editor._close()
+
+    def _invoke_configure(self, descriptor: ModuleDescriptor) -> None:
+        stage = LifecycleStage.CONFIGURE
+        editor = self._root.options_registry.contributor(
+            owner=descriptor,
+            stage=stage,
+        )
+        services = self._root.service_registry.contributor(
+            descriptor=descriptor,
+            stage=stage,
+        )
+        events = self._root.event_registry.contributor(
+            descriptor=descriptor,
+            stage=stage,
+        )
+        context = ConfigureContext(
+            application_id=self._root.application_id,
+            descriptor=descriptor,
+            stage=stage,
+            application=self._root.view(None),
+            _emit=self._root.diagnostic_emitter(descriptor, stage),
+            configuration=self._root.configuration,
+            pre_options=self._root.require_pre_options(),
+            configure=editor,
+            services=services,
+            events=events,
+        )
+        callback = cast(
+            Callable[[ConfigureContext], object],
+            descriptor.instance.configure,
+        )
+        try:
+            self._invoke(descriptor, stage, lambda: callback(context))
+        finally:
+            editor._close()
+            services._close()
+            events._close()
+
+    def _invoke_post_configure(self, descriptor: ModuleDescriptor) -> None:
+        stage = LifecycleStage.POST_CONFIGURE
+        editor = self._root.options_registry.contributor(
+            owner=descriptor,
+            stage=stage,
+        )
+        services = self._root.service_registry.contributor(
+            descriptor=descriptor,
+            stage=stage,
+        )
+        context = PostConfigureContext(
+            application_id=self._root.application_id,
+            descriptor=descriptor,
+            stage=stage,
+            application=self._root.view(None),
+            _emit=self._root.diagnostic_emitter(descriptor, stage),
+            configuration=self._root.configuration,
+            pre_options=self._root.require_pre_options(),
+            configure=editor,
+            services=services,
+        )
+        callback = cast(
+            Callable[[PostConfigureContext], object],
+            descriptor.instance.post_configure,
+        )
+        try:
+            self._invoke(descriptor, stage, lambda: callback(context))
+        finally:
+            editor._close()
+            services._close()
+
+    def _invoke(
+        self,
+        descriptor: ModuleDescriptor,
+        stage: LifecycleStage,
+        callback: Callable[[], object],
+    ) -> None:
+        subject = str(descriptor.key)
+        active_event = self._root.journal.start_event(
+            phase=LifecyclePhase.COMPOSITION,
+            stage=stage,
+            subject=subject,
+            source=descriptor.declaration_source,
+        )
+        try:
+            result = callback()
+            is_awaitable = inspect.isawaitable(result)
+            if inspect.iscoroutine(result):
+                result.close()
+            if result is not None:
+                raise CompositionResourceError(
+                    module=descriptor.key,
+                    stage=stage,
+                    resource_kind=("awaitable" if is_awaitable else "non-None value"),
+                )
+        except Exception as original_error:
+            failure_id = self._root.journal.begin_failure(
+                error_type=LIFECYCLE_ERROR_TYPE,
+                phase=LifecyclePhase.COMPOSITION,
+                stage=stage,
+                subject=subject,
+                message=_lifecycle_failure_message(subject, stage, original_error),
+                source=descriptor.declaration_source,
+                dependency_path=tuple(str(key) for key in descriptor.dependency_path),
+            )
+            duration_ns = self._root.journal.finish_event(
+                active_event,
+                status=EventStatus.FAILED,
+                failure_id=failure_id,
+            )
+            self._root.journal.complete_failure(failure_id)
+            error = LifecycleInvocationError(
+                failure_id=failure_id,
+                module=descriptor.key,
+                phase=LifecyclePhase.COMPOSITION,
+                stage=stage,
+                dependency_path=descriptor.dependency_path,
+                duration_ns=duration_ns,
+                source=descriptor.declaration_source,
+                original_error=original_error,
+            )
+            raise error from original_error
+
+        self._root.journal.finish_event(
+            active_event,
+            status=EventStatus.SUCCEEDED,
+            failure_id=None,
+        )
+        self._root.completed_stages[descriptor.key].append(stage)