python-platform 0.1.1__py3-none-any.whl

python_platform/configuration/composition.py

@@ -0,0 +1,65 @@
+"""Configuration source loading 与 merge 的 Application composition owner。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from pathlib import Path
+from typing import cast
+
+from .contracts import _ConfigurationDefaultContribution
+from .merge import _ConfigurationMerger
+from .root import ConfigurationRoot
+from .sources import _ConfigurationSourceLoader
+from .values import freeze_value, normalize_mapping
+
+
+class _ConfigurationComposer:
+    """组合已验证参数，不暴露 source 或 mutable merge state 给 Application。"""
+
+    __slots__ = ("_loader",)
+
+    def __init__(
+        self,
+        *,
+        environment: str,
+        base_path: Path,
+        env_prefix: str,
+        dotenv_path: Path | None,
+        explicit_overrides: Mapping[str, object],
+        cli_args: tuple[str, ...],
+    ) -> None:
+        self._loader = _ConfigurationSourceLoader(
+            environment=environment,
+            base_path=base_path,
+            env_prefix=env_prefix,
+            dotenv_path=dotenv_path,
+            explicit_overrides=explicit_overrides,
+            cli_args=cli_args,
+        )
+
+    def build(
+        self,
+        defaults: tuple[_ConfigurationDefaultContribution, ...],
+    ) -> ConfigurationRoot:
+        payloads, diagnostics = self._loader.load(defaults)
+        frozen_payloads = tuple(
+            replace(payload, values=cast(Mapping[str, object], freeze_value(payload.values)))
+            for payload in payloads
+        )
+        initial = _ConfigurationMerger().merge(
+            payloads=tuple(
+                replace(payload, values=normalize_mapping(payload.values, pending=True))
+                for payload in frozen_payloads
+            ),
+            diagnostics=diagnostics,
+            secret_paths=frozenset(key for payload in payloads for key in payload.values),
+        )
+        # 临时配置视图用于 composition；类型明确后只重解释此快照，绝不重读来源。
+        return ConfigurationRoot(
+            tree=initial,
+            provenance=initial._provenance,
+            secret_paths=frozenset(initial),
+            sources=initial.sources,
+            payloads=frozen_payloads,
+        )

python_platform/configuration/contracts.py

@@ -0,0 +1,68 @@
+"""Configuration source、provenance 与 diagnostic value contracts。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import Enum
+
+from ..diagnostics import SourceLocation
+
+
+class ConfigurationSource(str, Enum):
+    MODULE_DEFAULTS = "module-defaults"
+    YAML_BASE = "yaml-base"
+    YAML_ENVIRONMENT = "yaml-environment"
+    DOTENV = "dotenv"
+    OS_ENVIRONMENT = "os-environment"
+    CLI = "cli"
+    EXPLICIT = "explicit"
+
+
+class ConfigurationSourceStatus(str, Enum):
+    LOADED = "loaded"
+    SKIPPED = "skipped"
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigurationSourceDiagnostic:
+    source: ConfigurationSource
+    status: ConfigurationSourceStatus
+    location: SourceLocation
+    reason: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigurationContribution:
+    source_id: ConfigurationSource
+    source_location: SourceLocation
+    raw_kind: str
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigurationProvenance:
+    path: str
+    chain: tuple[ConfigurationContribution, ...]
+    effective_source: ConfigurationContribution
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigurationValueDiagnostic:
+    path: str
+    value: object
+    redacted: bool
+    provenance: ConfigurationProvenance
+
+
+@dataclass(frozen=True, slots=True)
+class _ConfigurationDefaultContribution:
+    source_location: SourceLocation
+    values: Mapping[str, object]
+
+
+@dataclass(frozen=True, slots=True)
+class _SourcePayload:
+    source: ConfigurationSource
+    location: SourceLocation
+    values: Mapping[str, object]
+    input_depth: int = 0

python_platform/configuration/dotenv_source.py

@@ -0,0 +1,51 @@
+"""dotenv 文件单次读取；语法预检与原生 value 解码消费同一份文本。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from io import StringIO
+from pathlib import Path
+
+from dotenv import dotenv_values
+from dotenv.parser import parse_stream
+from pydantic_settings import DotEnvSettingsSource
+from pydantic_settings.sources.utils import parse_env_vars
+
+from ..diagnostics import SourceLocation
+from ..errors import ConfigurationSourceError
+from .contracts import ConfigurationSource
+from .environment_source import _LayeredEnvSource
+from .input_shape import _environment_input_name
+
+
+class _SnapshotDotEnvSource(DotEnvSettingsSource, _LayeredEnvSource):
+    def _read_env_file(self, file_path: Path) -> Mapping[str, str | None]:
+        text = file_path.read_text(encoding=self.env_file_encoding or "utf-8")
+        seen: set[str] = set()
+        for binding in parse_stream(StringIO(text)):
+            if binding.error:
+                raise ConfigurationSourceError(
+                    source_id=ConfigurationSource.DOTENV.value,
+                    location=SourceLocation(
+                        owner=ConfigurationSource.DOTENV.value,
+                        file=str(file_path),
+                        line=binding.original.line,
+                        symbol=None,
+                    ),
+                    original_error=ValueError("invalid dotenv syntax"),
+                )
+            key = binding.key
+            if key is not None and key.casefold().startswith(self.env_prefix.casefold()):
+                parts = _environment_input_name(key, self.env_prefix)
+                if parts in seen:
+                    raise ValueError("duplicate dotenv path")
+                seen.add(parts)
+        return parse_env_vars(
+            {
+                _environment_input_name(key, self.env_prefix): value
+                for key, value in dotenv_values(stream=StringIO(text)).items()
+            },
+            True,
+            self.env_ignore_empty,
+            self.env_parse_none_str,
+        )

python_platform/configuration/environment_source.py

@@ -0,0 +1,38 @@
+"""原生环境 source 的读取期分层；保留 JSON 与嵌套变量的覆盖身份。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic.fields import FieldInfo
+from pydantic_settings import EnvSettingsSource
+
+
+class _LayeredEnvSource(EnvSettingsSource):
+    def __call__(self) -> dict[str, Any]:
+        self.input_layers: dict[int, dict[str, object]] = {}
+        return super().__call__()
+
+    def prepare_field_value(
+        self, field_name: str, field: FieldInfo, value: Any, value_is_complex: bool
+    ) -> Any:
+        snapshot = self.env_vars
+        delimiter = self.env_nested_delimiter
+        assert delimiter is not None
+        depths = sorted({name.count(delimiter) for name in snapshot})
+        prepared: object = None
+        try:
+            for depth in depths:
+                self.env_vars = {
+                    name: raw for name, raw in snapshot.items() if name.count(delimiter) == depth
+                }
+                layer_value, _, complex_value = self.get_field_value(field, field_name)
+                decoded = super().prepare_field_value(field_name, field, layer_value, complex_value)
+                if decoded is not None:
+                    self.input_layers.setdefault(depth, {})[field_name] = decoded
+                    prepared = decoded
+        finally:
+            self.env_vars = snapshot
+        # __call__ 仍只执行一次；最终合并消费 input_layers，不消费这个原生返回视图。
+        # 这里不校验 Options，也不重读 OS 或 dotenv。
+        return prepared

python_platform/configuration/immutability.py

@@ -0,0 +1,124 @@
+"""Configuration value 所有的 typed snapshot 规则，供 Options 与 Settings 复用。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, MutableMapping, MutableSequence, MutableSet
+from enum import Enum
+from functools import cached_property
+from types import MappingProxyType
+from typing import Annotated, Any, Literal, cast, get_args, get_origin
+
+from pydantic import BaseModel, Secret, SecretBytes, SecretStr
+
+from .values import freeze_value, is_frozen_secret, is_supported_scalar
+
+
+def validate_model_shape(model_type: type[BaseModel]) -> None:
+    # frozen 只保护字段赋值，不能保护 extra 和 PrivateAttr。
+    if model_type.model_config.get("frozen") is not True:
+        raise TypeError("snapshot models must be frozen")
+    if model_type.model_config.get("extra") == "allow":
+        raise TypeError("snapshot models must not allow mutable extra fields")
+    if model_type.__private_attributes__:
+        raise TypeError("snapshot models must not declare private attributes")
+    if any(
+        isinstance(member, cached_property)
+        for base in model_type.__mro__
+        for member in vars(base).values()
+    ):
+        # cached_property 可绕过 frozen 在读取时向 __dict__ 写入缓存，不能发布为共享默认值。
+        raise TypeError("snapshot models must not declare cached properties")
+
+
+def validate_immutable_annotation(
+    annotation: object, seen: frozenset[object] = frozenset()
+) -> None:
+    if annotation in seen:
+        return
+    origin = get_origin(annotation)
+    if annotation in (Any, object):
+        raise TypeError("snapshot annotations must not use Any/object")
+    mutable = (list, dict, set, bytearray, MutableMapping, MutableSequence, MutableSet)
+    if annotation in mutable or origin in mutable:
+        raise TypeError("snapshot annotations must not use mutable containers")
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        validate_model_shape(annotation)
+        for field in annotation.model_fields.values():
+            validate_immutable_annotation(field.annotation, seen | {annotation})
+    elif isinstance(annotation, type) and issubclass(annotation, Enum):
+        if any(not is_supported_scalar(member) for member in annotation):
+            raise TypeError("snapshot enum members must be deeply immutable")
+    elif origin is Annotated:
+        validate_immutable_annotation(get_args(annotation)[0], seen)
+    elif origin is not Literal:
+        _validate_annotation_arguments(get_args(annotation), seen)
+
+
+def _validate_annotation_arguments(arguments: tuple[object, ...], seen: frozenset[object]) -> None:
+    for argument in arguments:
+        if argument is not Ellipsis:
+            validate_immutable_annotation(argument, seen)
+
+
+def freeze_typed_value(value: object, *, allow_secrets: bool = True) -> object:
+    if isinstance(value, (Secret, SecretStr, SecretBytes)):
+        if not allow_secrets:
+            raise TypeError("runtime settings cannot contain secrets")
+        return freeze_value(value)
+    if isinstance(value, BaseModel):
+        return _freeze_model(value, allow_secrets=allow_secrets)
+    if isinstance(value, Mapping):
+        return MappingProxyType(
+            {
+                freeze_typed_value(key, allow_secrets=allow_secrets): freeze_typed_value(
+                    item, allow_secrets=allow_secrets
+                )
+                for key, item in value.items()
+            }
+        )
+    if isinstance(value, tuple):
+        items = tuple(freeze_typed_value(item, allow_secrets=allow_secrets) for item in value)
+        if type(value) is tuple:
+            return items
+        fields = getattr(type(value), "_fields", None)
+        if isinstance(fields, tuple) and not hasattr(value, "__dict__"):
+            return cast(Callable[..., tuple[object, ...]], type(value))(*items)
+        raise TypeError("unsupported tuple subtype")
+    if isinstance(value, frozenset):
+        return frozenset(freeze_typed_value(item, allow_secrets=allow_secrets) for item in value)
+    if is_supported_scalar(value) or (allow_secrets and is_frozen_secret(value)):
+        return value
+    raise TypeError(f"validated object graph contains unsupported {type(value).__name__}")
+
+
+def _freeze_model(value: BaseModel, *, allow_secrets: bool) -> BaseModel:
+    validate_model_shape(type(value))
+    # model_copy 会保留 __dict__ 中的额外状态，因此复制前必须验证实例边界。
+    if set(vars(value)) - type(value).model_fields.keys():
+        raise TypeError("snapshot models must not contain undeclared instance state")
+    updates = {
+        name: freeze_typed_value(getattr(value, name), allow_secrets=allow_secrets)
+        for name in type(value).model_fields
+    }
+    return value.model_copy(update=updates)
+
+
+def _serialization_value(value: object) -> object:
+    """仅在原生 serializer 边界复制冻结容器，不发布这个可变副本。"""
+    if isinstance(value, BaseModel):
+        return value.model_copy(
+            update={
+                name: _serialization_value(getattr(value, name))
+                for name in type(value).model_fields
+            }
+        )
+    if isinstance(value, Mapping):
+        return {key: _serialization_value(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        items = tuple(_serialization_value(item) for item in value)
+        if type(value) is tuple:
+            return items
+        return cast(Callable[..., tuple[object, ...]], type(value))(*items)
+    if isinstance(value, frozenset):
+        return frozenset(_serialization_value(item) for item in value)
+    return value

python_platform/configuration/input_shape.py

@@ -0,0 +1,58 @@
+"""从实际输入路径构造原生 source 的读取形状，不持有 Options schema。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TypeAlias
+
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings
+
+from .values import canonical_segment
+
+_PathTree: TypeAlias = dict[str, "_PathTree"]
+
+
+def _environment_input_name(name: str, prefix: str) -> str:
+    if not name.casefold().startswith(prefix.casefold()):
+        return name
+    first, separator, tail = name[len(prefix) :].partition("__")
+    # section 是已知字段；后续路径的类型尚未声明，不能提前折叠 Mapping 的数据键。
+    return prefix.casefold() + canonical_segment(first) + separator + tail
+
+
+def _input_sections(names: Iterable[str], prefix: str) -> frozenset[str]:
+    return frozenset(
+        canonical_segment(name[len(prefix) :].split("__")[0])
+        for name in names
+        if name.casefold().startswith(prefix.casefold())
+    )
+
+
+def _cli_settings_type(args: tuple[str, ...]) -> type[BaseSettings]:
+    paths: _PathTree = {}
+    seen: set[tuple[str, ...]] = set()
+    for argument in args:
+        if argument in ("-h", "--help"):
+            # Builder 只接收应用配置参数；Host 处理 help，原生 argparse 不得退出宿主进程。
+            raise ValueError("help flags belong to the Host")
+        if not argument.startswith("--"):
+            continue
+        parts = tuple(canonical_segment(part) for part in argument[2:].split("=", 1)[0].split("."))
+        # 原生 CLI source 会合并对象或覆盖叶子；平台在解码前拒绝同一路径的重复声明。
+        if parts in seen:
+            raise ValueError("duplicate canonical CLI path")
+        seen.add(parts)
+        node = paths
+        for part in parts:
+            node = node.setdefault(part, {})
+    annotations = {key: _shape_annotation(value) for key, value in paths.items()}
+    return type("_ApplicationCliSettings", (BaseSettings,), {"__annotations__": annotations})
+
+
+def _shape_annotation(value: object) -> object:
+    if isinstance(value, dict) and value:
+        annotations = {key: _shape_annotation(child) for key, child in value.items()}
+        return type("_CliSection", (BaseModel,), {"__annotations__": annotations})
+    # Union 保留普通字符串，同时让原生 source 解码 JSON mapping/sequence。
+    return dict[str, object] | list[object] | str

python_platform/configuration/merge.py

@@ -0,0 +1,103 @@
+"""Configuration precedence、provenance chain 与 immutable root 发布。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from .contracts import (
+    ConfigurationContribution,
+    ConfigurationProvenance,
+    ConfigurationSource,
+    ConfigurationSourceDiagnostic,
+    _SourcePayload,
+)
+from .root import ConfigurationRoot
+from .values import MISSING, canonical_path, raw_kind
+
+
+class _ConfigurationMerger:
+    """拥有一次 merge 的 mutable working tree；完成后只发布 immutable root。"""
+
+    __slots__ = ("_chains", "_merged")
+
+    def __init__(self) -> None:
+        self._merged: dict[str, object] = {}
+        self._chains: dict[tuple[str, ...], list[ConfigurationContribution]] = {}
+
+    def merge(
+        self,
+        *,
+        payloads: tuple[_SourcePayload, ...],
+        diagnostics: tuple[ConfigurationSourceDiagnostic, ...],
+        secret_paths: frozenset[str],
+    ) -> ConfigurationRoot:
+        # Enum declaration 是唯一 priority metadata；source 调用顺序不参与覆盖裁决。
+        for payload in sorted(
+            payloads, key=lambda item: (_source_ordinal(item.source), item.input_depth)
+        ):
+            self._merge_mapping(self._merged, payload.values, prefix=(), payload=payload)
+        provenance = {
+            path: ConfigurationProvenance(
+                path=".".join(path),
+                chain=tuple(chain),
+                effective_source=chain[-1],
+            )
+            for path, chain in self._chains.items()
+        }
+        canonical_secrets = frozenset(".".join(canonical_path(path)) for path in secret_paths)
+        return ConfigurationRoot(
+            tree=self._merged,
+            provenance=provenance,
+            secret_paths=canonical_secrets,
+            sources=tuple(sorted(diagnostics, key=lambda item: _source_ordinal(item.source))),
+        )
+
+    def _merge_mapping(
+        self,
+        target: dict[str, object],
+        incoming: Mapping[str, object],
+        *,
+        prefix: tuple[str, ...],
+        payload: _SourcePayload,
+    ) -> None:
+        for key, incoming_value in incoming.items():
+            path_parts = (*prefix, key)
+            path = path_parts
+            contribution = ConfigurationContribution(
+                source_id=payload.source,
+                source_location=payload.location,
+                raw_kind=raw_kind(incoming_value),
+            )
+            current = target.get(key, MISSING)
+            if isinstance(current, dict) and isinstance(incoming_value, Mapping):
+                self._chains.setdefault(path, []).append(contribution)
+                self._merge_mapping(
+                    current,
+                    incoming_value,
+                    prefix=path_parts,
+                    payload=payload,
+                )
+                continue
+
+            self._remove_descendant_chains(path)
+            self._chains.setdefault(path, []).append(contribution)
+            if isinstance(incoming_value, Mapping):
+                nested: dict[str, object] = {}
+                target[key] = nested
+                self._merge_mapping(
+                    nested,
+                    incoming_value,
+                    prefix=path_parts,
+                    payload=payload,
+                )
+            else:
+                target[key] = incoming_value
+
+    def _remove_descendant_chains(self, path: tuple[str, ...]) -> None:
+        for descendant in tuple(self._chains):
+            if len(descendant) > len(path) and descendant[: len(path)] == path:
+                del self._chains[descendant]
+
+
+def _source_ordinal(source: ConfigurationSource) -> int:
+    return tuple(ConfigurationSource).index(source)