python-platform 0.1.1__py3-none-any.whl

python_platform/invocation/callables.py

@@ -0,0 +1,171 @@
+"""调用签名的 DI 分类与原生注入包装；作用域创建仍归各运行入口。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType, SimpleNamespace
+from typing import Annotated, Any, TypeVar, get_args, get_origin, get_type_hints
+
+from dishka import AsyncContainer, BaseScope, DependencyKey
+from dishka.integrations.base import default_parse_dependency, wrap_injection
+
+_R = TypeVar("_R")
+
+
+def _resolved_parameter_hints(
+    function: Callable[..., object],
+    annotations: Mapping[str, object],
+) -> dict[str, Any]:
+    # 入口只解释自己拥有的参数；业务 payload 的局部引用不属于 DI 参数契约。
+    try:
+        return get_type_hints(
+            SimpleNamespace(__annotations__=dict(annotations)),
+            globalns=function.__globals__,
+            include_extras=True,
+        )
+    except (NameError, TypeError) as error:
+        raise TypeError(f"{function.__qualname__}: cannot resolve callable annotations") from error
+
+
+def _dependency_key(
+    parameter: inspect.Parameter,
+    hint: object,
+    container: AsyncContainer,
+    scope: BaseScope,
+) -> DependencyKey | None:
+    explicit = default_parse_dependency(parameter, hint)
+    hint_type = get_args(hint)[0] if get_origin(hint) is Annotated else hint
+    key = explicit or DependencyKey(hint_type, "")
+    root = container
+    while root.parent_container is not None:
+        root = root.parent_container
+    registry = root.registry
+    while True:
+        factory = registry.get_factory(key)
+        if factory is not None:
+            if registry.scope > scope:
+                raise TypeError(
+                    f"{parameter.name}: dependency {key} is unavailable in {scope.name}"
+                )
+            return key
+        if registry.child_registry is None:
+            break
+        registry = registry.child_registry
+    if explicit is not None:
+        raise TypeError(f"{parameter.name}: explicitly requested dependency {key} is unregistered")
+    return None
+
+
+@dataclass(frozen=True, slots=True)
+class _CallablePlan:
+    """冻结一次签名解释；只存契约事实，不缓存容器或解析出的服务实例。"""
+
+    signature: inspect.Signature
+    dependencies: Mapping[str, DependencyKey]
+
+    @classmethod
+    def compile(
+        cls,
+        function: Callable[..., object],
+        container: AsyncContainer,
+        scope: BaseScope,
+        *,
+        business_parameters: int = 0,
+    ) -> _CallablePlan:
+        if not inspect.iscoroutinefunction(function):
+            raise TypeError("Application callable must be an async function or bound async method")
+        signature = inspect.signature(function)
+        annotations = {
+            name: parameter.annotation
+            for index, (name, parameter) in enumerate(signature.parameters.items())
+            if index >= business_parameters and parameter.annotation is not inspect.Parameter.empty
+        }
+        hints = _resolved_parameter_hints(function, annotations)
+        dependencies: dict[str, DependencyKey] = {}
+        business: list[inspect.Parameter] = []
+        for index, parameter in enumerate(signature.parameters.values()):
+            if parameter.kind in (parameter.VAR_POSITIONAL, parameter.VAR_KEYWORD):
+                raise TypeError(
+                    f"{function.__qualname__}.{parameter.name}: "
+                    "variadic entry parameters are unsupported"
+                )
+            key = (
+                None
+                if index < business_parameters
+                else _dependency_key(
+                    parameter,
+                    hints.get(parameter.name, parameter.annotation),
+                    container,
+                    scope,
+                )
+            )
+            if key is None:
+                business.append(parameter)
+            elif parameter.kind is parameter.POSITIONAL_ONLY:
+                raise TypeError(
+                    f"{function.__qualname__}.{parameter.name}: "
+                    "DI parameter cannot be positional-only"
+                )
+            else:
+                dependencies[parameter.name] = key
+        return cls(signature.replace(parameters=business), MappingProxyType(dependencies))
+
+    async def invoke(
+        self,
+        function: Callable[..., Awaitable[_R]],
+        container: AsyncContainer,
+        args: tuple[object, ...],
+        kwargs: dict[str, object],
+    ) -> _R:
+        if self.dependencies.keys() & kwargs.keys():
+            raise TypeError("caller cannot override automatically injected parameters")
+        # 先验证全部业务实参，再解析任何依赖，避免错误调用触发 resource factory。
+        bound = self.signature.bind(*args, **kwargs)
+        bound.apply_defaults()
+
+        def parse(parameter: inspect.Parameter, hint: Any) -> DependencyKey | None:
+            return self.dependencies.get(parameter.name)
+
+        async def target(*args: object, **kwargs: object) -> _R:
+            return await function(*args, **kwargs)
+
+        # 原函数可能被多个 Application 共享；只给当前调用的 native wrapper 提供签名。
+        target.__signature__ = inspect.signature(function)  # type: ignore[attr-defined]
+        target.__annotations__ = {}
+        injected = wrap_injection(
+            func=target,
+            container_getter=lambda args, kwargs: container,
+            is_async=True,
+            parse_dependency=parse,
+        )
+        # DI 参数从签名移除后位置会变化；普通业务参数按名称交给原函数。
+        positional = tuple(
+            bound.arguments[name]
+            for name, parameter in self.signature.parameters.items()
+            if parameter.kind is parameter.POSITIONAL_ONLY
+        )
+        named = {
+            name: value
+            for name, value in bound.arguments.items()
+            if self.signature.parameters[name].kind is not inspect.Parameter.POSITIONAL_ONLY
+        }
+        return await injected(*positional, **named)
+
+
+async def _call_in_scope(
+    function: Callable[..., Awaitable[_R]],
+    container: AsyncContainer,
+    *args: object,
+    **kwargs: object,
+) -> _R:
+    # handler 的既有 payload/context 是入口契约，即使其类型也可解析也不能被 DI 替换。
+    from ..application_services.invocation import _InvocationRuntime
+
+    plan = _CallablePlan.compile(
+        function, container, container.scope, business_parameters=len(args)
+    )
+    runtime = await container.get(_InvocationRuntime)
+    with runtime.call_scope(container):
+        return await plan.invoke(function, container, args, kwargs)

python_platform/invocation/contracts.py

@@ -0,0 +1,33 @@
+"""跨 Application Service、Event 与 persistence 共享的只读 invocation facts。"""
+
+from dataclasses import dataclass
+from typing import TypeGuard
+from uuid import UUID
+
+_CORRELATION_ID_MAX_LENGTH = 128
+
+
+def _is_safe_correlation_id(value: object) -> TypeGuard[str]:
+    """所有入口共用同一 correlation 标识安全契约。"""
+
+    return (
+        isinstance(value, str)
+        and bool(value)
+        and value == value.strip()
+        and len(value) <= _CORRELATION_ID_MAX_LENGTH
+        and value.isascii()
+        and value.isprintable()
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationInvocationContext:
+    application_id: UUID
+    invocation_id: UUID
+    parent_invocation_id: UUID | None
+    connection_name: str
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundSystemCaller:
+    """只以 type 表达 framework system identity，不携带用户授权事实。"""

python_platform/invocation/entries.py

@@ -0,0 +1,54 @@
+"""已登记运行入口的构建期签名验证，读取最终原生图而不实例化处理器。"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from typing import cast
+
+from dishka import AsyncContainer, BaseScope, Scope
+
+from ..background_jobs import BackgroundJobCatalog
+from ..background_workers import BackgroundWorkerCatalog
+from ..events import LocalEventCatalog, LocalEventPhase
+from .callables import _CallablePlan
+
+
+def _validate_callable_entries(
+    container: AsyncContainer,
+    jobs: BackgroundJobCatalog,
+    workers: BackgroundWorkerCatalog,
+    events: LocalEventCatalog,
+    *,
+    event_implementations: Mapping[type[object], type[object]],
+) -> None:
+    for job in jobs.definitions:
+        _validate_entry(container, job.handler_type, "execute", 2, Scope.ACTION)
+    for worker in workers.definitions:
+        _validate_entry(container, worker.worker_type, "run_iteration", 1, Scope.ACTION)
+    for subscription in events.subscriptions:
+        scope = Scope.ACTION if subscription.phase is LocalEventPhase.DOMAIN else Scope.REQUEST
+        target = subscription.handler_type
+        if isinstance(target, type):
+            target = event_implementations[target]
+        _validate_entry(container, target, "handle", 1, scope)
+
+
+def _validate_entry(
+    container: AsyncContainer,
+    target: type[object] | Callable[..., Awaitable[None]],
+    method_name: str,
+    business_parameters: int,
+    scope: BaseScope,
+) -> None:
+    if isinstance(target, type):
+        function = cast(Callable[..., Awaitable[None]], getattr(target, method_name))
+        business_parameters += 1  # 未绑定方法的 self 也是调用入口负责的参数。
+    else:
+        function = target
+    plan = _CallablePlan.compile(
+        function, container, scope, business_parameters=business_parameters
+    )
+    try:
+        plan.signature.bind(*(object() for _ in range(business_parameters)))
+    except TypeError as error:
+        raise TypeError(f"{function.__qualname__}: unresolved entry parameters: {error}") from error

python_platform/invocation/function_runtime.py

@@ -0,0 +1,48 @@
+"""Application 与 HostedService 共用的函数入口作用域和调用许可。"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, TypeVar
+
+from dishka import AsyncContainer, Scope
+
+from ..application_services.errors import ApplicationInvocationRejectedError
+from ..authorization import CurrentUser
+from .callables import _CallablePlan
+
+if TYPE_CHECKING:
+    from ..application_services.invocation import _InvocationRuntime
+
+_R = TypeVar("_R")
+
+
+async def _invoke_callable(
+    container: AsyncContainer,
+    runtime: _InvocationRuntime,
+    current_user: CurrentUser,
+    correlation_id: str,
+    function: Callable[..., Awaitable[_R]],
+    args: tuple[object, ...],
+    kwargs: dict[str, object],
+) -> _R:
+    async with runtime.outer_lease():
+        ambient = runtime.current()
+        existing = ambient.action_container if ambient is not None else runtime.current_call_scope()
+        if existing is not None:
+            # REQUEST 已缓存的 CurrentUser 必须与授权/审计读取的身份一致。
+            # 同一调用作用域内不得通过 call_as 改变身份或污染外层缓存。
+            if current_user != runtime.current_user():
+                raise ApplicationInvocationRejectedError(
+                    reason="cannot switch caller identity inside an existing invocation scope",
+                )
+            plan = _CallablePlan.compile(function, existing, existing.scope)
+            return await plan.invoke(function, existing, args, kwargs)
+        token = runtime.bind_caller(current_user, correlation_id)
+        try:
+            plan = _CallablePlan.compile(function, container, Scope.REQUEST)
+            async with container(scope=Scope.REQUEST) as request:
+                with runtime.call_scope(request):
+                    return await plan.invoke(function, request, args, kwargs)
+        finally:
+            runtime.reset_caller(token)

python_platform/invocation/interception.py

@@ -0,0 +1,184 @@
+"""正式 Job/Worker/Handler 的扩展链；编译规则复用服务入口的同一权威。"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, replace
+from types import MappingProxyType
+from typing import cast
+
+from dishka import AsyncContainer, Scope
+
+from ..application_services.catalog import (
+    ApplicationServiceMethod,
+    _match_interceptors,
+    _method_source,
+)
+from ..application_services.execution import _InterceptorPipeline
+from ..application_services.interceptors import (
+    InterceptionStage,
+    InterceptorRegistration,
+    _InterceptorRule,
+)
+from ..application_services.invocation import _InvocationRuntime
+from ..events.catalog import LocalEventCatalog
+from ..events.contracts import LocalEventPhase
+from ..modularity import ModuleKey, ModuleRegistry
+from ..unit_of_work.options import _UNIT_OF_WORK_ATTRIBUTE, UnitOfWorkDeclaration, _declaration
+from .callables import _call_in_scope
+
+
+@dataclass(frozen=True, slots=True)
+class _CompiledEntry:
+    descriptor: ApplicationServiceMethod
+    steps: Mapping[InterceptionStage, tuple[InterceptorRegistration, ...]]
+    outer_scope: Scope
+    method_scope: Scope
+
+
+class _EntryInterceptionCatalog:
+    def __init__(
+        self,
+        registry: ModuleRegistry,
+        events: LocalEventCatalog,
+        rules: tuple[_InterceptorRule, ...],
+    ) -> None:
+        entries: dict[tuple[object, str], _CompiledEntry] = {}
+        for module in registry.dependency_order:
+            for worker in module.module_type.background_worker_definitions:
+                self._add(entries, worker.worker_type, "run_iteration", module.key, rules, True)
+            for job in module.module_type.background_job_definitions:
+                self._add(entries, job.handler_type, "execute", module.key, rules, False)
+        for subscription in events.subscriptions:
+            scope = Scope.ACTION if subscription.phase is LocalEventPhase.DOMAIN else Scope.REQUEST
+            self._add(
+                entries,
+                subscription.handler_type,
+                "handle",
+                subscription.owner,
+                rules,
+                False,
+                outer_scope=scope,
+                method_scope=scope,
+            )
+        self._entries: Mapping[tuple[object, str], _CompiledEntry] = MappingProxyType(entries)
+
+    @property
+    def interceptor_scopes(self) -> tuple[tuple[InterceptorRegistration, Scope], ...]:
+        return tuple(
+            (
+                registration,
+                entry.method_scope
+                if registration.before is InterceptionStage.METHOD
+                else entry.outer_scope,
+            )
+            for entry in self._entries.values()
+            for registration in entry.descriptor.interceptors
+        )
+
+    @staticmethod
+    def _add(
+        entries: dict[tuple[object, str], _CompiledEntry],
+        target: object,
+        name: str,
+        owner: ModuleKey,
+        rules: tuple[_InterceptorRule, ...],
+        worker: bool,
+        *,
+        outer_scope: Scope = Scope.REQUEST,
+        method_scope: Scope = Scope.ACTION,
+    ) -> None:
+        if (target, name) in entries:
+            current = entries[target, name]
+            # 同一 handler 可订阅两个 phase；构建时使用所有实际入口的最窄解析边界。
+            entries[target, name] = replace(
+                current,
+                outer_scope=min(current.outer_scope, outer_scope),
+                method_scope=min(current.method_scope, method_scope),
+            )
+            return
+        function = getattr(target, name) if isinstance(target, type) else target
+        implementation = target if isinstance(target, type) else type(target)
+        declaration = _declaration(implementation, function)
+        if worker and not any(
+            hasattr(item, _UNIT_OF_WORK_ATTRIBUTE) for item in (implementation, function)
+        ):
+            declaration = UnitOfWorkDeclaration(disabled=True)
+        source = _method_source(function, owner)
+        descriptor = ApplicationServiceMethod(
+            name=name,
+            source=source,
+            requires_authenticated_user=False,
+            permissions=(),
+            allows_anonymous=True,
+            service=implementation,
+            implementation=implementation,
+            method=cast(Callable[..., Awaitable[object]], function),
+            validation_enabled=True,
+            auditing_enabled=False,
+            policy_sources=(source,),
+            unit_of_work=declaration,
+        )
+        descriptor = replace(descriptor, interceptors=_match_interceptors(descriptor, rules))
+        entries[target, name] = _CompiledEntry(
+            descriptor,
+            MappingProxyType(
+                {
+                    stage: tuple(item for item in descriptor.interceptors if item.before is stage)
+                    for stage in InterceptionStage
+                }
+            ),
+            outer_scope,
+            method_scope,
+        )
+
+    async def invoke(
+        self,
+        runtime: _InvocationRuntime,
+        container: AsyncContainer,
+        target: object,
+        name: str,
+        args: tuple[object, ...],
+        *,
+        connection_name: str | None = None,
+    ) -> object:
+        entry = self._entries[target, name]
+        pipeline = _InterceptorPipeline(entry.descriptor, entry.steps, args, {})
+
+        async def call(scope: AsyncContainer) -> object:
+            instance: object = (
+                await scope.get(cast(type[object], target)) if isinstance(target, type) else None
+            )
+            function = getattr(instance, name) if instance is not None else target
+            return await _call_in_scope(
+                cast(Callable[..., Awaitable[object]], function),
+                scope,
+                *pipeline.arguments.args,
+                **pipeline.arguments.kwargs,
+            )
+
+        async def method(scope: AsyncContainer) -> object:
+            return await pipeline.run(InterceptionStage.METHOD, scope, lambda: call(scope))
+
+        async def boundary() -> object:
+            if connection_name is None:
+                # Domain 参与原事务；Post-Commit 自身不复活旧 UoW，服务调用仍会建立新边界。
+                return await method(container)
+            return await runtime.run_action(
+                container,
+                connection_name=connection_name,
+                callback=method,
+                declaration=entry.descriptor.unit_of_work,
+                method_name=name,
+            )
+
+        stages = tuple(
+            stage for stage in InterceptionStage if stage is not InterceptionStage.METHOD
+        )
+
+        async def run(index: int) -> object:
+            if index == len(stages):
+                return await boundary()
+            return await pipeline.run(stages[index], container, lambda: run(index + 1))
+
+        return await run(0)

python_platform/lifecycle/__init__.py

@@ -0,0 +1,25 @@
+"""Lifecycle state 与按 stage 限权的 context capability。"""
+
+from .composition import ConfigureContext, PostConfigureContext, PreConfigureContext
+from .context import ApplicationView, LifecycleContext
+from .runtime import (
+    InitializeContext,
+    PostInitializeContext,
+    PreInitializeContext,
+    ShutdownContext,
+)
+from .state import ApplicationState, ShutdownReason
+
+__all__ = (
+    "ApplicationState",
+    "ApplicationView",
+    "ConfigureContext",
+    "InitializeContext",
+    "LifecycleContext",
+    "PostConfigureContext",
+    "PostInitializeContext",
+    "PreConfigureContext",
+    "PreInitializeContext",
+    "ShutdownContext",
+    "ShutdownReason",
+)

python_platform/lifecycle/composition.py

@@ -0,0 +1,35 @@
+"""同步 composition stages 各自可见的最小 capability context。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..configuration import ConfigurationRoot
+from ..events import EventContributor
+from ..options import PreOptionsSnapshot
+from ..options.contribution import _OptionsContributor
+from ..services import ServiceContributor
+from .context import LifecycleContext
+
+
+@dataclass(frozen=True, slots=True)
+class PreConfigureContext(LifecycleContext):
+    configuration: ConfigurationRoot
+    pre_configure: _OptionsContributor
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigureContext(LifecycleContext):
+    configuration: ConfigurationRoot
+    pre_options: PreOptionsSnapshot
+    configure: _OptionsContributor
+    services: ServiceContributor
+    events: EventContributor
+
+
+@dataclass(frozen=True, slots=True)
+class PostConfigureContext(LifecycleContext):
+    configuration: ConfigurationRoot
+    pre_options: PreOptionsSnapshot
+    configure: _OptionsContributor
+    services: ServiceContributor

python_platform/lifecycle/context.py

@@ -0,0 +1,31 @@
+"""所有 lifecycle stage 共享的只读 Application view 与 context 根。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from uuid import UUID
+
+from ..diagnostics import LifecycleStage
+from ..modularity import ModuleDescriptor, ModuleGraphSnapshot
+from .state import ApplicationState
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationView:
+    application_id: UUID
+    state: ApplicationState | None
+    modules: ModuleGraphSnapshot
+
+
+@dataclass(frozen=True, slots=True)
+class LifecycleContext:
+    application_id: UUID
+    descriptor: ModuleDescriptor
+    stage: LifecycleStage
+    application: ApplicationView
+    _emit: Callable[[str], None] = field(repr=False, compare=False)
+
+    def emit(self, code: str) -> None:
+        """写入当前 Module/stage 已限定作用域的稳定诊断 code。"""
+        self._emit(code)

python_platform/lifecycle/runtime.py

@@ -0,0 +1,43 @@
+"""异步 runtime 与 shutdown stages 的 native container context。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from dishka import AsyncContainer
+
+from ..configuration import ConfigurationRoot
+from ..diagnostics import LifecycleStage
+from ..options import OptionsSnapshot
+from .context import LifecycleContext
+from .state import ShutdownReason
+
+
+@dataclass(frozen=True, slots=True)
+class PreInitializeContext(LifecycleContext):
+    configuration: ConfigurationRoot
+    options: OptionsSnapshot
+    container: AsyncContainer
+
+
+@dataclass(frozen=True, slots=True)
+class InitializeContext(LifecycleContext):
+    configuration: ConfigurationRoot
+    options: OptionsSnapshot
+    container: AsyncContainer
+
+
+@dataclass(frozen=True, slots=True)
+class PostInitializeContext(LifecycleContext):
+    configuration: ConfigurationRoot
+    options: OptionsSnapshot
+    container: AsyncContainer
+
+
+@dataclass(frozen=True, slots=True)
+class ShutdownContext(LifecycleContext):
+    configuration: ConfigurationRoot
+    options: OptionsSnapshot
+    reason: ShutdownReason
+    completed_stages: tuple[LifecycleStage, ...]
+    container: AsyncContainer

python_platform/lifecycle/state.py

@@ -0,0 +1,20 @@
+"""Application lifecycle 的公开状态与 shutdown reason。"""
+
+from enum import Enum
+
+
+class ApplicationState(str, Enum):
+    COMPOSED = "composed"
+    STARTING = "starting"
+    RUNNING = "running"
+    ROLLING_BACK = "rolling_back"
+    FAILED_START = "failed_start"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    STOPPED_WITH_ERRORS = "stopped_with_errors"
+
+
+class ShutdownReason(str, Enum):
+    NORMAL = "normal"
+    START_FAILURE = "start_failure"
+    RUNTIME_FAILURE = "runtime_failure"

python_platform/modularity/__init__.py

@@ -0,0 +1,15 @@
+"""Module contracts、graph builder 与 immutable registry capability。"""
+
+from .contracts import AppModule, ModuleDependency, ModuleDependencyEdge, ModuleKey, ModuleRef
+from .registry import ModuleDescriptor, ModuleGraphSnapshot, ModuleRegistry
+
+__all__ = (
+    "AppModule",
+    "ModuleDependency",
+    "ModuleDependencyEdge",
+    "ModuleDescriptor",
+    "ModuleGraphSnapshot",
+    "ModuleKey",
+    "ModuleRef",
+    "ModuleRegistry",
+)