python-platform 0.1.1__py3-none-any.whl

python_platform/options/issues.py

@@ -0,0 +1,335 @@
+"""Options validation issue sanitization、secret 判定与 source-chain 诊断。"""
+
+from __future__ import annotations
+
+import types
+from collections.abc import Mapping
+from typing import Annotated, Any, Union, get_args, get_origin
+
+from pydantic import BaseModel, ValidationError
+
+from ..configuration.contracts import ConfigurationContribution
+from ..configuration.root import ConfigurationRoot
+from ..configuration.values import REDACTION_MARKER, _looks_secret, canonical_path
+from .aliases import (
+    _lookup_input_path,
+    _patch_affects_path,
+    _sequence_item_annotation,
+)
+from .models import (
+    MISSING,
+    OptionsContribution,
+    OptionsValidationIssue,
+    _OptionPatch,
+    _OwnedOptionDefinition,
+)
+from .schema import _field_input_paths, _field_validation_paths, _model_annotation
+
+DEFINITION_DEFAULT_SOURCE = "definition-default"
+OPTIONS_PATCH_SOURCE = "options-patch"
+NOT_RETAINED_MARKER = "<not-retained>"
+
+
+class _OptionsIssueBuilder:
+    """将含原始 input 的 Pydantic error 收窄为 framework-owned 安全诊断。"""
+
+    __slots__ = (
+        "_configuration",
+        "_input_value",
+        "_owned",
+        "_patches",
+        "_secret_paths",
+    )
+
+    def __init__(
+        self,
+        owned: _OwnedOptionDefinition,
+        *,
+        configuration: ConfigurationRoot,
+        input_value: object,
+        patches: tuple[_OptionPatch, ...],
+        secret_paths: frozenset[str],
+    ) -> None:
+        self._owned = owned
+        self._configuration = configuration
+        self._input_value = input_value
+        self._patches = patches
+        self._secret_paths = secret_paths
+
+    def build(self, original_error: ValidationError) -> tuple[OptionsValidationIssue, ...]:
+        issues: list[OptionsValidationIssue] = []
+        definition = self._owned.definition
+        for error_detail in original_error.errors(
+            include_url=False,
+            include_context=False,
+            include_input=False,
+        ):
+            relative_parts = _error_location(
+                error_detail.get("loc", ()),
+                input_value=self._input_value,
+            )
+            full_parts = (*canonical_path(definition.section), *relative_parts)
+            full_path = ".".join(full_parts)
+            secret = _path_is_secret(full_parts, self._secret_paths)
+            issues.append(
+                OptionsValidationIssue(
+                    field_path=full_path,
+                    error_type=str(error_detail.get("type", "validation_error")),
+                    input_value=(REDACTION_MARKER if secret else NOT_RETAINED_MARKER),
+                    redacted=secret,
+                    source_chain=self._source_chain(relative_parts, full_parts),
+                )
+            )
+        return tuple(issues)
+
+    def _source_chain(
+        self,
+        relative_parts: tuple[str, ...],
+        full_path: tuple[str, ...],
+    ) -> tuple[OptionsContribution, ...]:
+        definition = self._owned.definition
+        if _definition_default_affects_path(
+            definition.model_type,
+            relative_parts,
+            input_value=self._input_value,
+        ):
+            return (
+                OptionsContribution(
+                    source_id=DEFINITION_DEFAULT_SOURCE,
+                    source_location=self._owned.owner.declaration_source,
+                    stage=self._owned.stage,
+                    reason=self._owned.reason,
+                ),
+            )
+        chain = list(_nearest_configuration_contributions(self._configuration, full_path))
+        for patch in self._patches:
+            if patch.model_type is not definition.model_type:
+                continue
+            if _patch_affects_path(relative_parts, patch.field_paths):
+                chain.append(
+                    OptionsContribution(
+                        source_id=OPTIONS_PATCH_SOURCE,
+                        source_location=patch.owner.declaration_source,
+                        reason=patch.reason,
+                        stage=patch.stage,
+                    )
+                )
+        return tuple(chain)
+
+
+def _sanitized_validation_error(
+    model_type: type[BaseModel],
+    issues: tuple[OptionsValidationIssue, ...],
+) -> ValidationError:
+    line_errors: list[Any] = [
+        {
+            "type": "assertion_error",
+            "loc": tuple(issue.field_path.split(".")),
+            "input": issue.input_value,
+            "ctx": {
+                "error": AssertionError(f"validation failed with error type {issue.error_type}")
+            },
+        }
+        for issue in issues
+    ]
+    model_name = f"{model_type.__module__}.{model_type.__qualname__}"
+    return ValidationError.from_exception_data(
+        model_name,
+        line_errors,
+        hide_input=True,
+    )
+
+
+def _error_location(
+    location: object,
+    *,
+    input_value: object,
+) -> tuple[str, ...]:
+    raw_parts = _normalized_error_location_parts(location)
+    parts: list[str] = []
+    current = input_value
+    for index, part in enumerate(raw_parts):
+        include, current = _resolve_error_location_part(
+            current,
+            part,
+            remaining=raw_parts[index + 1 :],
+        )
+        if include:
+            parts.append(part)
+    return tuple(parts)
+
+
+def _normalized_error_location_parts(location: object) -> tuple[str, ...]:
+    if not isinstance(location, tuple):
+        return ()
+    raw_parts: list[str] = []
+    for item in location:
+        if isinstance(item, str):
+            raw_parts.append(item)
+        elif isinstance(item, int):
+            raw_parts.append(str(item))
+    return tuple(raw_parts)
+
+
+def _resolve_error_location_part(
+    current: object,
+    part: str,
+    *,
+    remaining: tuple[str, ...],
+) -> tuple[bool, object]:
+    if isinstance(current, Mapping):
+        if part in current:
+            return True, current[part]
+        if part in current.values() or any(later in current for later in remaining):
+            return False, current
+        return True, MISSING
+    if isinstance(current, (list, tuple)) and part.isdecimal():
+        item_index = int(part)
+        if item_index < len(current):
+            return True, current[item_index]
+    if current is MISSING:
+        return True, current
+    return False, current
+
+
+def _path_is_secret(path: tuple[str, ...], secret_paths: frozenset[str]) -> bool:
+    compact_path = tuple(part for part in path if not part.isdecimal())
+    for secret in secret_paths:
+        secret_path = tuple(secret.split("."))
+        if (
+            _path_is_prefix(secret_path, compact_path)
+            or _path_is_prefix(compact_path, secret_path)
+            or _path_is_ordered_subsequence(secret_path, compact_path)
+            or _path_is_ordered_subsequence(compact_path, secret_path)
+        ):
+            return True
+    return _looks_secret(path)
+
+
+def _path_is_prefix(prefix: tuple[str, ...], path: tuple[str, ...]) -> bool:
+    return len(prefix) <= len(path) and path[: len(prefix)] == prefix
+
+
+def _path_is_ordered_subsequence(
+    candidate: tuple[str, ...],
+    path: tuple[str, ...],
+) -> bool:
+    if not candidate:
+        return False
+    cursor = iter(path)
+    return all(any(part == expected for part in cursor) for expected in candidate)
+
+
+def _configuration_contribution(
+    contribution: ConfigurationContribution,
+) -> OptionsContribution:
+    return OptionsContribution(
+        source_id=contribution.source_id.value,
+        source_location=contribution.source_location,
+    )
+
+
+def _nearest_configuration_contributions(
+    configuration: ConfigurationRoot,
+    full_path: tuple[str, ...],
+) -> tuple[OptionsContribution, ...]:
+    parts = full_path
+    for length in range(len(parts), 0, -1):
+        try:
+            provenance = configuration._provenance_at(parts[:length])
+        except (KeyError, ValueError):
+            continue
+        return tuple(_configuration_contribution(item) for item in provenance.chain)
+    return ()
+
+
+def _definition_default_affects_path(
+    model_type: type[BaseModel],
+    path: tuple[str, ...],
+    *,
+    input_value: object,
+) -> bool:
+    if not path:
+        return False
+    for field_name, field in model_type.model_fields.items():
+        for input_path in _field_input_paths(field_name, field):
+            if path[: len(input_path)] != input_path:
+                continue
+            supplied = MISSING
+            if isinstance(input_value, Mapping):
+                for validation_path in _field_validation_paths(
+                    model_type,
+                    field_name,
+                    field,
+                ):
+                    supplied = _lookup_input_path(input_value, validation_path)
+                    if supplied is not MISSING:
+                        break
+            if supplied is MISSING:
+                return not field.is_required()
+            remaining = path[len(input_path) :]
+            if not remaining:
+                return False
+            return _annotation_default_affects_path(
+                field.annotation,
+                remaining,
+                input_value=supplied,
+            )
+    return False
+
+
+def _annotation_default_affects_path(
+    annotation: object,
+    path: tuple[str, ...],
+    *,
+    input_value: object,
+) -> bool:
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        arguments = get_args(annotation)
+        return bool(arguments) and _annotation_default_affects_path(
+            arguments[0],
+            path,
+            input_value=input_value,
+        )
+
+    model_type = _model_annotation(annotation)
+    if model_type is not None:
+        return _definition_default_affects_path(
+            model_type,
+            path,
+            input_value=input_value,
+        )
+
+    if origin in (Union, types.UnionType):
+        return any(
+            _annotation_default_affects_path(
+                argument,
+                path,
+                input_value=input_value,
+            )
+            for argument in get_args(annotation)
+        )
+
+    arguments = get_args(annotation)
+    if origin is Mapping and len(arguments) == 2 and path:
+        nested_input = MISSING
+        if isinstance(input_value, Mapping):
+            nested_input = input_value.get(path[0], MISSING)
+        return _annotation_default_affects_path(
+            arguments[1],
+            path[1:],
+            input_value=nested_input,
+        )
+    if origin in (tuple, frozenset) and path and path[0].isdecimal():
+        index = int(path[0])
+        nested_input = MISSING
+        if isinstance(input_value, (list, tuple)) and index < len(input_value):
+            nested_input = input_value[index]
+        item_annotation = _sequence_item_annotation(arguments, index)
+        return item_annotation is not None and _annotation_default_affects_path(
+            item_annotation,
+            path[1:],
+            input_value=nested_input,
+        )
+    return False

python_platform/options/models.py

@@ -0,0 +1,114 @@
+"""Typed Options definitions、patch facts 与 immutable snapshots。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Generic, TypeVar, cast
+
+from pydantic import BaseModel, ConfigDict
+
+from ..diagnostics import LifecycleStage, SourceLocation
+from ..errors import UnknownOptionsError
+from ..modularity import ModuleDescriptor
+
+TOptions = TypeVar("TOptions", bound=BaseModel)
+TDeclaredOptions_co = TypeVar(
+    "TDeclaredOptions_co",
+    bound=BaseModel,
+    covariant=True,
+)
+MISSING = object()
+
+
+class BaseOptions(BaseModel):
+    """配置 model 的统一默认契约，字段与 validator 沿用原生 Pydantic。"""
+
+    model_config = ConfigDict(frozen=True, validate_default=True)
+
+
+@dataclass(frozen=True, slots=True)
+class Options(Generic[TDeclaredOptions_co]):
+    """Application 内共享的最终配置快照，泛型参数也是原生 DI dependency key。"""
+
+    value: TDeclaredOptions_co = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class _OptionDefinition(Generic[TDeclaredOptions_co]):
+    model_type: type[TDeclaredOptions_co]
+    section: str
+    secret_paths: frozenset[str] = frozenset()
+
+
+@dataclass(frozen=True, slots=True)
+class OptionsContribution:
+    source_id: str
+    source_location: SourceLocation
+    reason: str | None = None
+    stage: LifecycleStage | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class OptionsValidationIssue:
+    field_path: str
+    error_type: str
+    input_value: str
+    redacted: bool
+    source_chain: tuple[OptionsContribution, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class _OwnedOptionDefinition:
+    definition: _OptionDefinition[BaseModel]
+    owner: ModuleDescriptor
+    stage: LifecycleStage
+    reason: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class _OptionPatch:
+    model_type: type[BaseModel]
+    values: Mapping[str, object]
+    field_paths: frozenset[tuple[str, ...]]
+    owner: ModuleDescriptor
+    stage: LifecycleStage
+    reason: str | None
+
+
+class _OptionsSnapshotBase:
+    __slots__ = ("_kind", "_values")
+
+    def __init__(
+        self,
+        values: Mapping[type[BaseModel], BaseModel],
+        *,
+        kind: str,
+    ) -> None:
+        self._values = MappingProxyType(dict(values))
+        self._kind = kind
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(models={len(self._values)})"
+
+    def get(self, model_type: type[TOptions]) -> TOptions:
+        try:
+            value = self._values[model_type]
+        except KeyError:
+            raise UnknownOptionsError(model_type, option_kind=self._kind) from None
+        # model_type 是索引 identity，只在该 key 下保存同一具体 Pydantic type。
+        return cast(TOptions, value)
+
+
+class OptionsSnapshot(_OptionsSnapshotBase):
+    """普通 Options 的 Application-local typed immutable lookup。"""
+
+    @property
+    def values(self) -> Mapping[type[BaseModel], BaseModel]:
+        """已完成绑定的正式定义；DI 消费此视图，不维护第二份类型清单。"""
+        return self._values
+
+
+class PreOptionsSnapshot(_OptionsSnapshotBase):
+    """全局 pre_configure barrier 后发布的 typed immutable lookup。"""