python-platform 0.1.1__py3-none-any.whl

python_platform/configuration/values.py

@@ -0,0 +1,427 @@
+"""Configuration value canonicalization、deep immutability 与统一脱敏。"""
+
+from __future__ import annotations
+
+import keyword
+from collections.abc import Callable, Mapping
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path
+from types import MappingProxyType
+from typing import ClassVar, Final, cast
+from uuid import UUID
+
+from pydantic import Secret, SecretBytes, SecretStr
+
+MISSING: Final = object()
+REDACTION_MARKER: Final = "********"
+_SECRET_NAME_SUFFIXES: Final = (
+    "access_key",
+    "api_key",
+    "apikey",
+    "credential",
+    "credentials",
+    "password",
+    "passwd",
+    "private_key",
+    "secret",
+    "token",
+)
+
+
+class _ImmutableSecretMixin:
+    __slots__ = ()
+    _wrapped_secret_type: ClassVar[type[object]]
+
+    def __setattr__(self, name: str, value: object) -> None:
+        # Pydantic Secret 只保证显示脱敏，发布后还必须阻止改写其内部 payload。
+        if hasattr(self, "_secret_value"):
+            raise TypeError("published secret values are immutable")
+        super().__setattr__(name, value)
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            isinstance(other, _ImmutableSecretMixin)
+            and self._wrapped_secret_type is other._wrapped_secret_type
+            and secret_payload(self) == secret_payload(other)
+        )
+
+    def __hash__(self) -> int:
+        return hash((self._wrapped_secret_type, secret_payload(self)))
+
+
+class _FrozenSecretStr(_ImmutableSecretMixin, SecretStr):
+    __slots__ = ()
+    _wrapped_secret_type = SecretStr
+
+
+class _FrozenSecretBytes(_ImmutableSecretMixin, SecretBytes):
+    __slots__ = ()
+    _wrapped_secret_type = SecretBytes
+
+
+class _FrozenSecret(_ImmutableSecretMixin, Secret[object]):
+    __slots__ = ()
+    _wrapped_secret_type = Secret
+
+
+def normalize_mapping(
+    values: Mapping[str, object],
+    *,
+    mapping_paths: frozenset[tuple[str | int | None, ...]] = frozenset(),
+    path: tuple[str | int | None, ...] = (),
+    pending: bool = False,
+    strict_paths: frozenset[tuple[str, ...]] = frozenset(),
+    merge_fields: bool = False,
+) -> dict[str, object]:
+    normalized: dict[str, object] = {}
+    pending_here = pending and not any(path[: len(prefix)] == prefix for prefix in strict_paths)
+    for raw_key, raw_value in values.items():
+        if not isinstance(raw_key, str):
+            raise TypeError("configuration mapping keys must be strings")
+        if path in mapping_paths:
+            key = raw_key
+        elif pending_here:
+            key = raw_key.casefold()
+        else:
+            key = canonical_segment(raw_key)
+        child_path = (*path, key)
+        child = normalize_value(
+            raw_value,
+            mapping_paths=mapping_paths,
+            path=child_path,
+            pending=pending,
+            strict_paths=strict_paths,
+            merge_fields=merge_fields,
+        )
+        if key in normalized and not pending_here:
+            _merge_source_fields(normalized, key, child, child_path, mapping_paths, merge_fields)
+        else:
+            normalized[key] = child
+    return normalized
+
+
+def normalize_value(
+    value: object,
+    *,
+    mapping_paths: frozenset[tuple[str | int | None, ...]] = frozenset(),
+    path: tuple[str | int | None, ...] = (),
+    pending: bool = False,
+    strict_paths: frozenset[tuple[str, ...]] = frozenset(),
+    merge_fields: bool = False,
+) -> object:
+    if isinstance(value, Mapping):
+        return normalize_mapping(
+            cast(Mapping[str, object], value),
+            mapping_paths=mapping_paths,
+            path=path,
+            pending=pending,
+            strict_paths=strict_paths,
+            merge_fields=merge_fields,
+        )
+    if isinstance(value, (list, tuple)):
+        return tuple(
+            normalize_value(
+                item,
+                mapping_paths=mapping_paths,
+                path=(*path, index),
+                pending=pending,
+                strict_paths=strict_paths,
+                merge_fields=merge_fields,
+            )
+            for index, item in enumerate(value)
+        )
+    if isinstance(value, (set, frozenset)):
+        return frozenset(
+            normalize_value(
+                item,
+                mapping_paths=mapping_paths,
+                path=(*path, index),
+                pending=pending,
+                strict_paths=strict_paths,
+                merge_fields=merge_fields,
+            )
+            for index, item in enumerate(value)
+        )
+    if isinstance(value, bytearray):
+        return bytes(value)
+    if is_supported_scalar(value):
+        return value
+    raise TypeError(f"unsupported mutable or opaque configuration value {type(value).__name__}")
+
+
+def _merge_source_fields(
+    target: dict[str, object],
+    key: str,
+    incoming: object,
+    path: tuple[str | int | None, ...],
+    mapping_paths: frozenset[tuple[str | int | None, ...]],
+    allowed: bool,
+) -> None:
+    current = target[key]
+    if not allowed or not isinstance(current, dict) or not isinstance(incoming, Mapping):
+        raise ValueError("duplicate canonical configuration field")
+    # 原生环境来源允许 JSON 对象加嵌套变量。合并字段片段，不折叠数据键身份。
+    for name, value in incoming.items():
+        if name in current and path not in mapping_paths:
+            _merge_source_fields(current, name, value, (*path, name), mapping_paths, allowed)
+        else:
+            current[name] = value
+
+
+def _capture_input_mapping(values: Mapping[str, object], *, root: bool = True) -> dict[str, object]:
+    # 来源只读取一次。类型声明晚于来源读取，数据键必须在这份快照里保留原貌。
+    result: dict[str, object] = {}
+    for name, value in values.items():
+        if not isinstance(name, str):
+            raise TypeError("configuration mapping keys must be strings")
+        key = canonical_segment(name) if root else name
+        if key in result:
+            raise ValueError("duplicate canonical configuration field")
+        result[key] = _capture_input_value(value)
+    return result
+
+
+def _capture_input_value(value: object) -> object:
+    if isinstance(value, Mapping):
+        return _capture_input_mapping(value, root=False)
+    if isinstance(value, (list, tuple)):
+        return tuple(_capture_input_value(item) for item in value)
+    if isinstance(value, (set, frozenset)):
+        return frozenset(_capture_input_value(item) for item in value)
+    if isinstance(value, bytearray):
+        return bytes(value)
+    if is_supported_scalar(value):
+        return value
+    raise TypeError("unsupported mutable or opaque configuration value")
+
+
+def freeze_value(value: object) -> object:
+    if isinstance(value, (Secret, SecretStr, SecretBytes)):
+        return _freeze_secret_value(value)
+    if isinstance(value, Mapping):
+        return MappingProxyType({key: freeze_value(item) for key, item in value.items()})
+    if isinstance(value, tuple):
+        return tuple(freeze_value(item) for item in value)
+    if isinstance(value, frozenset):
+        return frozenset(freeze_value(item) for item in value)
+    if is_supported_scalar(value):
+        return value
+    raise TypeError(f"unsupported mutable or opaque configuration value {type(value).__name__}")
+
+
+def _freeze_secret_value(value: object) -> object:
+    if isinstance(value, _ImmutableSecretMixin):
+        return value
+    if isinstance(value, SecretStr):
+        frozen_value: object = value.get_secret_value()
+        base_frozen_type: type[object] = _FrozenSecretStr
+        base_type: type[object] = SecretStr
+    elif isinstance(value, SecretBytes):
+        frozen_value = value.get_secret_value()
+        base_frozen_type = _FrozenSecretBytes
+        base_type = SecretBytes
+    elif isinstance(value, Secret):
+        frozen_value = freeze_value(value.get_secret_value())
+        base_frozen_type = _FrozenSecret
+        base_type = Secret
+    else:
+        raise TypeError(f"unsupported secret value {type(value).__name__}")
+
+    concrete_type = type(value)
+    frozen_type = (
+        base_frozen_type
+        if concrete_type is base_type
+        else type(
+            f"_Frozen{concrete_type.__name__}",
+            (_ImmutableSecretMixin, concrete_type),
+            {
+                "__slots__": (),
+                "__module__": __name__,
+                "_wrapped_secret_type": concrete_type,
+            },
+        )
+    )
+    factory = cast(Callable[[object], object], frozen_type)
+    return factory(frozen_value)
+
+
+def is_frozen_secret(value: object) -> bool:
+    return isinstance(value, _ImmutableSecretMixin)
+
+
+def secret_payload(value: object) -> object:
+    if isinstance(value, (Secret, SecretStr, SecretBytes)):
+        return value.get_secret_value()
+    raise TypeError(f"unsupported secret value {type(value).__name__}")
+
+
+def redact_value(
+    value: object,
+    *,
+    path: tuple[str, ...],
+    secret_paths: frozenset[str],
+) -> tuple[object, bool]:
+    canonical = ".".join(path)
+    if (
+        canonical in secret_paths
+        or any(canonical.startswith(f"{secret_path}.") for secret_path in secret_paths)
+        or _looks_secret(path)
+        or isinstance(value, (Secret, SecretStr, SecretBytes))
+    ):
+        return REDACTION_MARKER, True
+    if isinstance(value, Mapping):
+        redacted = False
+        sanitized: dict[str, object] = {}
+        for key, item in value.items():
+            sanitized_item, item_redacted = redact_value(
+                item,
+                path=(*path, key),
+                secret_paths=secret_paths,
+            )
+            sanitized[key] = sanitized_item
+            redacted = redacted or item_redacted
+        return MappingProxyType(sanitized), redacted
+    if isinstance(value, tuple):
+        items: list[object] = []
+        redacted = False
+        for item in value:
+            sanitized_item, item_redacted = redact_value(
+                item,
+                path=path,
+                secret_paths=secret_paths,
+            )
+            items.append(sanitized_item)
+            redacted = redacted or item_redacted
+        return tuple(items), redacted
+    if isinstance(value, frozenset):
+        frozen_items: list[object] = []
+        redacted = False
+        for item in value:
+            sanitized_item, item_redacted = redact_value(
+                item,
+                path=path,
+                secret_paths=secret_paths,
+            )
+            frozen_items.append(sanitized_item)
+            redacted = redacted or item_redacted
+        return frozenset(frozen_items), redacted
+    return value, False
+
+
+def _looks_secret(path: tuple[str, ...]) -> bool:
+    return any(_looks_secret_name(segment) for segment in path)
+
+
+def _looks_secret_name(name: str) -> bool:
+    """Configuration/Settings 共用的 secret-shaped name 单一判定权威。"""
+
+    normalized = name.casefold().replace("-", "_")
+    return any(
+        segment.endswith(_SECRET_NAME_SUFFIXES) for segment in normalized.split(".") if segment
+    )
+
+
+def is_supported_scalar(value: object) -> bool:
+    if isinstance(value, (Secret, SecretBytes, SecretStr)):
+        return True
+    if isinstance(value, Enum):
+        return _enum_member_is_deeply_immutable(value, seen=set())
+    return _is_intrinsically_immutable_scalar(value)
+
+
+def _enum_member_is_deeply_immutable(value: Enum, *, seen: set[int]) -> bool:
+    identity = id(value)
+    if identity in seen:
+        return True
+    member_state = vars(value)
+    if any(
+        name not in {"_name_", "_sort_order_", "_value_", "__objclass__"} for name in member_state
+    ):
+        # Enum member 是跨 Application singleton；任何额外 instance state 都不可发布。
+        return False
+    return _enum_payload_is_deeply_immutable(value.value, seen={*seen, identity})
+
+
+def _enum_payload_is_deeply_immutable(value: object, *, seen: set[int]) -> bool:
+    if isinstance(value, Enum):
+        return _enum_member_is_deeply_immutable(value, seen=seen)
+    if _is_intrinsically_immutable_scalar(value):
+        return True
+    identity = id(value)
+    if identity in seen:
+        return True
+    branch_seen = {*seen, identity}
+    if type(value) is tuple or _is_named_tuple_instance(value):
+        tuple_value = cast(tuple[object, ...], value)
+        return all(
+            _enum_payload_is_deeply_immutable(item, seen=branch_seen) for item in tuple_value
+        )
+    if isinstance(value, frozenset):
+        return all(_enum_payload_is_deeply_immutable(item, seen=branch_seen) for item in value)
+    # MappingProxyType 仍可能被持有原 dict 的代码改写。
+    return False
+
+
+def _is_named_tuple_instance(value: object) -> bool:
+    fields = getattr(type(value), "_fields", None)
+    return (
+        isinstance(value, tuple)
+        and isinstance(fields, tuple)
+        and all(isinstance(field, str) for field in fields)
+        and not hasattr(value, "__dict__")
+    )
+
+
+def _is_intrinsically_immutable_scalar(value: object) -> bool:
+    if type(value) in {
+        UUID,
+        date,
+        datetime,
+        Decimal,
+        time,
+        timedelta,
+        bool,
+        bytes,
+        float,
+        int,
+        str,
+        type(None),
+    }:
+        return True
+    return isinstance(value, Path) and type(value).__module__ == Path.__module__
+
+
+def lookup_path(tree: Mapping[str, object], parts: tuple[str, ...]) -> object:
+    current: object = tree
+    for part in parts:
+        if not isinstance(current, Mapping):
+            raise TypeError("configuration path traversed a scalar value")
+        current = current[part]
+    return current
+
+
+def canonical_path(path: str) -> tuple[str, ...]:
+    if not isinstance(path, str):
+        raise TypeError("configuration path must be a string")
+    return tuple(canonical_segment(part) for part in path.split("."))
+
+
+def canonical_segment(segment: object) -> str:
+    if not isinstance(segment, str):
+        raise TypeError("configuration key must be a string")
+    if not segment or segment != segment.strip() or "." in segment:
+        raise ValueError("configuration key segments must be non-empty and must not contain dots")
+    canonical = segment.casefold()
+    if not canonical.isidentifier() or keyword.iskeyword(canonical):
+        raise ValueError(f"configuration key {segment!r} is not a valid identifier segment")
+    return canonical
+
+
+def raw_kind(value: object) -> str:
+    if isinstance(value, Mapping):
+        return "mapping"
+    if isinstance(value, (tuple, frozenset)):
+        return "sequence"
+    return type(value).__name__

python_platform/configuration/yaml_source.py

@@ -0,0 +1,51 @@
+"""原生 YAML source 的安全结构边界；语法与标签仍由 PyYAML SafeLoader 解释。"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from pathlib import Path
+from typing import Any, cast
+
+from pydantic_settings import YamlConfigSettingsSource
+from pydantic_settings.sources.types import Traversable
+
+# PyYAML 未发布 typing；动态类型只留在原生 loader 边界，不向 Kernel 扩散。
+yaml = import_module("yaml")
+
+
+class _UniqueKeySafeLoader(yaml.SafeLoader):  # type: ignore[misc, name-defined]
+    def construct_mapping(self, node: Any, deep: bool = False) -> dict[Any, Any]:
+        # 在原生 merge-key 展开前检查显式重复键；合法 anchor merge 仍由原生规则处理。
+        keys: set[object] = set()
+        for key_node, _ in node.value:
+            if key_node.tag == "tag:yaml.org,2002:merge":
+                continue
+            key = self.construct_object(key_node, deep=deep)
+            if key in keys:
+                raise ValueError("duplicate YAML mapping key")
+            keys.add(key)
+        return cast(dict[Any, Any], super().construct_mapping(node, deep=deep))
+
+
+class _YamlConfigurationSource(YamlConfigSettingsSource):
+    def _read_file(self, file_path: Path | Traversable) -> dict[str, Any]:
+        with file_path.open(encoding="utf-8") as stream:
+            value = yaml.load(stream, Loader=_UniqueKeySafeLoader)
+        if value is None:
+            return {}
+        if not isinstance(value, dict):
+            raise ValueError("YAML configuration must be a mapping")
+        _reject_cycles(value, set())
+        return value
+
+
+def _reject_cycles(value: object, active: set[int]) -> None:
+    if not isinstance(value, (dict, list)):
+        return
+    identity = id(value)
+    if identity in active:
+        raise ValueError("cyclic YAML configuration")
+    active.add(identity)
+    for item in value.values() if isinstance(value, dict) else value:
+        _reject_cycles(item, active)
+    active.remove(identity)

python_platform/developer_kit/__init__.py

@@ -0,0 +1 @@
+"""随框架版本发布的开发工具；运行命令不依赖本包。"""

python_platform/developer_kit/generation.py

@@ -0,0 +1,182 @@
+"""包内模板 staging 校验和发布；不覆盖文件，不移动已安装环境。"""
+
+from __future__ import annotations
+
+import ast
+import importlib.metadata as metadata
+import importlib.resources as resources
+import inspect
+import keyword
+import os
+import platform
+import re
+import secrets
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+# 官方库未发布 typing marker；仅在第三方导入边界忽略缺失的类型信息。
+from cookiecutter.main import cookiecutter  # type: ignore[import-untyped]
+
+from ..application import Application
+from ..cli import ENVIRONMENT_VARIABLE
+from ..cli.errors import CommandError
+from ..cli.project import Project, read_project
+from .project_metadata import add_module_metadata
+from .source import framework_source
+from .wiring import add_dependency
+
+
+def _name(value: str) -> tuple[str, str]:
+    if not re.fullmatch(r"[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*", value) or re.fullmatch(
+        r"con|prn|aux|nul|com[1-9]|lpt[1-9]", value
+    ):
+        raise CommandError("Use a lowercase project/module name valid on Windows and Linux")
+    package = value.replace("-", "_")
+    if keyword.iskeyword(package):
+        raise CommandError("Project/module package name must not be a Python keyword")
+    return package, "".join(part.capitalize() for part in package.split("_"))
+
+
+def _render(template: str, context: dict[str, Any]) -> Path:
+    staging = Path(tempfile.mkdtemp(prefix="python-platform-generation-"))
+    root = resources.files(__package__).joinpath("templates").joinpath(template)
+    with resources.as_file(root) as template_path:
+        # Cookiecutter 用相对路径加载；安装目录较深时先复制到短 staging，避免 Windows MAX_PATH。
+        source = str(template_path.resolve())
+        if os.name == "nt" and not source.startswith("\\\\?\\"):
+            source = (
+                "\\\\?\\UNC\\" + source[2:] if source.startswith("\\\\") else "\\\\?\\" + source
+            )
+        local_template = staging / "template"
+        shutil.copytree(source, local_template)
+        rendered = Path(
+            cookiecutter(
+                str(local_template),
+                no_input=True,
+                extra_context=context,
+                output_dir=str(staging / "output"),
+                default_config=True,
+                accept_hooks=False,
+                keep_project_on_failure=True,
+            )
+        )
+    for path in tuple(rendered.rglob("*.jinja")):
+        path.rename(path.with_suffix(""))
+    _validate(rendered)
+    return rendered
+
+
+def _validate(root: Path) -> None:
+    for path in root.rglob("*"):
+        if path.is_symlink():
+            raise CommandError("Generated output must not contain symbolic links")
+        if path.suffix == ".py":
+            ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        elif path.suffix == ".toml":
+            read_project(path)
+
+
+def new_project(name: str, wheel: Path | None, dry_run: bool) -> None:
+    package, class_prefix = _name(name)
+    destination = Path.cwd() / name
+    if destination.exists():
+        raise CommandError(f"Destination already exists: {destination}")
+    source = framework_source(wheel)
+    if dry_run:
+        print(f"Would generate {destination} with bundled Host template")
+        return
+    distribution = metadata.distribution("python-platform")
+    generator = (distribution.read_text("WHEEL") or "").split("Generator: uv ")[-1].splitlines()[0]
+    if not re.fullmatch(r"\d+\.\d+\.\d+", generator):
+        raise CommandError("Cannot determine the framework wheel's uv build tool version")
+    staged = _render(
+        "project",
+        {
+            "project_name": name,
+            "package_name": package,
+            "class_prefix": class_prefix,
+            "framework_version": source.version,
+            "framework_source": source.uv_source,
+            "python_version": platform.python_version(),
+            "build_version": generator,
+            "host_environment_variable": ENVIRONMENT_VARIABLE,
+            "database_password": secrets.token_urlsafe(24),
+            "admin_password": secrets.token_urlsafe(24),
+            "jwt_key": secrets.token_urlsafe(48),
+        },
+    )
+    if source.wheel is not None:
+        vendor = staged / "vendor"
+        vendor.mkdir()
+        shutil.copy2(source.wheel, vendor / source.wheel.name)
+    # copytree 原生拒绝已存在目录；staging 跨 Windows 盘符，不能依赖目录 rename。
+    shutil.copytree(staged, destination)
+    print(f"Generated {destination}; staging retained at {staged}")
+    subprocess.run(["uv", "sync"], cwd=destination, check=True)
+
+
+def add_module(name: str, dry_run: bool) -> None:
+    package, class_prefix = _name(name)
+    project = Project.current()
+    application = project.host("application").load()(environment="development")
+    if not isinstance(application, Application):
+        raise CommandError("The application entry point must return Application")
+    startup = application.modules.startup.module_type
+    if startup.__qualname__ != startup.__name__:
+        raise CommandError("Startup Module must be a top-level class for module generation")
+    source_path = Path(inspect.getfile(startup)).resolve()
+    if not source_path.is_relative_to(project.root / "src"):
+        raise CommandError(
+            "Startup Module source must belong to the current project's src directory"
+        )
+    modules = project.root / "src" / "modules"
+    destination = modules / package
+    if destination.exists():
+        raise CommandError(f"Module destination already exists: {destination}")
+    source = source_path.read_text(encoding="utf-8")
+    updated = source
+    for layer, suffix in (
+        ("application", "ApplicationModule"),
+        ("sqlalchemy", "SqlAlchemyModule"),
+        ("http_api", "HttpApiModule"),
+    ):
+        updated = add_dependency(
+            updated, startup.__name__, f"modules.{package}.{layer}.module", class_prefix + suffix
+        )
+    metadata_path = project.root / "pyproject.toml"
+    metadata_source = metadata_path.read_text(encoding="utf-8")
+    updated_metadata = add_module_metadata(metadata_source, package, class_prefix)
+    ast.parse(updated)
+    if dry_run:
+        print(
+            f"Would add {destination}, wire modules into {source_path} and update {metadata_path}"
+        )
+        return
+    staged = _render(
+        "module",
+        {
+            "module_name": package,
+            "class_prefix": class_prefix,
+        },
+    )
+    # 先验证全部新文件和接线；已有 startup 文件仅在内容仍等于读取快照时替换。
+    if (
+        source_path.read_text(encoding="utf-8") != source
+        or metadata_path.read_text(encoding="utf-8") != metadata_source
+    ):
+        raise CommandError("Startup source changed during generation; retry after reviewing it")
+    modules.mkdir(exist_ok=True)
+    if not modules.joinpath("__init__.py").exists():
+        modules.joinpath("__init__.py").touch()
+    shutil.copytree(staged, destination)
+    with tempfile.NamedTemporaryFile(
+        mode="w", encoding="utf-8", dir=source_path.parent, delete=False
+    ) as pending:
+        pending.write(updated)
+    Path(pending.name).replace(source_path)
+    metadata_path.write_text(updated_metadata, encoding="utf-8")
+    subprocess.run(["uv", "sync"], cwd=project.root, check=True)
+    print(f"Added {package}; staging retained at {staged}")