python-platform 0.1.1__py3-none-any.whl

python_platform/options/schema.py

@@ -0,0 +1,488 @@
+"""Options model schema、alias path 与 secret path contract validation。"""
+
+from __future__ import annotations
+
+import types
+from collections.abc import Mapping, MutableMapping, MutableSequence, MutableSet
+from typing import Annotated, Any, Literal, Union, cast, get_args, get_origin
+
+from pydantic import AliasChoices, AliasPath, BaseModel, Secret, SecretBytes, SecretStr
+from pydantic.fields import FieldInfo
+from pydantic_settings import BaseSettings
+
+from ..configuration.values import canonical_path
+from ..errors import InvalidOptionDefinitionError
+from ..modularity import ModuleDescriptor
+from .models import _OptionDefinition
+
+_MUTABLE_ANNOTATION_ORIGINS = (
+    list,
+    dict,
+    set,
+    MutableMapping,
+    MutableSequence,
+    MutableSet,
+)
+
+
+def _validate_definition(
+    candidate: _OptionDefinition[BaseModel],
+    *,
+    owner: ModuleDescriptor,
+    kind: str,
+) -> _OptionDefinition[BaseModel]:
+    model_type = candidate.model_type
+    if not isinstance(model_type, type) or not issubclass(model_type, BaseModel):
+        raise InvalidOptionDefinitionError(
+            owner=owner.key,
+            model_type=None,
+            option_kind=kind,
+            reason="model_type must be a Pydantic BaseModel class",
+        )
+    try:
+        section = ".".join(canonical_path(candidate.section))
+        if not isinstance(candidate.secret_paths, frozenset):
+            raise TypeError("secret_paths must be frozenset")
+        _validate_model_schema(model_type, seen=set())
+        expanded_secret_paths: set[tuple[str, ...]] = set()
+        for secret_path in candidate.secret_paths:
+            expanded_secret_paths.update(
+                _expand_declared_secret_path(
+                    model_type,
+                    canonical_path(secret_path),
+                )
+            )
+        secret_paths = frozenset(".".join(path) for path in expanded_secret_paths)
+    except (TypeError, ValueError) as original_error:
+        raise InvalidOptionDefinitionError(
+            owner=owner.key,
+            model_type=model_type,
+            option_kind=kind,
+            reason=str(original_error),
+        ) from original_error
+    return _OptionDefinition(
+        model_type=model_type,
+        section=section,
+        secret_paths=secret_paths,
+    )
+
+
+def _validate_model_schema(
+    model_type: type[BaseModel],
+    *,
+    seen: set[type[BaseModel]],
+) -> None:
+    if model_type in seen:
+        return
+    seen.add(model_type)
+    # 在绑定及任何 default factory 运行前检查完整模型图，嵌套模型也不能另读配置源。
+    if issubclass(model_type, BaseSettings):
+        raise ValueError("Options must not load independent settings sources")
+    if model_type.model_config.get("frozen") is not True:
+        raise ValueError(f"nested model {model_type.__qualname__} must set frozen=True")
+    if model_type.model_config.get("validate_default") is not True:
+        raise ValueError(f"nested model {model_type.__qualname__} must set validate_default=True")
+    if model_type.__private_attributes__:
+        # Pydantic frozen 不阻止 PrivateAttr 重新赋值，发布 snapshot 时不能接受它。
+        raise ValueError(
+            f"model {model_type.__qualname__} must not declare mutable private attributes"
+        )
+    if model_type.model_config.get("extra") == "allow":
+        raise ValueError(f"model {model_type.__qualname__} must not allow mutable extra fields")
+    validation_paths: dict[str, tuple[tuple[str, ...], ...]] = {}
+    for field_name, field in model_type.model_fields.items():
+        if _canonical_path_part(field_name) != field_name:
+            raise ValueError(f"field name {field_name!r} must already be canonical snake_case")
+        _validate_field_aliases(field)
+        validation_paths[field_name] = _field_validation_paths(
+            model_type,
+            field_name,
+            field,
+        )
+        _validate_annotation(
+            field.annotation,
+            path=f"{model_type.__qualname__}.{field_name}",
+            seen=seen,
+            discriminator=field.discriminator,
+        )
+    _validate_model_input_paths(model_type, validation_paths)
+
+
+def _validate_annotation(
+    annotation: object,
+    *,
+    path: str,
+    seen: set[type[BaseModel]],
+    discriminator: object = None,
+) -> None:
+    if annotation in (Any, object):
+        raise TypeError(f"{path} must not use Any/object")
+    origin = get_origin(annotation)
+    if _is_mutable_annotation(annotation, origin):
+        raise TypeError(f"{path} uses a mutable container annotation")
+    if origin is Annotated:
+        annotated = get_args(annotation)
+        if annotated:
+            _validate_annotation(
+                annotated[0],
+                path=path,
+                seen=seen,
+                discriminator=discriminator or _annotation_discriminator(annotation),
+            )
+        return
+    if origin in (Union, types.UnionType):
+        model_choices = _direct_model_types(annotation)
+        if (
+            len(model_choices) > 1
+            and any(
+                _model_contains_competing_aliases(model_choice, seen=set())
+                for model_choice in model_choices
+            )
+            and not isinstance(discriminator, str)
+        ):
+            raise TypeError(
+                f"{path} must use a string discriminator when union branches contain "
+                "competing validation aliases"
+            )
+        _validate_annotation_arguments(get_args(annotation), path=path, seen=seen)
+        return
+    if origin is Literal:
+        return
+    model_type = _model_annotation(annotation)
+    if model_type is not None:
+        _validate_model_schema(model_type, seen=seen)
+        return
+    _validate_annotation_arguments(get_args(annotation), path=path, seen=seen)
+
+
+def _validate_annotation_arguments(
+    arguments: tuple[object, ...],
+    *,
+    path: str,
+    seen: set[type[BaseModel]],
+) -> None:
+    for argument in arguments:
+        if argument is not Ellipsis:
+            _validate_annotation(argument, path=path, seen=seen)
+
+
+def _is_mutable_annotation(annotation: object, origin: object) -> bool:
+    return annotation in _MUTABLE_ANNOTATION_ORIGINS or origin in _MUTABLE_ANNOTATION_ORIGINS
+
+
+def _model_annotation(annotation: object) -> type[BaseModel] | None:
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return annotation
+    return None
+
+
+def _direct_model_types(annotation: object) -> tuple[type[BaseModel], ...]:
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        arguments = get_args(annotation)
+        return _direct_model_types(arguments[0]) if arguments else ()
+    if origin in (Union, types.UnionType):
+        models: list[type[BaseModel]] = []
+        for argument in get_args(annotation):
+            model_type = _model_annotation(argument)
+            if model_type is not None and model_type not in models:
+                models.append(model_type)
+        return tuple(models)
+    model_type = _model_annotation(annotation)
+    return (model_type,) if model_type is not None else ()
+
+
+def _annotation_discriminator(annotation: object) -> object:
+    if get_origin(annotation) is not Annotated:
+        return None
+    for metadata in get_args(annotation)[1:]:
+        if isinstance(metadata, FieldInfo) and metadata.discriminator is not None:
+            return metadata.discriminator
+    return None
+
+
+def _model_contains_competing_aliases(
+    model_type: type[BaseModel],
+    *,
+    seen: set[type[BaseModel]],
+) -> bool:
+    if model_type in seen:
+        return False
+    branch_seen = {*seen, model_type}
+    for field_name, field in model_type.model_fields.items():
+        if len(_field_validation_paths(model_type, field_name, field)) > 1:
+            return True
+        if _annotation_contains_competing_aliases(field.annotation, seen=branch_seen):
+            return True
+    return False
+
+
+def _annotation_contains_competing_aliases(
+    annotation: object,
+    *,
+    seen: set[type[BaseModel]],
+) -> bool:
+    model_type = _model_annotation(annotation)
+    if model_type is not None:
+        return _model_contains_competing_aliases(model_type, seen=seen)
+    return any(
+        _annotation_contains_competing_aliases(argument, seen=seen)
+        for argument in get_args(annotation)
+        if argument is not Ellipsis
+    )
+
+
+def _definition_secret_paths(definition: _OptionDefinition[BaseModel]) -> frozenset[str]:
+    paths = set(definition.secret_paths)
+    paths.update(_model_secret_paths(definition.model_type, prefix=(), seen=set()))
+    return frozenset(paths)
+
+
+def _model_secret_paths(
+    model_type: type[BaseModel],
+    *,
+    prefix: tuple[str, ...],
+    seen: set[type[BaseModel]],
+) -> set[str]:
+    if model_type in seen:
+        return set()
+    branch_seen = {*seen, model_type}
+    paths: set[str] = set()
+    for field_name, field in model_type.model_fields.items():
+        field_paths = tuple(
+            (*prefix, *relative_path) for relative_path in _field_input_paths(field_name, field)
+        )
+        if _annotation_contains_secret(
+            field.annotation
+        ) or _annotation_has_secret_in_dynamic_mapping(field.annotation):
+            paths.update(".".join(field_path) for field_path in field_paths)
+        for nested_type in _nested_model_types(field.annotation):
+            for field_path in field_paths:
+                if nested_type in branch_seen:
+                    # 递归 model 深度无上限，递归入口整体脱敏才是 fail-safe。
+                    paths.add(".".join(field_path))
+                else:
+                    paths.update(
+                        _model_secret_paths(
+                            nested_type,
+                            prefix=field_path,
+                            seen=branch_seen,
+                        )
+                    )
+    return paths
+
+
+def _expand_declared_secret_path(
+    model_type: type[BaseModel],
+    path: tuple[str, ...],
+) -> set[tuple[str, ...]]:
+    expanded: set[tuple[str, ...]] = set()
+    for field_name, field in model_type.model_fields.items():
+        input_paths = _field_input_paths(field_name, field)
+        for input_path in input_paths:
+            if path[: len(input_path)] != input_path:
+                continue
+            remaining = path[len(input_path) :]
+            if not remaining:
+                expanded.update(input_paths)
+                continue
+            if _annotation_accepts_dynamic_mapping_path(field.annotation):
+                expanded.update((*candidate, *remaining) for candidate in input_paths)
+                continue
+            for nested_type in _nested_model_types(field.annotation):
+                try:
+                    nested_paths = _expand_declared_secret_path(nested_type, remaining)
+                except ValueError:
+                    continue
+                expanded.update(
+                    (*candidate, *nested_path)
+                    for candidate in input_paths
+                    for nested_path in nested_paths
+                )
+    if not expanded:
+        raise ValueError(
+            f"secret path {'.'.join(path)!r} does not resolve to an Options input field"
+        )
+    return expanded
+
+
+def _annotation_accepts_dynamic_mapping_path(annotation: object) -> bool:
+    origin = get_origin(annotation)
+    if origin is Mapping:
+        return True
+    if origin is Annotated:
+        arguments = get_args(annotation)
+        return bool(arguments) and _annotation_accepts_dynamic_mapping_path(arguments[0])
+    if origin in (Union, types.UnionType):
+        return any(_annotation_accepts_dynamic_mapping_path(item) for item in get_args(annotation))
+    return False
+
+
+def _field_input_paths(
+    field_name: str,
+    field: FieldInfo,
+) -> tuple[tuple[str, ...], ...]:
+    paths: set[tuple[str, ...]] = {(_canonical_path_part(field_name),)}
+    paths.update(_validation_alias_paths(field.validation_alias))
+    if isinstance(field.alias, str):
+        paths.update(_validation_alias_paths(field.alias))
+    return tuple(sorted(paths))
+
+
+def _field_validation_paths(
+    model_type: type[BaseModel],
+    field_name: str,
+    field: FieldInfo,
+) -> tuple[tuple[str, ...], ...]:
+    paths: list[tuple[str, ...]] = []
+    if model_type.model_config.get("validate_by_alias") is not False:
+        validation_alias = field.validation_alias
+        if validation_alias is None and isinstance(field.alias, str):
+            validation_alias = field.alias
+        for path in _ordered_validation_alias_paths(validation_alias):
+            if path not in paths:
+                paths.append(path)
+    if model_type.model_config.get("validate_by_name") is True or not paths:
+        name_path = (_canonical_path_part(field_name),)
+        if name_path not in paths:
+            paths.append(name_path)
+    return tuple(paths)
+
+
+def _validation_alias_paths(alias: object) -> set[tuple[str, ...]]:
+    return set(_ordered_validation_alias_paths(alias))
+
+
+def _ordered_validation_alias_paths(alias: object) -> tuple[tuple[str, ...], ...]:
+    candidates: tuple[object, ...]
+    if isinstance(alias, AliasChoices):
+        candidates = tuple(alias.choices)
+    elif alias is None:
+        candidates = ()
+    else:
+        candidates = (alias,)
+    paths: list[tuple[str, ...]] = []
+    for candidate in candidates:
+        path = _canonical_validation_alias(candidate)
+        if path not in paths:
+            paths.append(path)
+    return tuple(paths)
+
+
+def _canonical_validation_alias(alias: object) -> tuple[str, ...]:
+    if isinstance(alias, str):
+        return (_canonical_alias_part(alias),)
+    if isinstance(alias, AliasPath):
+        if not alias.path or any(not isinstance(item, str) for item in alias.path):
+            raise ValueError("validation AliasPath must contain only configuration key segments")
+        return tuple(_canonical_alias_part(cast(str, part)) for part in alias.path)
+    raise TypeError("validation alias must be str, AliasPath or AliasChoices")
+
+
+def _validate_field_aliases(field: FieldInfo) -> None:
+    try:
+        _validation_alias_paths(field.validation_alias)
+        if isinstance(field.alias, str):
+            _validation_alias_paths(field.alias)
+    except (TypeError, ValueError) as original_error:
+        raise ValueError(
+            f"field validation alias is not a configuration path: {original_error}"
+        ) from original_error
+
+
+def _validate_model_input_paths(
+    model_type: type[BaseModel],
+    paths_by_field: Mapping[str, tuple[tuple[str, ...], ...]],
+) -> None:
+    items = tuple(paths_by_field.items())
+    for field_name, paths in items:
+        for index, path in enumerate(paths):
+            for other in paths[index + 1 :]:
+                if _paths_overlap(path, other):
+                    raise ValueError(
+                        f"field {model_type.__qualname__}.{field_name} has overlapping "
+                        "validation input paths"
+                    )
+    for index, (field_name, paths) in enumerate(items):
+        for other_name, other_paths in items[index + 1 :]:
+            if len(paths) == 1 and len(other_paths) == 1:
+                continue
+            if any(_paths_overlap(path, other) for path in paths for other in other_paths):
+                raise ValueError(
+                    f"fields {model_type.__qualname__}.{field_name} and {other_name} have "
+                    "overlapping validation input paths"
+                )
+
+
+def _paths_overlap(left: tuple[str, ...], right: tuple[str, ...]) -> bool:
+    shared = min(len(left), len(right))
+    return left[:shared] == right[:shared]
+
+
+def _canonical_path_part(part: str) -> str:
+    canonical = canonical_path(part)
+    if len(canonical) != 1:
+        raise ValueError("validation alias path segment must be a single configuration key")
+    return canonical[0]
+
+
+def _canonical_alias_part(part: str) -> str:
+    canonical = _canonical_path_part(part)
+    if canonical != part:
+        raise ValueError("validation alias segments must already be canonical snake_case")
+    return canonical
+
+
+def _annotation_contains_secret(annotation: object) -> bool:
+    if (
+        annotation in (SecretStr, SecretBytes)
+        or get_origin(annotation) is Secret
+        or (
+            isinstance(annotation, type)
+            and issubclass(annotation, (Secret, SecretStr, SecretBytes))
+        )
+    ):
+        return True
+    return any(_annotation_contains_secret(argument) for argument in get_args(annotation))
+
+
+def _annotation_has_secret_in_dynamic_mapping(annotation: object) -> bool:
+    origin = get_origin(annotation)
+    if origin is Mapping:
+        return any(
+            _annotation_contains_secret_deep(argument, seen=set())
+            for argument in get_args(annotation)
+        )
+    return any(
+        _annotation_has_secret_in_dynamic_mapping(argument) for argument in get_args(annotation)
+    )
+
+
+def _annotation_contains_secret_deep(
+    annotation: object,
+    *,
+    seen: set[type[BaseModel]],
+) -> bool:
+    if _annotation_contains_secret(annotation):
+        return True
+    model_type = _model_annotation(annotation)
+    if model_type is not None:
+        if model_type in seen:
+            return False
+        branch_seen = {*seen, model_type}
+        return any(
+            _annotation_contains_secret_deep(field.annotation, seen=branch_seen)
+            for field in model_type.model_fields.values()
+        )
+    return any(
+        _annotation_contains_secret_deep(argument, seen=seen) for argument in get_args(annotation)
+    )
+
+
+def _nested_model_types(annotation: object) -> tuple[type[BaseModel], ...]:
+    nested: list[type[BaseModel]] = []
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        nested.append(annotation)
+    for argument in get_args(annotation):
+        nested.extend(_nested_model_types(argument))
+    return tuple(nested)

python_platform/options/validation.py

@@ -0,0 +1,120 @@
+"""原生 Pydantic 验证边界：每个 Union 候选只解释自己的模型字段。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from functools import partial
+from typing import Any, cast
+
+from pydantic import BaseModel
+from pydantic_core import SchemaValidator, core_schema
+
+from ..configuration.values import normalize_mapping
+from .immutability import _merge_patch_input
+from .input_keys import _InputReference, _mapping_input_paths
+
+
+def _validate_input(
+    model: type[BaseModel], value: object, layers: tuple[tuple[object, bool], ...]
+) -> BaseModel:
+    # 不修改 model 的共享 schema/validator。所有原生 Union 模式、discriminator、
+    # alias、约束和用户 validator 都保留，只在候选模型输入边界加入字段归一化。
+    inputs = _InputNormalization()
+    inputs.index(value, layers)
+    schema = cast(
+        core_schema.CoreSchema, _input_schema(model.__pydantic_core_schema__, inputs.normalize)
+    )
+    # 原生重建开关禁止回用 class 上的旧 validator，否则会跳过此次输入 schema。
+    return cast(BaseModel, SchemaValidator(schema, _use_prebuilt=False).validate_python(value))
+
+
+def _input_schema(value: Any, normalize: Callable[[type[BaseModel], object], object]) -> Any:
+    if isinstance(value, list):
+        return [_input_schema(child, normalize) for child in value]
+    if isinstance(value, tuple):
+        return tuple(_input_schema(child, normalize) for child in value)
+    if not isinstance(value, dict):
+        return value
+    copied = {
+        name: child
+        if name in ("default", "metadata", "config", "serialization")
+        else _input_schema(child, normalize)
+        for name, child in value.items()
+    }
+    if value.get("type") == "model":
+        model = value["cls"]
+        reference = copied.pop("ref", None)
+        return core_schema.no_info_before_validator_function(
+            partial(normalize, model), copied, ref=reference
+        )
+    return copied
+
+
+class _InputNormalization:
+    """一次验证拥有的输入层索引；未标记 Union 在候选入口才按来源合并字段。"""
+
+    def __init__(self) -> None:
+        self._inputs: dict[int, tuple[object, tuple[tuple[object, bool], ...]]] = {}
+
+    def index(self, value: object, layers: tuple[tuple[object, bool], ...]) -> None:
+        if isinstance(value, Mapping):
+            # scalar/sequence 覆盖会截断更早的 mapping；来源顺序已由 Configuration 确定。
+            start = next(
+                (
+                    i + 1
+                    for i in range(len(layers) - 1, -1, -1)
+                    if not isinstance(layers[i][0], Mapping)
+                ),
+                0,
+            )
+            layers = layers[start:]
+            self._inputs[id(value)] = (value, layers)
+            for key, child in value.items():
+                children = tuple(
+                    (layer[key], merge)
+                    for layer, merge in layers
+                    if isinstance(layer, Mapping) and key in layer
+                )
+                self.index(child, children)
+        elif isinstance(value, tuple):
+            for i, child in enumerate(value):
+                last, merge = layers[-1] if layers else ((), False)
+                self.index(
+                    child, ((last[i], merge),) if isinstance(last, tuple) and i < len(last) else ()
+                )
+
+    def normalize(self, model: type[BaseModel], value: object) -> object:
+        if not isinstance(value, Mapping):
+            return value
+        values = cast(Mapping[str, object], value)
+        layers = self._inputs.get(id(value), (value, ()))[1]
+        reference = _InputReference(tuple(layer for layer, _ in layers)) if layers else values
+        try:
+            normalized = normalize_mapping(
+                values, mapping_paths=_mapping_input_paths(model, values, reference)
+            )
+        except ValueError:
+            if not layers:
+                raise
+        else:
+            if normalized == values:
+                # 已归一化的边界直接保留 alias 仲裁结果与子节点身份，不再解释来源。
+                return value
+            if not layers:
+                return normalized
+        normalized_layers = tuple(
+            (
+                normalize_mapping(
+                    cast(Mapping[str, object], layer),
+                    mapping_paths=_mapping_input_paths(model, layer, reference),
+                    merge_fields=merge,
+                ),
+                merge,
+            )
+            for layer, merge in layers
+        )
+        merged: dict[str, object] = {}
+        for layer, _ in normalized_layers:
+            merged = _merge_patch_input(merged, layer)
+        self.index(merged, normalized_layers)
+        return merged

python_platform/realtime/__init__.py

@@ -0,0 +1,12 @@
+"""Provider-neutral realtime public capability。"""
+
+from .contracts import RealtimePublisher
+from .diagnostics import RealtimeDeliveryReport, RealtimeSnapshot
+from .messages import RealtimeEnvelope
+
+__all__ = (
+    "RealtimeDeliveryReport",
+    "RealtimeEnvelope",
+    "RealtimePublisher",
+    "RealtimeSnapshot",
+)

python_platform/realtime/contracts.py

@@ -0,0 +1,28 @@
+"""Realtime publisher contract；delivery 只表示 Application-local queue acceptance。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Protocol, runtime_checkable
+from uuid import UUID
+
+from .diagnostics import RealtimeDeliveryReport
+
+
+@runtime_checkable
+class RealtimePublisher(Protocol):
+    async def send_to_connection(
+        self,
+        connection_id: UUID,
+        *,
+        message_type: str,
+        payload: Mapping[str, object],
+    ) -> RealtimeDeliveryReport: ...
+
+    async def send_to_user(
+        self,
+        user_id: UUID,
+        *,
+        message_type: str,
+        payload: Mapping[str, object],
+    ) -> RealtimeDeliveryReport: ...

python_platform/realtime/diagnostics.py

@@ -0,0 +1,37 @@
+"""不暴露连接 identity、user list、token 或 payload 的 realtime diagnostics。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class RealtimeDeliveryReport:
+    matched: int
+    enqueued: int
+    dropped: int
+
+    def __post_init__(self) -> None:
+        counts = (self.matched, self.enqueued, self.dropped)
+        if any(not isinstance(item, int) or isinstance(item, bool) or item < 0 for item in counts):
+            raise ValueError("realtime delivery counts must be non-negative integers")
+        if self.enqueued + self.dropped != self.matched:
+            raise ValueError("realtime delivery counts must partition matched connections")
+
+
+@dataclass(frozen=True, slots=True)
+class RealtimeSnapshot:
+    accepting: bool
+    active_connections: int
+    active_users: int
+    enqueued: int
+    dropped: int
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.accepting, bool):
+            raise TypeError("realtime accepting must be bool")
+        counts = (self.active_connections, self.active_users, self.enqueued, self.dropped)
+        if any(not isinstance(item, int) or isinstance(item, bool) or item < 0 for item in counts):
+            raise ValueError("realtime snapshot counts must be non-negative integers")
+        if self.active_users > self.active_connections:
+            raise ValueError("realtime active users cannot exceed active connections")