python-platform 0.1.1__py3-none-any.whl

python_platform/configuration/root.py

@@ -0,0 +1,215 @@
+"""Application-owned immutable ConfigurationRoot。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Mapping
+from dataclasses import replace
+from types import MappingProxyType
+from typing import cast
+
+from .contracts import (
+    ConfigurationProvenance,
+    ConfigurationSource,
+    ConfigurationSourceDiagnostic,
+    ConfigurationValueDiagnostic,
+    _SourcePayload,
+)
+from .values import (
+    MISSING,
+    canonical_path,
+    canonical_segment,
+    freeze_value,
+    lookup_path,
+    normalize_mapping,
+    redact_value,
+)
+
+
+class ConfigurationRoot(Mapping[str, object]):
+    """一次 Application build 拥有的不可变配置树和来源事实。"""
+
+    __slots__ = ("_payloads", "_provenance", "_secret_paths", "_sources", "_tree")
+
+    def __init__(
+        self,
+        *,
+        tree: Mapping[str, object],
+        provenance: Mapping[tuple[str, ...], ConfigurationProvenance],
+        secret_paths: frozenset[str],
+        sources: tuple[ConfigurationSourceDiagnostic, ...],
+        payloads: tuple[_SourcePayload, ...] = (),
+    ) -> None:
+        frozen_tree = freeze_value(tree)
+        if not isinstance(frozen_tree, Mapping):
+            raise TypeError("ConfigurationRoot tree must be a mapping")
+        self._tree = cast(Mapping[str, object], frozen_tree)
+        self._provenance = MappingProxyType(dict(provenance))
+        self._secret_paths = frozenset(secret_paths)
+        self._sources = tuple(sources)
+        self._payloads = payloads
+
+    def _bind_input_keys(
+        self,
+        mapping_paths: Callable[
+            [Mapping[str, object], tuple[Mapping[str, object], ...]],
+            frozenset[tuple[str | int | None, ...]],
+        ],
+        *,
+        sections: frozenset[str] | None = None,
+    ) -> ConfigurationRoot:
+        from ..errors import ConfigurationSourceError
+        from .merge import _ConfigurationMerger, _source_ordinal
+
+        if not self._payloads:
+            return self
+        normalized: list[_SourcePayload] = []
+        reference = tuple(
+            payload.values
+            for payload in sorted(
+                self._payloads, key=lambda item: (_source_ordinal(item.source), item.input_depth)
+            )
+        )
+        strict_paths = frozenset(canonical_path(section) for section in sections or ())
+        for payload in self._payloads:
+            values: dict[str, object] = {}
+            rejected = False
+            try:
+                for key, value in payload.values.items():
+                    values.update(
+                        normalize_mapping(
+                            {key: value},
+                            mapping_paths=mapping_paths(payload.values, reference),
+                            # PreOptions 只解释已声明的完整 section，不能提前裁决其兄弟字段。
+                            pending=sections is not None,
+                            strict_paths=strict_paths,
+                            merge_fields=payload.source
+                            in (ConfigurationSource.OS_ENVIRONMENT, ConfigurationSource.DOTENV),
+                        )
+                    )
+            except (TypeError, ValueError):
+                rejected = True
+            if rejected:
+                # 不保留原始键或值的异常引用；来源仍是冻结快照中的正式 provenance。
+                raise ConfigurationSourceError(
+                    source_id=payload.source.value,
+                    location=payload.location,
+                    original_error=ValueError("configuration input keys rejected"),
+                )
+            normalized.append(replace(payload, values=values))
+        result = _ConfigurationMerger().merge(
+            payloads=tuple(normalized),
+            diagnostics=self._sources,
+            secret_paths=self._secret_paths,
+        )
+        return ConfigurationRoot(
+            tree=result._tree,
+            provenance=result._provenance,
+            secret_paths=self._secret_paths,
+            sources=self._sources,
+            payloads=tuple(
+                replace(payload, values=cast(Mapping[str, object], freeze_value(payload.values)))
+                for payload in normalized
+            ),
+        )
+
+    def _section_inputs(self, section: str) -> tuple[tuple[object, bool], ...]:
+        from .merge import _source_ordinal
+
+        layers: list[tuple[object, bool]] = []
+        for payload in sorted(
+            self._payloads, key=lambda item: (_source_ordinal(item.source), item.input_depth)
+        ):
+            try:
+                value = lookup_path(payload.values, canonical_path(section))
+            except (KeyError, TypeError):
+                continue
+            layers.append(
+                (
+                    value,
+                    payload.source
+                    in (ConfigurationSource.OS_ENVIRONMENT, ConfigurationSource.DOTENV),
+                )
+            )
+        return tuple(layers)
+
+    @property
+    def sources(self) -> tuple[ConfigurationSourceDiagnostic, ...]:
+        return self._sources
+
+    def __getitem__(self, key: str) -> object:
+        return self._tree[canonical_segment(key)]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._tree)
+
+    def __len__(self) -> int:
+        return len(self._tree)
+
+    def __repr__(self) -> str:
+        return f"ConfigurationRoot(keys={len(self._tree)}, sources={len(self._sources)})"
+
+    def get_path(self, path: str, default: object = MISSING) -> object:
+        try:
+            value = lookup_path(self._tree, canonical_path(path))
+        except (KeyError, TypeError, ValueError):
+            if default is not MISSING:
+                return default
+            raise KeyError(path) from None
+        return value
+
+    def provenance(self, path: str) -> ConfigurationProvenance:
+        return self._provenance_at(canonical_path(path))
+
+    def _provenance_at(self, path: tuple[str, ...]) -> ConfigurationProvenance:
+        return self._provenance[path]
+
+    def diagnostic(self, path: str) -> ConfigurationValueDiagnostic:
+        canonical_parts = canonical_path(path)
+        canonical = ".".join(canonical_parts)
+        value, redacted = redact_value(
+            self.get_path(canonical),
+            path=canonical_parts,
+            secret_paths=self._secret_paths,
+        )
+        return ConfigurationValueDiagnostic(
+            path=canonical,
+            value=value,
+            redacted=redacted,
+            provenance=self.provenance(canonical),
+        )
+
+    def _finalize(
+        self,
+        *,
+        sections: frozenset[str],
+        secret_paths: frozenset[str],
+        mapping_paths: Callable[
+            [Mapping[str, object], tuple[Mapping[str, object], ...]],
+            frozenset[tuple[str | int | None, ...]],
+        ],
+    ) -> ConfigurationRoot:
+        from ..errors import ConfigurationSourceError
+
+        resolved = self._bind_input_keys(mapping_paths)
+        known = {canonical_path(section)[0] for section in sections}
+        external = {
+            ConfigurationSource.DOTENV,
+            ConfigurationSource.OS_ENVIRONMENT,
+            ConfigurationSource.CLI,
+        }
+        for key in self:
+            chain = self.provenance(key).chain
+            if key not in known and all(item.source_id in external for item in chain):
+                source = chain[-1]
+                raise ConfigurationSourceError(
+                    source_id=source.source_id.value,
+                    location=source.source_location,
+                    original_error=ValueError("unknown configuration section"),
+                )
+        # 旧 context 保留保守脱敏视图；只发布新的诊断视图，不重读或改变配置值。
+        return ConfigurationRoot(
+            tree=resolved._tree,
+            provenance=resolved._provenance,
+            secret_paths=secret_paths,
+            sources=self._sources,
+        )