python-platform 0.1.1__py3-none-any.whl

python_platform/settings/contracts.py

@@ -0,0 +1,115 @@
+"""SettingDefinition 的名称、类型校验与不可变默认值。"""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar, cast, get_args, get_origin
+
+from pydantic import BaseModel, Secret, SecretBytes, SecretStr, TypeAdapter, ValidationError
+
+from ..configuration.immutability import (
+    _serialization_value,
+    freeze_typed_value,
+    validate_immutable_annotation,
+)
+from ..configuration.values import _looks_secret_name, canonical_path
+from .errors import RuntimeSettingError, SettingDefinitionError
+
+_T = TypeVar("_T")
+_MISSING = object()
+
+
+class SettingDefinition(Generic[_T]):
+    __slots__ = ("_adapter", "_default", "_name", "_value_type")
+
+    def __init__(self, name: str, value_type: type[_T], *, default: object = _MISSING) -> None:
+        _validate_setting_name(name)
+        if not isinstance(value_type, type):
+            raise SettingDefinitionError(setting=name, reason="value_type must be a runtime type")
+        if _contains_secret_type(value_type):
+            raise SettingDefinitionError(
+                setting=name, reason="runtime settings cannot contain secrets"
+            )
+        try:
+            validate_immutable_annotation(value_type)
+            adapter: TypeAdapter[_T] = TypeAdapter(value_type)
+            validated_default = (
+                _MISSING
+                if default is _MISSING
+                else freeze_typed_value(adapter.validate_python(default), allow_secrets=False)
+            )
+        except (TypeError, ValidationError) as original_error:
+            raise SettingDefinitionError(
+                setting=name,
+                reason=f"default is invalid: {type(original_error).__name__}",
+            ) from None
+        self._name = name
+        self._value_type = value_type
+        self._adapter = adapter
+        self._default = validated_default
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def value_type(self) -> type[_T]:
+        return self._value_type
+
+    @property
+    def has_default(self) -> bool:
+        return self._default is not _MISSING
+
+    def _validate_python(self, value: object) -> _T:
+        return cast(
+            _T, freeze_typed_value(self._adapter.validate_python(value), allow_secrets=False)
+        )
+
+    def _validate_json(self, value: str) -> _T:
+        return cast(_T, freeze_typed_value(self._adapter.validate_json(value), allow_secrets=False))
+
+    def _dump_json(self, value: object) -> tuple[_T, str]:
+        validated = self._validate_python(value)
+        # frozen snapshot 中的 MappingProxyType 不是 Pydantic 原生 dict serializer 输入。
+        # 只在 I/O 边界复制容器，继续用同一 TypeAdapter 编码，不暴露可变副本。
+        serialized = self._adapter.dump_json(cast(_T, _serialization_value(validated))).decode(
+            "utf-8"
+        )
+        return validated, serialized
+
+    def _default_value(self) -> _T:
+        if self._default is _MISSING:
+            raise RuntimeSettingError(
+                setting=self.name,
+                operation="get",
+                error_type="MissingSettingValue",
+            )
+        return cast(_T, self._default)
+
+
+def _validate_setting_name(name: object) -> None:
+    if isinstance(name, str) and _looks_secret_name(name):
+        raise SettingDefinitionError(setting=name, reason="runtime settings cannot store secrets")
+    try:
+        if not isinstance(name, str) or ".".join(canonical_path(name)) != name:
+            raise ValueError("setting name must already be canonical")
+    except (TypeError, ValueError):
+        raise SettingDefinitionError(
+            setting=repr(name), reason="name must be a canonical configuration path"
+        ) from None
+
+
+def _contains_secret_type(value_type: object, seen: frozenset[object] = frozenset()) -> bool:
+    if value_type in seen:
+        return False
+    if isinstance(value_type, type) and issubclass(value_type, (Secret, SecretStr, SecretBytes)):
+        return True
+    if isinstance(value_type, type) and issubclass(value_type, BaseModel):
+        next_seen = seen | {value_type}
+        return any(
+            _contains_secret_type(field.annotation, next_seen)
+            for field in value_type.model_fields.values()
+        )
+    origin = get_origin(value_type)
+    return origin is not None and any(
+        _contains_secret_type(argument, seen) for argument in get_args(value_type)
+    )

python_platform/settings/definition_discovery.py

@@ -0,0 +1,71 @@
+"""把受控类型发现解释为 Settings 定义；校验只发生在用户贡献边界。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any, cast
+
+from ..diagnostics import SourceLocation
+from ..modularity.discovery import _DiscoveredType
+from .contracts import SettingDefinition
+from .definitions import SettingDefinitionContext, SettingDefinitionProvider
+from .errors import SettingDefinitionError
+
+
+def _collect_setting_definitions(
+    discoveries: tuple[_DiscoveredType, ...],
+) -> tuple[tuple[SettingDefinition[Any], ...], dict[str, SourceLocation]]:
+    providers: dict[type[object], SourceLocation] = {}
+    sources: dict[str, SourceLocation] = {}
+    definitions: list[SettingDefinition[Any]] = []
+    for discovery in discoveries:
+        candidate = discovery.candidate
+        if not issubclass(candidate, SettingDefinitionProvider) or inspect.isabstract(candidate):
+            continue
+        previous = providers.get(candidate)
+        if previous is not None:
+            if previous.owner != discovery.source.owner:
+                raise SettingDefinitionError(
+                    setting=candidate.__qualname__,
+                    reason=f"provider is already owned by {previous}",
+                    source=discovery.source,
+                )
+            continue
+        providers[candidate] = discovery.source
+        for definition in _define(candidate, discovery.source):
+            if definition.name in sources:
+                raise SettingDefinitionError(
+                    setting=definition.name,
+                    reason=f"setting is already owned by {sources[definition.name]}",
+                    source=discovery.source,
+                )
+            sources[definition.name] = discovery.source
+            definitions.append(definition)
+    return tuple(definitions), sources
+
+
+def _define(
+    provider_type: type[SettingDefinitionProvider], source: SourceLocation
+) -> tuple[SettingDefinition[Any], ...]:
+    context = SettingDefinitionContext(source)
+    try:
+        provider = provider_type()
+        callback = cast(Callable[[SettingDefinitionContext], object], provider.define)
+        if inspect.iscoroutinefunction(callback) or inspect.isasyncgenfunction(callback):
+            raise TypeError("define must be synchronous")
+        result = callback(context)
+        if result is not None:
+            # 拒绝同步函数偷渡 coroutine，同时释放尚未运行的原生 coroutine/generator。
+            if inspect.iscoroutine(result) or inspect.isgenerator(result):
+                result.close()
+            raise TypeError("define must return None")
+    except Exception as error:
+        raise SettingDefinitionError(
+            setting=provider_type.__qualname__,
+            reason=f"definition provider failed: {type(error).__name__}: {error}",
+            source=source,
+        ) from error
+    finally:
+        definitions = context._close()
+    return definitions

python_platform/settings/definitions.py

@@ -0,0 +1,41 @@
+"""同步定义贡献的契约与一次调用独占的上下文；不接触运行期容器。"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..diagnostics import SourceLocation
+from .contracts import SettingDefinition
+from .errors import SettingDefinitionError
+
+
+class SettingDefinitionProvider(ABC):
+    @abstractmethod
+    def define(self, context: SettingDefinitionContext) -> None:
+        """向所属 Application 贡献定义；必须同步完成并返回 None。"""
+
+
+class SettingDefinitionContext:
+    __slots__ = ("_closed", "_definitions", "_source")
+
+    def __init__(self, source: SourceLocation) -> None:
+        self._source = source
+        self._definitions: list[SettingDefinition[Any]] = []
+        self._closed = False
+
+    def add(self, definition: SettingDefinition[Any]) -> None:
+        if self._closed:
+            raise SettingDefinitionError(
+                setting="context", reason="definition context is closed", source=self._source
+            )
+        if not isinstance(definition, SettingDefinition):
+            raise SettingDefinitionError(
+                setting="context", reason="expected SettingDefinition", source=self._source
+            )
+        self._definitions.append(definition)
+
+    def _close(self) -> tuple[SettingDefinition[Any], ...]:
+        # 成功或异常都封闭上下文；外部保留的引用不能再贡献定义。
+        self._closed = True
+        return tuple(self._definitions)

python_platform/settings/errors.py

@@ -0,0 +1,22 @@
+"""Runtime Settings definition、lookup 与 provider failures。"""
+
+from __future__ import annotations
+
+from ..diagnostics import SourceLocation
+from ..errors.base import FrameworkError
+
+
+class SettingDefinitionError(FrameworkError):
+    def __init__(self, *, setting: str, reason: str, source: SourceLocation | None = None) -> None:
+        self.setting = setting
+        self.reason = reason
+        self.source = source
+        super().__init__(f"Invalid setting {setting!r}: {reason}; source={source}")
+
+
+class RuntimeSettingError(FrameworkError):
+    def __init__(self, *, setting: str, operation: str, error_type: str) -> None:
+        self.setting = setting
+        self.operation = operation
+        self.error_type = error_type
+        super().__init__(f"Runtime setting {operation} failed for {setting!r} with {error_type}")

python_platform/settings/handlers.py

@@ -0,0 +1,43 @@
+"""长期组件的 typed 应用契约；执行上下文由组件自身负责。"""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import Generic, Protocol, TypeVar
+
+from .contracts import SettingDefinition
+from .errors import SettingDefinitionError
+from .values import SettingSnapshot
+
+_T = TypeVar("_T")
+
+
+class SettingHandler(Protocol[_T]):
+    async def apply(self, snapshot: SettingSnapshot[_T]) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class SettingHandlerDefinition(Generic[_T]):
+    setting: SettingDefinition[_T]
+    handler_type: type[SettingHandler[_T]]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.setting, SettingDefinition):
+            raise SettingDefinitionError(setting="handler", reason="setting must be a definition")
+        if (
+            not isinstance(self.handler_type, type)
+            or inspect.isabstract(self.handler_type)
+            or not inspect.iscoroutinefunction(getattr(self.handler_type, "apply", None))
+        ):
+            raise SettingDefinitionError(
+                setting=self.setting.name, reason="handler must have an async apply method"
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class SettingApplicationStatus:
+    setting: str
+    handler: str
+    last_applied: SettingSnapshot[object] | None
+    error_type: str | None

python_platform/settings/management.py

@@ -0,0 +1,57 @@
+"""Settings 管理的权限、输入与 HTTP 可序列化结果契约。"""
+
+from __future__ import annotations
+
+from typing import Literal, Protocol
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, JsonValue
+
+from ..application_services import ApplicationServiceContract
+from ..authorization import PermissionName
+from ..notifications import NotificationPublishStatus
+from .values import SettingValueSource
+
+SETTINGS_READ = PermissionName("settings.read")
+SETTINGS_WRITE = PermissionName("settings.write")
+
+
+class UpdateSettingCommand(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    value: JsonValue
+    expected_version: UUID | None
+
+
+class ResetSettingCommand(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    expected_version: UUID | None
+
+
+class SettingView(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    value: JsonValue
+    source: SettingValueSource
+    version: UUID | None
+    effect: str = "New operations read the saved value; running components apply it separately."
+
+
+class SettingWriteResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    saved: Literal[True] = True
+    setting: SettingView
+    notification: NotificationPublishStatus
+
+
+class SettingsManagementApplicationService(ApplicationServiceContract, Protocol):
+    async def get_list(self) -> tuple[SettingView, ...]: ...
+
+    async def get(self, name: str) -> SettingView: ...
+
+    async def update(self, name: str, command: UpdateSettingCommand) -> SettingWriteResult: ...
+
+    async def reset(self, name: str, command: ResetSettingCommand) -> SettingWriteResult: ...

python_platform/settings/manager.py

@@ -0,0 +1,89 @@
+"""条件写入与提交后通知的 owner；读取解析由 SettingProvider 负责。"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+from uuid import UUID
+
+from pydantic import ValidationError
+from pydantic_core import PydanticSerializationError
+
+from ..notifications import NotificationPayloadError, NotificationPublishStatus, Notifications
+from .catalog import SettingCatalog
+from .changes import SETTINGS_CHANGED, SettingChanged
+from .contracts import SettingDefinition
+from .errors import RuntimeSettingError
+from .provider import SettingProvider
+from .store import RuntimeSettingStore
+from .values import SettingSnapshot, SettingValueSource, SettingWriteOutcome, StoredSetting
+
+if TYPE_CHECKING:
+    from .refresh import SettingsRefreshRuntime
+
+_T = TypeVar("_T")
+_LOGGER = logging.getLogger(__name__)
+
+
+class SettingManager:
+    __slots__ = ("_catalog", "_notifications", "_provider", "_refresh", "_store")
+
+    def __init__(
+        self, catalog: SettingCatalog, provider: SettingProvider, store: RuntimeSettingStore
+    ) -> None:
+        self._catalog = catalog
+        self._provider = provider
+        self._store = store
+        self._refresh: SettingsRefreshRuntime | None = None
+        self._notifications: Notifications | None = None
+
+    async def set_global(self, definition: SettingDefinition[_T], value: _T) -> _T:
+        current = await self._provider.snapshot(definition)
+        saved = await self.update(definition, value, expected_version=current.version)
+        return cast(_T, saved.snapshot.value)
+
+    async def reset_global(self, definition: SettingDefinition[Any]) -> None:
+        current = await self._provider.snapshot(definition)
+        await self.reset(definition, expected_version=current.version)
+
+    async def update(
+        self, definition: SettingDefinition[_T], value: object, *, expected_version: UUID | None
+    ) -> SettingWriteOutcome[_T]:
+        self._catalog.require_owned(definition)
+        try:
+            validated, serialized = definition._dump_json(value)
+        except (TypeError, ValidationError, PydanticSerializationError):
+            raise RuntimeSettingError(
+                setting=definition.name, operation="set", error_type="ValidationError"
+            ) from None
+        saved = await self._store.write(
+            definition.name, serialized, expected_version=expected_version
+        )
+        # 返回本次已经提交的值，不在提交后重读，避免把另一次并发写入误报为本次结果。
+        snapshot = SettingSnapshot(
+            definition.name, validated, SettingValueSource.RUNTIME, saved.version
+        )
+        return SettingWriteOutcome(snapshot, await self._committed(definition.name))
+
+    async def reset(
+        self, definition: SettingDefinition[_T], *, expected_version: UUID | None
+    ) -> SettingWriteOutcome[_T]:
+        self._catalog.require_owned(definition)
+        # 默认值先校验，不能在物理删除已经提交之后再抛出配置校验失败。
+        fallback = self._provider._resolve(definition, StoredSetting(None, expected_version))
+        saved = await self._store.write(definition.name, None, expected_version=expected_version)
+        snapshot = SettingSnapshot(definition.name, fallback.value, fallback.source, saved.version)
+        return SettingWriteOutcome(snapshot, await self._committed(definition.name))
+
+    async def _committed(self, name: str) -> NotificationPublishStatus:
+        # 本地刷新先入队；Redis 降级不会撤销短事务已经提交的结果。
+        if self._refresh is not None:
+            self._refresh.request_refresh(name)
+        if self._notifications is None:
+            return NotificationPublishStatus.NOT_CONFIGURED
+        try:
+            return await self._notifications.publish(SETTINGS_CHANGED, SettingChanged(name=name))
+        except NotificationPayloadError:
+            # 发布大小/编码限制是独立结果；不能把已提交的写入重新表现为保存失败。
+            _LOGGER.warning("Committed setting notification rejected for %s", name)
+            return NotificationPublishStatus.REJECTED

python_platform/settings/module.py

@@ -0,0 +1,7 @@
+"""Provider-neutral 的 Settings 管理服务与权限贡献。"""
+
+from ..modularity import AppModule
+
+
+class SettingsManagementModule(AppModule):
+    scan_packages = ("python_platform.settings.application", "python_platform.settings.permissions")

python_platform/settings/notifications.py

@@ -0,0 +1,39 @@
+"""Settings 是通用通知的使用方，重连和漏消息的补偿由 Settings 自身拥有。"""
+
+from __future__ import annotations
+
+from contextlib import AsyncExitStack
+
+from ..lifecycle import PreInitializeContext, ShutdownContext
+from ..modularity import AppModule
+from ..notifications import Notifications
+from .changes import SETTINGS_CHANGED, SettingChanged
+from .manager import SettingManager
+from .refresh import SettingsRefreshRuntime
+from .refresh_module import SettingsRefreshModule
+
+
+class SettingsNotificationsModule(AppModule):
+    dependencies = (SettingsRefreshModule,)
+    notification_definitions = (SETTINGS_CHANGED,)
+
+    def __init__(self) -> None:
+        self._subscriptions = AsyncExitStack()
+
+    async def pre_initialize(self, context: PreInitializeContext) -> None:
+        refresh = await context.container.get(SettingsRefreshRuntime)
+        notifications = await context.container.get(Notifications)
+        settings = await context.container.get(SettingManager)
+
+        async def changed(message: SettingChanged) -> None:
+            refresh.request_refresh(message.name)
+
+        await self._subscriptions.enter_async_context(
+            notifications.subscribe(SETTINGS_CHANGED, changed, on_reconnect=refresh.request_refresh)
+        )
+        settings._notifications = notifications
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        settings = await context.container.get(SettingManager)
+        settings._notifications = None
+        await self._subscriptions.aclose()

python_platform/settings/permissions.py

@@ -0,0 +1,14 @@
+"""settings 权限定义；持久化名称继续来自所属正式契约。"""
+
+from ..authorization import (
+    PermissionDefinition,
+    PermissionDefinitionContext,
+    PermissionDefinitionProvider,
+)
+from .management import SETTINGS_READ, SETTINGS_WRITE
+
+
+class SettingsPermissionDefinitionProvider(PermissionDefinitionProvider):
+    def define(self, context: PermissionDefinitionContext) -> None:
+        context.add(PermissionDefinition(SETTINGS_READ, "Read settings"))
+        context.add(PermissionDefinition(SETTINGS_WRITE, "Write settings"))

python_platform/settings/provider.py

@@ -0,0 +1,74 @@
+"""有效值读取：存储覆盖、Application 配置快照、不可变定义默认值。"""
+
+from __future__ import annotations
+
+from typing import TypeVar, cast
+
+from pydantic import ValidationError
+from pydantic_core import PydanticSerializationError
+
+from ..configuration import ConfigurationRoot
+from .catalog import SettingCatalog
+from .contracts import SettingDefinition
+from .errors import RuntimeSettingError
+from .store import RuntimeSettingStore
+from .values import SettingSnapshot, SettingValueSource, StoredSetting
+
+_T = TypeVar("_T")
+_MISSING = object()
+
+
+class SettingProvider:
+    __slots__ = ("_catalog", "_configuration", "_store")
+
+    def __init__(
+        self,
+        catalog: SettingCatalog,
+        configuration: ConfigurationRoot,
+        store: RuntimeSettingStore | None = None,
+    ) -> None:
+        self._catalog = catalog
+        self._configuration = configuration
+        self._store = store
+
+    async def get(self, definition: SettingDefinition[_T]) -> _T:
+        snapshot = await self.snapshot(definition)
+        if snapshot.source is SettingValueSource.UNSET:
+            raise RuntimeSettingError(
+                setting=definition.name, operation="get", error_type="MissingSettingValue"
+            )
+        return cast(_T, snapshot.value)
+
+    async def snapshot(self, definition: SettingDefinition[_T]) -> SettingSnapshot[_T]:
+        self._catalog.require_owned(definition)
+        stored = (
+            await self._store.read(definition.name)
+            if self._store is not None
+            else StoredSetting(None, None)
+        )
+        return self._resolve(definition, stored)
+
+    def _resolve(
+        self, definition: SettingDefinition[_T], stored: StoredSetting
+    ) -> SettingSnapshot[_T]:
+        try:
+            if stored.value_json is not None:
+                value = definition._validate_json(stored.value_json)
+                source = SettingValueSource.RUNTIME
+            else:
+                configured = self._configuration.get_path(f"settings.{definition.name}", _MISSING)
+                if configured is not _MISSING:
+                    value = definition._validate_python(configured)
+                    source = SettingValueSource.CONFIGURATION
+                elif definition.has_default:
+                    value = definition._default_value()
+                    source = SettingValueSource.DEFINITION
+                else:
+                    return SettingSnapshot(
+                        definition.name, None, SettingValueSource.UNSET, stored.version
+                    )
+            return SettingSnapshot(definition.name, value, source, stored.version)
+        except (TypeError, ValidationError, PydanticSerializationError):
+            raise RuntimeSettingError(
+                setting=definition.name, operation="get", error_type="ValidationError"
+            ) from None