python-platform 0.1.1__py3-none-any.whl

python_platform/options/registry.py

@@ -0,0 +1,280 @@
+"""Application-owned Options definitions、patch journal 与 binding barrier。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import cast
+
+from pydantic import BaseModel, ValidationError
+
+from ..configuration.immutability import freeze_typed_value
+from ..configuration.root import ConfigurationRoot
+from ..configuration.values import MISSING, freeze_value, normalize_mapping
+from ..diagnostics import LifecycleStage
+from ..errors import (
+    DuplicateOptionDefinitionError,
+    InvalidOptionDefinitionError,
+    OptionsValidationError,
+    UnknownOptionsError,
+)
+from ..modularity import ModuleDescriptor
+from .aliases import _prefer_higher_priority_alias_inputs
+from .contribution import _OptionsContributor
+from .immutability import (
+    _mapping_paths,
+    _merge_patch_input,
+    _thaw_value,
+)
+from .input_keys import _field_at, _InputReference, _mapping_input_paths
+from .issues import _OptionsIssueBuilder, _sanitized_validation_error
+from .models import (
+    OptionsSnapshot,
+    PreOptionsSnapshot,
+    _OptionDefinition,
+    _OptionPatch,
+    _OwnedOptionDefinition,
+)
+from .schema import _definition_secret_paths, _validate_definition
+from .validation import _validate_input
+
+
+class _OptionsRegistry:
+    """一次 Application build 的 definitions 与 append-only patch owner。"""
+
+    __slots__ = ("_claims", "_definitions", "_kind", "_ordered", "_patches")
+
+    def __init__(
+        self,
+        *,
+        kind: str,
+        claims: dict[type[BaseModel], tuple[str, ModuleDescriptor]],
+    ) -> None:
+        self._ordered: list[_OwnedOptionDefinition] = []
+        self._definitions: dict[type[BaseModel], _OwnedOptionDefinition] = {}
+        self._claims = claims
+        self._kind = kind
+        self._patches: list[_OptionPatch] = []
+
+    @property
+    def sections(self) -> frozenset[str]:
+        return frozenset(owned.definition.section for owned in self._ordered)
+
+    def mapping_paths(
+        self,
+        values: Mapping[str, object],
+        reference: tuple[Mapping[str, object], ...],
+        snapshot: OptionsSnapshot | PreOptionsSnapshot | None = None,
+    ) -> frozenset[tuple[str | int | None, ...]]:
+        paths: set[tuple[str | int | None, ...]] = set()
+        for owned in self._ordered:
+            section = tuple(owned.definition.section.split("."))
+            value = _field_at(values, section)
+            if value is MISSING:
+                continue
+            hint = _field_at(_InputReference(reference), section)
+            paths.update(
+                (*section, *path)
+                for path in _mapping_input_paths(
+                    owned.definition.model_type,
+                    value,
+                    hint,
+                    snapshot.get(owned.definition.model_type) if snapshot is not None else None,
+                )
+            )
+        return frozenset(paths)
+
+    @property
+    def secret_paths(self) -> frozenset[str]:
+        paths: set[str] = set()
+        for owned in self._ordered:
+            section = owned.definition.section
+            paths.update(f"{section}.{path}" for path in _definition_secret_paths(owned.definition))
+        return frozenset(paths)
+
+    def contributor(self, *, owner: ModuleDescriptor, stage: LifecycleStage) -> _OptionsContributor:
+        return _OptionsContributor(self, owner=owner, stage=stage, kind=self._kind)
+
+    def declare(
+        self,
+        model_type: type[BaseModel],
+        section: str,
+        *,
+        secret_paths: frozenset[str],
+        owner: ModuleDescriptor,
+        stage: LifecycleStage,
+        reason: str | None = None,
+    ) -> None:
+        if reason is not None:
+            _validate_patch_reason(reason)
+        definition = _validate_definition(
+            _OptionDefinition(model_type, section, secret_paths), owner=owner, kind=self._kind
+        )
+        existing = self._claims.get(model_type)
+        if existing is not None:
+            raise DuplicateOptionDefinitionError(
+                model_type=model_type,
+                option_kind=self._kind,
+                first_owner=existing[1].key,
+                second_owner=owner.key,
+            )
+        self._claims[model_type] = (self._kind, owner)
+        owned = _OwnedOptionDefinition(definition, owner, stage, reason)
+        self._definitions[model_type] = owned
+        self._ordered.append(owned)
+
+    def declare_default(
+        self, model_type: type[BaseModel], section: str, *, owner: ModuleDescriptor
+    ) -> None:
+        if model_type not in self._definitions:
+            self.declare(
+                model_type,
+                section,
+                secret_paths=frozenset(),
+                owner=owner,
+                stage=LifecycleStage.POST_CONFIGURE,
+            )
+
+    def patch(
+        self,
+        model_type: type[BaseModel],
+        values: Mapping[str, object],
+        *,
+        owner: ModuleDescriptor,
+        stage: LifecycleStage,
+        reason: str | None,
+    ) -> None:
+        existing = self._claims.get(model_type)
+        if existing is not None and existing[0] != self._kind:
+            raise UnknownOptionsError(model_type, option_kind=self._kind)
+        if not isinstance(values, Mapping):
+            raise TypeError("Options patch values must be a mapping")
+        if reason is not None:
+            _validate_patch_reason(reason)
+        normalized = normalize_mapping(
+            values, mapping_paths=_mapping_input_paths(model_type, values, values)
+        )
+        frozen = freeze_value(normalized)
+        if not isinstance(frozen, Mapping):
+            raise RuntimeError("Options patch did not freeze to a mapping")
+        self._patches.append(
+            _OptionPatch(
+                model_type=model_type,
+                values=cast(Mapping[str, object], frozen),
+                field_paths=frozenset(_mapping_paths(normalized)),
+                owner=owner,
+                stage=stage,
+                reason=reason,
+            )
+        )
+
+    def bind_pre_options(self, configuration: ConfigurationRoot) -> PreOptionsSnapshot:
+        return PreOptionsSnapshot(self._bind(configuration), kind=self._kind)
+
+    def bind_options(self, configuration: ConfigurationRoot) -> OptionsSnapshot:
+        return OptionsSnapshot(self._bind(configuration), kind=self._kind)
+
+    def _bind(
+        self,
+        configuration: ConfigurationRoot,
+    ) -> Mapping[type[BaseModel], BaseModel]:
+        configuration = configuration._bind_input_keys(self.mapping_paths, sections=self.sections)
+        for patch in self._patches:
+            if patch.model_type not in self._definitions:
+                raise UnknownOptionsError(patch.model_type, option_kind=self._kind)
+        bound: dict[type[BaseModel], BaseModel] = {}
+        for owned in self._ordered:
+            definition = owned.definition
+            section_value = configuration.get_path(definition.section, {})
+            input_value = _thaw_value(section_value)
+            for patch in self._patches:
+                if patch.model_type is definition.model_type:
+                    input_value = _merge_patch_input(input_value, patch.values)
+            _prefer_higher_priority_alias_inputs(
+                definition.model_type,
+                input_value,
+                configuration=configuration,
+                section=definition.section,
+                patches=tuple(self._patches),
+            )
+            try:
+                model = _validate_options_model(
+                    definition.model_type,
+                    input_value,
+                    (
+                        *configuration._section_inputs(definition.section),
+                        *(
+                            (patch.values, False)
+                            for patch in self._patches
+                            if patch.model_type is definition.model_type
+                        ),
+                    ),
+                )
+            except ValidationError as original_error:
+                issues = _OptionsIssueBuilder(
+                    owned,
+                    configuration=configuration,
+                    input_value=input_value,
+                    patches=tuple(self._patches),
+                    secret_paths=self.secret_paths,
+                ).build(original_error)
+                validation_error = _sanitized_validation_error(
+                    definition.model_type,
+                    issues,
+                )
+                error = OptionsValidationError(
+                    model_type=definition.model_type,
+                    section=definition.section,
+                    owner=owned.owner.key,
+                    option_kind=self._kind,
+                    issues=issues,
+                    validation_error=validation_error,
+                )
+            else:
+                try:
+                    bound[definition.model_type] = cast(BaseModel, freeze_typed_value(model))
+                except TypeError as original_error:
+                    raise InvalidOptionDefinitionError(
+                        owner=owned.owner.key,
+                        model_type=definition.model_type,
+                        option_kind=self._kind,
+                        reason=str(original_error),
+                    ) from original_error
+                continue
+            # 不保留含原始 input/ctx 的 Pydantic exception context。
+            raise error from error.validation_error
+        return MappingProxyType(bound)
+
+
+def _validate_patch_reason(reason: str) -> None:
+    if not isinstance(reason, str) or not reason or len(reason) > 128:
+        raise ValueError(
+            "Options patch reason must be a stable identifier of at most 128 characters"
+        )
+    if not reason[0].isalpha() or any(
+        not (character.isalnum() or character in "._-") for character in reason
+    ):
+        raise ValueError("Options patch reason must be a stable identifier")
+
+
+def _validate_options_model(
+    model_type: type[BaseModel], value: object, layers: tuple[tuple[object, bool], ...]
+) -> BaseModel:
+    try:
+        return _validate_input(model_type, value, layers)
+    except ValidationError:
+        raise
+    except Exception:
+        # 用户 validator 的 TypeError 等不由 Pydantic 包装；也不能带原文穿过配置边界。
+        pass
+    raise ValidationError.from_exception_data(
+        model_type.__name__,
+        [
+            {
+                "type": "value_error",
+                "loc": (),
+                "input": None,
+                "ctx": {"error": ValueError("Options validator failed")},
+            }
+        ],
+    )