python-platform 0.1.1__py3-none-any.whl

python_platform/options/aliases.py

@@ -0,0 +1,331 @@
+"""多来源 Options input alias 的确定性优先级裁决。"""
+
+from __future__ import annotations
+
+import types
+from collections.abc import Mapping, MutableMapping
+from typing import Annotated, Literal, Union, cast, get_args, get_origin
+
+from pydantic import BaseModel
+
+from ..configuration.merge import _source_ordinal
+from ..configuration.root import ConfigurationRoot
+from ..configuration.values import canonical_path
+from .models import MISSING, _OptionPatch
+from .schema import (
+    _annotation_discriminator,
+    _direct_model_types,
+    _field_validation_paths,
+    _model_annotation,
+)
+
+
+def _prefer_higher_priority_alias_inputs(
+    model_type: type[BaseModel],
+    input_value: object,
+    *,
+    configuration: ConfigurationRoot,
+    section: str,
+    patches: tuple[_OptionPatch, ...],
+) -> None:
+    if not isinstance(input_value, MutableMapping):
+        return
+    _prefer_model_alias_inputs(
+        model_type,
+        cast(MutableMapping[str, object], input_value),
+        root_model_type=model_type,
+        prefix=(),
+        configuration=configuration,
+        section=section,
+        patches=patches,
+    )
+
+
+def _prefer_model_alias_inputs(
+    model_type: type[BaseModel],
+    values: MutableMapping[str, object],
+    *,
+    root_model_type: type[BaseModel],
+    prefix: tuple[str, ...],
+    configuration: ConfigurationRoot,
+    section: str,
+    patches: tuple[_OptionPatch, ...],
+) -> None:
+    for field_name, field in model_type.model_fields.items():
+        paths = _field_validation_paths(model_type, field_name, field)
+        present: list[tuple[int, tuple[str, ...], object]] = []
+        for index, path in enumerate(paths):
+            value = _lookup_input_path(values, path)
+            if value is not MISSING:
+                present.append((index, path, value))
+        if not present:
+            continue
+
+        winner = max(
+            present,
+            key=lambda item: (
+                *_input_path_rank(
+                    (*prefix, *item[1]),
+                    root_model_type=root_model_type,
+                    configuration=configuration,
+                    section=section,
+                    patches=patches,
+                ),
+                -item[0],
+            ),
+        )
+        for candidate in present:
+            if candidate is not winner:
+                _delete_input_path(values, candidate[1])
+
+        _prefer_annotation_alias_inputs(
+            field.annotation,
+            winner[2],
+            discriminator=field.discriminator,
+            root_model_type=root_model_type,
+            prefix=(*prefix, *winner[1]),
+            configuration=configuration,
+            section=section,
+            patches=patches,
+        )
+
+
+def _prefer_annotation_alias_inputs(
+    annotation: object,
+    value: object,
+    *,
+    discriminator: object,
+    root_model_type: type[BaseModel],
+    prefix: tuple[str, ...],
+    configuration: ConfigurationRoot,
+    section: str,
+    patches: tuple[_OptionPatch, ...],
+) -> None:
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        arguments = get_args(annotation)
+        if arguments:
+            _prefer_annotation_alias_inputs(
+                arguments[0],
+                value,
+                discriminator=discriminator or _annotation_discriminator(annotation),
+                root_model_type=root_model_type,
+                prefix=prefix,
+                configuration=configuration,
+                section=section,
+                patches=patches,
+            )
+        return
+
+    model_type = _model_annotation(annotation)
+    if model_type is not None:
+        if isinstance(value, MutableMapping):
+            _prefer_model_alias_inputs(
+                model_type,
+                cast(MutableMapping[str, object], value),
+                root_model_type=root_model_type,
+                prefix=prefix,
+                configuration=configuration,
+                section=section,
+                patches=patches,
+            )
+        return
+
+    if origin in (Union, types.UnionType):
+        _prefer_union_alias_inputs(
+            annotation,
+            value,
+            discriminator=discriminator,
+            root_model_type=root_model_type,
+            prefix=prefix,
+            configuration=configuration,
+            section=section,
+            patches=patches,
+        )
+        return
+
+    _prefer_container_alias_inputs(
+        origin,
+        get_args(annotation),
+        value,
+        root_model_type=root_model_type,
+        prefix=prefix,
+        configuration=configuration,
+        section=section,
+        patches=patches,
+    )
+
+
+def _prefer_union_alias_inputs(
+    annotation: object,
+    value: object,
+    *,
+    discriminator: object,
+    root_model_type: type[BaseModel],
+    prefix: tuple[str, ...],
+    configuration: ConfigurationRoot,
+    section: str,
+    patches: tuple[_OptionPatch, ...],
+) -> None:
+    model_choices = _direct_model_types(annotation)
+    selected: type[BaseModel] | None = None
+    if len(model_choices) == 1:
+        selected = model_choices[0]
+    elif isinstance(discriminator, str) and isinstance(value, Mapping):
+        selected = _select_discriminated_model(model_choices, value, discriminator)
+    if selected is not None and isinstance(value, MutableMapping):
+        _prefer_model_alias_inputs(
+            selected,
+            cast(MutableMapping[str, object], value),
+            root_model_type=root_model_type,
+            prefix=prefix,
+            configuration=configuration,
+            section=section,
+            patches=patches,
+        )
+
+
+def _prefer_container_alias_inputs(
+    origin: object,
+    arguments: tuple[object, ...],
+    value: object,
+    *,
+    root_model_type: type[BaseModel],
+    prefix: tuple[str, ...],
+    configuration: ConfigurationRoot,
+    section: str,
+    patches: tuple[_OptionPatch, ...],
+) -> None:
+    if origin is Mapping and len(arguments) == 2 and isinstance(value, Mapping):
+        value_annotation = arguments[1]
+        for key, item in value.items():
+            if isinstance(key, str):
+                _prefer_annotation_alias_inputs(
+                    value_annotation,
+                    item,
+                    discriminator=None,
+                    root_model_type=root_model_type,
+                    prefix=(*prefix, key),
+                    configuration=configuration,
+                    section=section,
+                    patches=patches,
+                )
+        return
+    if origin in (tuple, frozenset) and isinstance(value, (list, tuple, frozenset)):
+        for index, item in enumerate(value):
+            item_annotation = _sequence_item_annotation(arguments, index)
+            if item_annotation is not None:
+                _prefer_annotation_alias_inputs(
+                    item_annotation,
+                    item,
+                    discriminator=None,
+                    root_model_type=root_model_type,
+                    prefix=(*prefix, str(index)),
+                    configuration=configuration,
+                    section=section,
+                    patches=patches,
+                )
+
+
+def _select_discriminated_model(
+    model_choices: tuple[type[BaseModel], ...],
+    values: Mapping[str, object],
+    discriminator: str,
+) -> type[BaseModel] | None:
+    for model_type in model_choices:
+        field = model_type.model_fields.get(discriminator)
+        if field is None:
+            continue
+        tag = MISSING
+        for path in _field_validation_paths(model_type, discriminator, field):
+            tag = _lookup_input_path(values, path)
+            if tag is not MISSING:
+                break
+        if tag is not MISSING and tag in _literal_values(field.annotation):
+            return model_type
+    return None
+
+
+def _literal_values(annotation: object) -> tuple[object, ...]:
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        arguments = get_args(annotation)
+        return _literal_values(arguments[0]) if arguments else ()
+    if origin is Literal:
+        return get_args(annotation)
+    return ()
+
+
+def _sequence_item_annotation(
+    arguments: tuple[object, ...],
+    index: int,
+) -> object | None:
+    if not arguments:
+        return None
+    if len(arguments) == 2 and arguments[1] is Ellipsis:
+        return arguments[0]
+    if index < len(arguments):
+        return arguments[index]
+    return None
+
+
+def _input_path_rank(
+    relative_path: tuple[str, ...],
+    *,
+    root_model_type: type[BaseModel],
+    configuration: ConfigurationRoot,
+    section: str,
+    patches: tuple[_OptionPatch, ...],
+) -> tuple[int, int]:
+    patch_rank = -1
+    for index, patch in enumerate(patches):
+        if patch.model_type is root_model_type and _patch_affects_path(
+            relative_path,
+            patch.field_paths,
+        ):
+            patch_rank = index
+    if patch_rank >= 0:
+        return (1, patch_rank)
+
+    full_parts = (*canonical_path(section), *relative_path)
+    for length in range(len(full_parts), 0, -1):
+        try:
+            provenance = configuration._provenance_at(full_parts[:length])
+        except (KeyError, ValueError):
+            continue
+        return (0, _source_ordinal(provenance.effective_source.source_id))
+    return (-1, -1)
+
+
+def _lookup_input_path(
+    values: Mapping[str, object],
+    path: tuple[str, ...],
+) -> object:
+    current: object = values
+    for part in path:
+        if not isinstance(current, Mapping) or part not in current:
+            return MISSING
+        current = current[part]
+    return current
+
+
+def _delete_input_path(
+    values: MutableMapping[str, object],
+    path: tuple[str, ...],
+) -> None:
+    current: object = values
+    for part in path[:-1]:
+        if not isinstance(current, MutableMapping) or part not in current:
+            return
+        current = current[part]
+    if isinstance(current, MutableMapping):
+        current.pop(path[-1], None)
+
+
+def _patch_affects_path(path: tuple[str, ...], candidates: frozenset[tuple[str, ...]]) -> bool:
+    if not path:
+        return bool(candidates)
+    return any(
+        path[: len(candidate)] == candidate or candidate[: len(path)] == path
+        for candidate in candidates
+    )

python_platform/options/contribution.py

@@ -0,0 +1,62 @@
+"""限定到当前 lifecycle invocation 的声明与程序覆盖入口。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING
+
+from ..diagnostics import LifecycleStage
+from ..errors import OptionsContributionClosedError
+from ..modularity import ModuleDescriptor
+from .models import TOptions
+
+if TYPE_CHECKING:
+    from .registry import _OptionsRegistry
+
+
+class _OptionsContributor:
+    __slots__ = ("_active", "_kind", "_owner", "_registry", "_stage")
+
+    def __init__(
+        self,
+        registry: _OptionsRegistry,
+        *,
+        owner: ModuleDescriptor,
+        stage: LifecycleStage,
+        kind: str,
+    ) -> None:
+        self._registry = registry
+        self._owner = owner
+        self._stage = stage
+        self._kind = kind
+        self._active = True
+
+    def __call__(
+        self,
+        model_type: type[TOptions],
+        *,
+        section: str | None = None,
+        values: Mapping[str, object] | None = None,
+        secret_paths: frozenset[str] = frozenset(),
+        reason: str | None = None,
+    ) -> None:
+        if not self._active:
+            raise OptionsContributionClosedError(option_kind=self._kind, stage=self._stage.value)
+        if section is None and (values is None or secret_paths):
+            raise ValueError("Options requires a section declaration or values contribution")
+        if section is not None:
+            self._registry.declare(
+                model_type,
+                section,
+                secret_paths=secret_paths,
+                owner=self._owner,
+                stage=self._stage,
+                reason=reason,
+            )
+        if values is not None:
+            self._registry.patch(
+                model_type, values, owner=self._owner, stage=self._stage, reason=reason
+            )
+
+    def _close(self) -> None:
+        self._active = False

python_platform/options/immutability.py

@@ -0,0 +1,48 @@
+"""Options patch 的独立容器副本；不向贡献者暴露已发布 snapshot 的可变引用。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import cast
+
+
+def _merge_patch_input(base: object, patch: Mapping[str, object]) -> dict[str, object]:
+    merged = {} if not isinstance(base, Mapping) else cast(dict[str, object], _thaw_value(base))
+    _merge_mapping_values(merged, patch)
+    return merged
+
+
+def _merge_mapping_values(
+    target: dict[str, object],
+    incoming: Mapping[str, object],
+) -> None:
+    for key, value in incoming.items():
+        current = target.get(key)
+        if isinstance(current, dict) and isinstance(value, Mapping):
+            _merge_mapping_values(current, value)
+        else:
+            target[key] = _thaw_value(value)
+
+
+def _thaw_value(value: object) -> object:
+    if isinstance(value, Mapping):
+        return {key: _thaw_value(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return tuple(_thaw_value(item) for item in value)
+    if isinstance(value, frozenset):
+        return frozenset(_thaw_value(item) for item in value)
+    return value
+
+
+def _mapping_paths(
+    values: Mapping[str, object],
+    prefix: tuple[str, ...] = (),
+) -> set[tuple[str, ...]]:
+    paths: set[tuple[str, ...]] = set()
+    for key, value in values.items():
+        current = (*prefix, key)
+        if isinstance(value, Mapping) and value:
+            paths.update(_mapping_paths(value, current))
+        else:
+            paths.add(current)
+    return paths

python_platform/options/input_keys.py

@@ -0,0 +1,214 @@
+"""沿有限输入和正式 typing 解释 Mapping 边界；分支路径不跨 Union 共享。"""
+
+from __future__ import annotations
+
+import types
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Annotated, Union, get_args, get_origin
+
+from pydantic import BaseModel
+
+from ..configuration.values import MISSING, canonical_segment
+from .aliases import _literal_values, _sequence_item_annotation
+from .schema import _annotation_discriminator, _direct_model_types, _field_validation_paths
+
+
+@dataclass(frozen=True)
+class _InputReference:
+    """只读来源层视图；字段按 canonical 查找，数据键按原名查找。"""
+
+    layers: tuple[object, ...]
+
+    def child(self, key: str, *, field: bool) -> object:
+        found: list[object] = []
+        for layer in self.layers:
+            if not isinstance(layer, Mapping):
+                found.clear()
+                continue
+            values = _field_view(layer) if field else layer
+            if key in values:
+                child = values[key]
+                if not isinstance(child, Mapping):
+                    found.clear()
+                found.append(child)
+        if not found:
+            return MISSING
+        return _InputReference(tuple(found)) if isinstance(found[-1], Mapping) else found[-1]
+
+
+def _mapping_input_paths(
+    model_type: type[BaseModel], value: object, reference: object, selected: object = None
+) -> frozenset[tuple[str | int | None, ...]]:
+    paths: set[tuple[str | int | None, ...]] = set()
+    _visit(model_type, value, reference, (), paths, selected=selected)
+    return frozenset(paths)
+
+
+def _visit(
+    annotation: object,
+    value: object,
+    reference: object,
+    prefix: tuple[str | int | None, ...],
+    paths: set[tuple[str | int | None, ...]],
+    discriminator: object = None,
+    selected: object = None,
+) -> None:
+    origin, args = get_origin(annotation), get_args(annotation)
+    if origin is Annotated:
+        _visit(
+            args[0],
+            value,
+            reference,
+            prefix,
+            paths,
+            discriminator or _annotation_discriminator(annotation),
+            selected,
+        )
+    elif origin in (Union, types.UnionType):
+        _visit_union(annotation, value, reference, prefix, paths, discriminator, selected)
+    elif origin in (Mapping, dict) and isinstance(value, Mapping):
+        paths.add(prefix)
+        for key, child in value.items():
+            hint = (
+                reference.child(key, field=False)
+                if isinstance(reference, _InputReference)
+                else reference.get(key, child)
+                if isinstance(reference, Mapping)
+                else child
+            )
+            choice = selected.get(key) if isinstance(selected, Mapping) else None
+            _visit(args[1], child, hint, (*prefix, key), paths, selected=choice)
+    elif isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        _visit_fields(annotation, value, reference, prefix, paths, selected)
+    elif origin in (tuple, frozenset, list, set) and isinstance(value, (tuple, list, frozenset)):
+        for index, child in enumerate(value):
+            item = _sequence_item_annotation(args, index)
+            hint = (
+                reference[index]
+                if isinstance(reference, (tuple, list)) and index < len(reference)
+                else child
+            )
+            if item is not None:
+                choice = (
+                    selected[index]
+                    if isinstance(selected, tuple) and index < len(selected)
+                    else None
+                )
+                _visit(item, child, hint, (*prefix, index), paths, selected=choice)
+
+
+def _visit_union(
+    annotation: object,
+    value: object,
+    reference: object,
+    prefix: tuple[str | int | None, ...],
+    paths: set[tuple[str | int | None, ...]],
+    discriminator: object,
+    selected: object,
+) -> None:
+    choices = _direct_model_types(annotation)
+    if isinstance(discriminator, str) and isinstance(reference, (Mapping, _InputReference)):
+        # 只解释标签所属的分支，不在绑定前执行用户 validator 或替代原生 Union 校验。
+        branch_type = _select_input_model(choices, reference, discriminator)
+        if branch_type is not None:
+            _visit(branch_type, value, reference, prefix, paths, selected=selected)
+        return
+    if isinstance(selected, BaseModel) and type(selected) in choices:
+        _visit(type(selected), value, reference, prefix, paths, selected=selected)
+        return
+    branch_paths = []
+    for item in get_args(annotation):
+        if item is type(None) or (isinstance(value, Mapping) and item in (str, int, float, bool)):
+            continue
+        branch: set[tuple[str | int | None, ...]] = set()
+        _visit(item, value, reference, prefix, branch)
+        branch_paths.append(branch)
+    if branch_paths:
+        if all(branch == branch_paths[0] for branch in branch_paths):
+            paths.update(branch_paths[0])
+        else:
+            # 未标记 Union 的选择归原生 validator。暂时保留每一层原始输入键，
+            # 各候选模型在自己的原生验证入口归一化，成功后按实际选择发布 Configuration。
+            _preserve_mapping_paths(value, prefix, paths)
+
+
+def _preserve_mapping_paths(
+    value: object,
+    prefix: tuple[str | int | None, ...],
+    paths: set[tuple[str | int | None, ...]],
+) -> None:
+    if isinstance(value, Mapping):
+        paths.add(prefix)
+        for key, child in value.items():
+            _preserve_mapping_paths(child, (*prefix, key), paths)
+    elif isinstance(value, (tuple, list)):
+        for index, child in enumerate(value):
+            _preserve_mapping_paths(child, (*prefix, index), paths)
+
+
+def _select_input_model(
+    choices: tuple[type[BaseModel], ...],
+    reference: object,
+    discriminator: str,
+) -> type[BaseModel] | None:
+    for model in choices:
+        field = model.model_fields[discriminator]
+        for path in _field_validation_paths(model, discriminator, field):
+            tag = _field_at(reference, path)
+            if tag is not MISSING:
+                if tag in _literal_values(field.annotation):
+                    return model
+                break
+    return None
+
+
+def _field_view(value: Mapping[object, object]) -> dict[str, object]:
+    fields: dict[str, object] = {}
+    for key, child in value.items():
+        try:
+            name = canonical_segment(key)
+        except (TypeError, ValueError):
+            # 此时可能仍在枚举 Union 候选；其他分支的数据键不是当前模型字段。
+            # 真正选用模型时由 normalize_mapping 拒绝无效字段，不在探测路径时裁决。
+            continue
+        fields[name] = child
+    return fields
+
+
+def _field_at(value: object, path: tuple[str, ...]) -> object:
+    for segment in path:
+        if isinstance(value, _InputReference):
+            value = value.child(segment, field=True)
+        elif isinstance(value, Mapping):
+            value = _field_view(value).get(segment, MISSING)
+        else:
+            return MISSING
+    return value
+
+
+def _visit_fields(
+    model: type[BaseModel],
+    value: object,
+    reference: object,
+    prefix: tuple[str | int | None, ...],
+    paths: set[tuple[str | int | None, ...]],
+    selected: object,
+) -> None:
+    if not isinstance(value, Mapping):
+        return
+    # 递归的终点是输入叶子；再次遇到同一模型类型不代表再次遇到同一输入节点。
+    for name, field in model.model_fields.items():
+        for path in _field_validation_paths(model, name, field):
+            child = _field_at(value, path)
+            if child is not MISSING:
+                hint = _field_at(reference, path)
+                _visit(
+                    field.annotation,
+                    child,
+                    child if hint is MISSING else hint,
+                    (*prefix, *path),
+                    paths,
+                    field.discriminator,
+                    getattr(selected, name) if isinstance(selected, model) else None,
+                )