python-platform 0.1.1__py3-none-any.whl

python_platform/configuration/sources.py

@@ -0,0 +1,519 @@
+"""Pydantic Settings native sources 的受控读取与输入边界验证。"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Final, NoReturn, cast, get_origin
+
+from pydantic_settings import (
+    BaseSettings,
+    CliSettingsSource,
+    InitSettingsSource,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+)
+from pydantic_settings.sources.utils import parse_env_vars
+
+from ..diagnostics import SourceLocation
+from ..errors import ConfigurationSourceError
+from .contracts import (
+    ConfigurationSource,
+    ConfigurationSourceDiagnostic,
+    ConfigurationSourceStatus,
+    _ConfigurationDefaultContribution,
+    _SourcePayload,
+)
+from .dotenv_source import _SnapshotDotEnvSource
+from .environment_source import _LayeredEnvSource
+from .input_shape import _cli_settings_type, _environment_input_name, _input_sections
+from .values import _capture_input_mapping, canonical_path, canonical_segment, is_supported_scalar
+from .yaml_source import _YamlConfigurationSource
+
+_ENVIRONMENT_NESTED_DELIMITER: Final = "__"
+
+
+class _NativeConfigurationSettings(BaseSettings):
+    # Source 只负责读取/解码；最终 schema validation 归具体 Options model。
+    model_config = SettingsConfigDict(extra="ignore")
+
+
+class _SnapshotEnvSource(_LayeredEnvSource):
+    def _load_env_vars(self) -> Mapping[str, str | None]:
+        # 必须在原生大小写归一化丢失重复 key 前校验；校验和解码共享同一次原始读取。
+        snapshot = dict(os.environ)
+        inputs: dict[str, str] = {}
+        for name, value in snapshot.items():
+            key = _environment_input_name(name, self.env_prefix)
+            if key in inputs:
+                raise ValueError("duplicate canonical environment path")
+            inputs[key] = value
+        return parse_env_vars(inputs, True, self.env_ignore_empty, self.env_parse_none_str)
+
+
+class _ConfigurationSourceLoader:
+    """拥有一次 build 的 source 选择、动态 settings shape 与读取顺序。"""
+
+    __slots__ = (
+        "_base_path",
+        "_cli_args",
+        "_dotenv_path",
+        "_env_prefix",
+        "_environment",
+        "_explicit_overrides",
+    )
+
+    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._environment = environment
+        self._base_path = base_path
+        self._env_prefix = env_prefix
+        self._dotenv_path = dotenv_path
+        self._explicit_overrides = explicit_overrides
+        self._cli_args = cli_args
+
+    def load(
+        self,
+        defaults: tuple[_ConfigurationDefaultContribution, ...],
+    ) -> tuple[tuple[_SourcePayload, ...], tuple[ConfigurationSourceDiagnostic, ...]]:
+        failure: ConfigurationSourceError | None = None
+        try:
+            return self._load(defaults)
+        except ConfigurationSourceError as error:
+            failure = error
+        # 离开 except 后重建安全异常，断开原生 parser 的 input/context/traceback 引用。
+        assert failure is not None
+        raise ConfigurationSourceError(
+            source_id=failure.source_id,
+            location=failure.location,
+            original_error=(
+                FileNotFoundError("configuration file missing")
+                if isinstance(failure.original_error, FileNotFoundError)
+                else ValueError("configuration source rejected")
+            ),
+        )
+
+    def _load(
+        self, defaults: tuple[_ConfigurationDefaultContribution, ...]
+    ) -> tuple[tuple[_SourcePayload, ...], tuple[ConfigurationSourceDiagnostic, ...]]:
+        payloads = list(self._load_module_defaults(defaults))
+        diagnostics = [
+            _loaded_diagnostic(
+                ConfigurationSource.MODULE_DEFAULTS,
+                _source_location(ConfigurationSource.MODULE_DEFAULTS),
+            )
+        ]
+
+        self._append_optional_yaml(
+            payloads,
+            diagnostics,
+            ConfigurationSource.YAML_BASE,
+            self._base_path / "app.yaml",
+        )
+        self._append_optional_yaml(
+            payloads,
+            diagnostics,
+            ConfigurationSource.YAML_ENVIRONMENT,
+            self._base_path / f"app.{self._environment}.yaml",
+        )
+
+        explicit_preview = _normalize_with_boundary(
+            ConfigurationSource.EXPLICIT,
+            _source_location(ConfigurationSource.EXPLICIT),
+            self._explicit_overrides,
+        )
+        # 原生来源各读取一次。后续 Module 声明只能绑定此次输入快照。
+        try:
+            environment_source = _SnapshotEnvSource(
+                _NativeConfigurationSettings,
+                env_prefix=self._env_prefix,
+                env_nested_delimiter=_ENVIRONMENT_NESTED_DELIMITER,
+            )
+        except Exception as original_error:
+            _raise_source_error(
+                ConfigurationSource.OS_ENVIRONMENT,
+                _source_location(ConfigurationSource.OS_ENVIRONMENT),
+                original_error,
+            )
+        dotenv_source, dotenv_diagnostic = self._prepare_dotenv()
+        env_names = tuple(environment_source.env_vars)
+        dotenv_names = tuple(dotenv_source.env_vars) if dotenv_source is not None else ()
+        try:
+            sections = _input_sections((*env_names, *dotenv_names), self._env_prefix)
+        except (TypeError, ValueError) as original_error:
+            _raise_source_error(
+                ConfigurationSource.OS_ENVIRONMENT,
+                _source_location(ConfigurationSource.OS_ENVIRONMENT),
+                original_error,
+            )
+        settings_type = _build_settings_type(
+            payloads=tuple(payloads),
+            explicit_preview=explicit_preview,
+            known_sections=sections,
+        )
+        diagnostics.append(dotenv_diagnostic)
+        if dotenv_source is not None:
+            dotenv_source.settings_cls = settings_type
+            _validate_prefixed_names(
+                dotenv_names,
+                settings_type=settings_type,
+                env_prefix=self._env_prefix,
+                source_id=ConfigurationSource.DOTENV,
+                location=dotenv_diagnostic.location,
+            )
+            payloads.extend(
+                _environment_payloads(
+                    ConfigurationSource.DOTENV, dotenv_diagnostic.location, dotenv_source
+                )
+            )
+
+        environment_payload = self._load_environment(settings_type, environment_source)
+        diagnostics.append(
+            _loaded_diagnostic(
+                ConfigurationSource.OS_ENVIRONMENT,
+                _source_location(ConfigurationSource.OS_ENVIRONMENT),
+            )
+        )
+        payloads.extend(environment_payload)
+
+        cli_location = _source_location(ConfigurationSource.CLI)
+        try:
+            cli_source: CliSettingsSource[BaseSettings] = CliSettingsSource(
+                _cli_settings_type(self._cli_args),
+                cli_parse_args=self._cli_args,
+                cli_exit_on_error=False,
+            )
+        except Exception as original_error:
+            _raise_source_error(ConfigurationSource.CLI, cli_location, original_error)
+        payloads.append(
+            _SourcePayload(
+                ConfigurationSource.CLI,
+                cli_location,
+                _call_native_source(ConfigurationSource.CLI, cli_location, cli_source),
+            )
+        )
+        diagnostics.append(_loaded_diagnostic(ConfigurationSource.CLI, cli_location))
+        explicit_payload = self._load_explicit(settings_type)
+        diagnostics.append(
+            _loaded_diagnostic(ConfigurationSource.EXPLICIT, explicit_payload.location)
+        )
+        payloads.append(explicit_payload)
+        return tuple(payloads), tuple(diagnostics)
+
+    @staticmethod
+    def _load_module_defaults(
+        defaults: tuple[_ConfigurationDefaultContribution, ...],
+    ) -> tuple[_SourcePayload, ...]:
+        payloads: list[_SourcePayload] = []
+        for contribution in defaults:
+            try:
+                _validate_immutable_module_default(contribution.values)
+            except (TypeError, ValueError) as original_error:
+                _raise_source_error(
+                    ConfigurationSource.MODULE_DEFAULTS,
+                    contribution.source_location,
+                    original_error,
+                )
+            values = _normalize_with_boundary(
+                ConfigurationSource.MODULE_DEFAULTS,
+                contribution.source_location,
+                contribution.values,
+            )
+            payloads.append(
+                _SourcePayload(
+                    source=ConfigurationSource.MODULE_DEFAULTS,
+                    location=contribution.source_location,
+                    values=values,
+                )
+            )
+        return tuple(payloads)
+
+    @staticmethod
+    def _append_optional_yaml(
+        payloads: list[_SourcePayload],
+        diagnostics: list[ConfigurationSourceDiagnostic],
+        source_id: ConfigurationSource,
+        path: Path,
+    ) -> None:
+        payload, diagnostic = _load_optional_yaml(source_id, path)
+        diagnostics.append(diagnostic)
+        if payload is not None:
+            payloads.append(payload)
+
+    def _prepare_dotenv(self) -> tuple[_SnapshotDotEnvSource | None, ConfigurationSourceDiagnostic]:
+        path, required, skipped_reason = self._select_dotenv()
+        source_id = ConfigurationSource.DOTENV
+        location = _source_location(source_id, file=path)
+        if path is None:
+            return None, _skipped_diagnostic(source_id, location, skipped_reason or "disabled")
+        if not path.exists():
+            if required:
+                _raise_source_error(source_id, location, FileNotFoundError())
+            return None, _skipped_diagnostic(source_id, location, "optional_missing")
+        try:
+            if not path.is_file():
+                raise ValueError("dotenv path must be a file")
+            source = _SnapshotDotEnvSource(
+                _NativeConfigurationSettings,
+                env_file=path,
+                env_file_encoding="utf-8",
+                dotenv_filtering="match_prefix",
+                env_prefix=self._env_prefix,
+                env_nested_delimiter=_ENVIRONMENT_NESTED_DELIMITER,
+            )
+        except ConfigurationSourceError:
+            raise
+        except Exception as original_error:
+            _raise_source_error(source_id, location, original_error)
+        return source, _loaded_diagnostic(source_id, location)
+
+    def _select_dotenv(self) -> tuple[Path | None, bool, str | None]:
+        if self._dotenv_path is not None:
+            return self._dotenv_path, True, None
+        if self._environment.casefold() == "development":
+            return self._base_path / ".env", False, None
+        return None, False, "disabled_for_environment"
+
+    def _load_environment(
+        self,
+        settings_type: type[BaseSettings],
+        source: _LayeredEnvSource,
+    ) -> tuple[_SourcePayload, ...]:
+        source_id = ConfigurationSource.OS_ENVIRONMENT
+        location = _source_location(source_id)
+        source.settings_cls = settings_type
+        _validate_prefixed_names(
+            source.env_vars,
+            settings_type=settings_type,
+            env_prefix=self._env_prefix,
+            source_id=source_id,
+            location=location,
+        )
+        return _environment_payloads(source_id, location, source)
+
+    def _load_explicit(self, settings_type: type[BaseSettings]) -> _SourcePayload:
+        source_id = ConfigurationSource.EXPLICIT
+        location = _source_location(source_id)
+        try:
+            source = InitSettingsSource(settings_type, dict(self._explicit_overrides))
+        except Exception as original_error:
+            _raise_source_error(source_id, location, original_error)
+        return _SourcePayload(
+            source_id,
+            location,
+            _call_native_source(source_id, location, source),
+        )
+
+
+def _validate_immutable_module_default(value: object) -> None:
+    if isinstance(value, Mapping):
+        from types import MappingProxyType
+
+        if not isinstance(value, MappingProxyType):
+            raise TypeError("configuration_defaults mappings must be immutable MappingProxyType")
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise TypeError("configuration mapping keys must be strings")
+            _validate_immutable_module_default(item)
+        return
+    if isinstance(value, (tuple, frozenset)):
+        for item in value:
+            _validate_immutable_module_default(item)
+        return
+    if is_supported_scalar(value):
+        return
+    raise TypeError(f"configuration_defaults contains mutable or opaque {type(value).__name__}")
+
+
+def _load_optional_yaml(
+    source_id: ConfigurationSource,
+    path: Path,
+) -> tuple[_SourcePayload | None, ConfigurationSourceDiagnostic]:
+    location = _source_location(source_id, file=path)
+    if not path.exists():
+        return None, _skipped_diagnostic(source_id, location, "optional_missing")
+    if not path.is_file():
+        _raise_source_error(source_id, location, ValueError("configuration path is not a file"))
+    try:
+        source = _YamlConfigurationSource(_NativeConfigurationSettings, yaml_file=path)
+    except Exception as original_error:
+        _raise_source_error(source_id, location, original_error)
+    values = _call_native_source(source_id, location, source)
+    return _SourcePayload(source_id, location, values), _loaded_diagnostic(source_id, location)
+
+
+def _environment_payloads(
+    source_id: ConfigurationSource,
+    location: SourceLocation,
+    source: _LayeredEnvSource,
+) -> tuple[_SourcePayload, ...]:
+    # 同一次读取按嵌套深度保留覆盖层。原生 parser 仍负责解码；字段与数据键的
+    # 身份由晚声明的 Options 决定，不能在原生 deep_update 里提前覆盖或合并。
+    _call_native_source(source_id, location, source)
+    return tuple(
+        _SourcePayload(
+            source_id, location, _normalize_with_boundary(source_id, location, values), depth
+        )
+        for depth, values in sorted(source.input_layers.items())
+    )
+
+
+def _call_native_source(
+    source_id: ConfigurationSource,
+    location: SourceLocation,
+    source: PydanticBaseSettingsSource,
+) -> dict[str, object]:
+    # 第三方动态 Any 只存在于这个边界，返回前递归收窄为配置对象树。
+    try:
+        raw_values = source()
+    except Exception as original_error:
+        _raise_source_error(source_id, location, original_error)
+    return _normalize_with_boundary(source_id, location, raw_values)
+
+
+def _build_settings_type(
+    *,
+    payloads: tuple[_SourcePayload, ...],
+    explicit_preview: Mapping[str, object],
+    known_sections: frozenset[str],
+) -> type[BaseSettings]:
+    mapping_fields: set[str] = set()
+    scalar_fields: set[str] = set()
+    for payload in payloads:
+        _collect_field_shapes(payload.values, mapping_fields, scalar_fields)
+    _collect_field_shapes(explicit_preview, mapping_fields, scalar_fields)
+    for section in known_sections:
+        top_level = canonical_path(section)[0]
+        if top_level not in scalar_fields:
+            mapping_fields.add(top_level)
+
+    annotations: dict[str, object] = {
+        name: dict if name in mapping_fields else object
+        for name in sorted(mapping_fields | scalar_fields)
+    }
+    namespace: dict[str, object] = {
+        "__annotations__": annotations,
+        # 无 prefix dotenv key 由 native source 作为 extra 返回；ignore 只屏蔽这些变量。
+        "model_config": SettingsConfigDict(extra="ignore"),
+    }
+    return type(
+        "_ApplicationConfigurationSettings",
+        (_NativeConfigurationSettings,),
+        namespace,
+    )
+
+
+def _collect_field_shapes(
+    values: Mapping[str, object],
+    mapping_fields: set[str],
+    scalar_fields: set[str],
+) -> None:
+    for key, value in values.items():
+        if isinstance(value, Mapping):
+            mapping_fields.add(key)
+            scalar_fields.discard(key)
+        elif key not in mapping_fields:
+            scalar_fields.add(key)
+
+
+def _validate_prefixed_names(
+    env_names: Iterable[str],
+    *,
+    settings_type: type[BaseSettings],
+    env_prefix: str,
+    source_id: ConfigurationSource,
+    location: SourceLocation,
+) -> None:
+    prefix = env_prefix.casefold()
+    for raw_name in env_names:
+        normalized_name = raw_name.casefold()
+        if not normalized_name.startswith(prefix):
+            continue
+        relative = normalized_name[len(prefix) :]
+        raw_parts = relative.split(_ENVIRONMENT_NESTED_DELIMITER)
+        try:
+            parts = (canonical_segment(raw_parts[0]), *raw_parts[1:])
+            # 字段来自同一次环境输入快照；未知 section 在 Module 声明完成后统一校验。
+            field = settings_type.model_fields[parts[0]]
+            if (
+                len(parts) > 1
+                and field.annotation is not dict
+                and get_origin(field.annotation) is not dict
+            ):
+                raise ValueError(
+                    f"configuration key {parts[0]!r} does not accept nested environment keys"
+                )
+        except (IndexError, TypeError, ValueError) as original_error:
+            _raise_source_error(source_id, location, original_error)
+
+
+def _normalize_with_boundary(
+    source_id: ConfigurationSource,
+    location: SourceLocation,
+    values: object,
+) -> dict[str, object]:
+    try:
+        if not isinstance(values, Mapping):
+            raise TypeError("configuration source must return a mapping")
+        return _capture_input_mapping(cast(Mapping[str, object], values))
+    except (TypeError, ValueError) as original_error:
+        _raise_source_error(source_id, location, original_error)
+
+
+def _source_location(
+    source: ConfigurationSource,
+    *,
+    file: Path | None = None,
+) -> SourceLocation:
+    return SourceLocation(
+        owner=source.value,
+        file=str(file) if file is not None else None,
+        line=None,
+        symbol=None,
+    )
+
+
+def _loaded_diagnostic(
+    source: ConfigurationSource,
+    location: SourceLocation,
+) -> ConfigurationSourceDiagnostic:
+    return ConfigurationSourceDiagnostic(
+        source=source,
+        status=ConfigurationSourceStatus.LOADED,
+        location=location,
+    )
+
+
+def _skipped_diagnostic(
+    source: ConfigurationSource,
+    location: SourceLocation,
+    reason: str,
+) -> ConfigurationSourceDiagnostic:
+    return ConfigurationSourceDiagnostic(
+        source=source,
+        status=ConfigurationSourceStatus.SKIPPED,
+        location=location,
+        reason=reason,
+    )
+
+
+def _raise_source_error(
+    source: ConfigurationSource,
+    location: SourceLocation,
+    original_error: BaseException,
+) -> NoReturn:
+    error = ConfigurationSourceError(
+        source_id=source.value,
+        location=location,
+        original_error=original_error,
+    )
+    raise error from original_error