python-ddd-framework 0.3.1__py3-none-any.whl

python_ddd_framework/cli/inspection.py

@@ -0,0 +1,96 @@
+"""当前 Host 组合快照的只读展示；不解析服务实例或启动运行时。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from typing import cast
+
+from pydantic import ConfigDict, TypeAdapter
+
+from ..application import Application
+from ..configuration import ConfigurationRoot
+from .errors import CommandError
+from .project import Project
+
+
+async def inspect_application(environment: str) -> None:
+    project = Project.current()
+    application = project.host("application").load()(environment=environment)
+    if not isinstance(application, Application):
+        raise CommandError("The application entry point must return Application")
+    try:
+        report = _report(application)
+        output = TypeAdapter(
+            dict[str, object], config=ConfigDict(ser_json_bytes="base64")
+        ).dump_json(report, indent=2, fallback=_serialize_mapping)
+    finally:
+        # COMPOSED 也拥有 DI container；读取或序列化失败时同样交还给正式关闭流程。
+        await application.stop()
+    print(output.decode("utf-8"))
+
+
+def _report(application: Application) -> dict[str, object]:
+    graph = application.modules.snapshot
+    return {
+        "modules": {
+            "startup_order": [str(key) for key in graph.dependency_order],
+            "dependencies": [
+                {
+                    "module": str(module.key),
+                    "dependencies": [str(key) for key in module.dependencies],
+                    "source": module.declaration_source,
+                }
+                for module in application.modules.dependency_order
+            ],
+        },
+        "services": [
+            {
+                "service": str(row.key.type_hint),
+                "component": row.key.component,
+                "scope": row.scope.name,
+                "owner": str(row.owner),
+                "source": row.source,
+                "kind": row.kind.value,
+                "decision": row.decision.value,
+                "reason": row.decision_reason,
+            }
+            for row in application.service_catalog.registrations
+        ],
+        "configuration": {
+            "sources": application.configuration.sources,
+            "values": [
+                row
+                for section in application.configuration
+                for row in _configuration_rows(
+                    application.configuration,
+                    (section,),
+                    application.configuration.diagnostic(section).value,
+                )
+            ],
+        },
+    }
+
+
+def _configuration_rows(
+    configuration: ConfigurationRoot, path: tuple[str, ...], value: object
+) -> Iterator[dict[str, object]]:
+    # 只遍历正式 diagnostic 已脱敏的值；被整体隐藏的父节点不得再展开原值。
+    if isinstance(value, Mapping) and value:
+        for key, item in cast(Mapping[str, object], value).items():
+            yield from _configuration_rows(configuration, (*path, key), item)
+        return
+    # Mapping 数据键允许大小写和点号，查询和输出均保留 segment 身份。
+    provenance = configuration._provenance_at(path)
+    yield {
+        "path": path,
+        "value": value,
+        "sources": provenance.chain,
+        "effective_source": provenance.effective_source,
+    }
+
+
+def _serialize_mapping(value: object) -> object:
+    # Pydantic 原生 JSON serializer 负责日期、枚举、集合和 bytes；仅补不可变 Mapping。
+    if isinstance(value, Mapping):
+        return dict(value)
+    raise TypeError("Unsupported diagnostic value")

python_ddd_framework/cli/project.py

@@ -0,0 +1,69 @@
+"""当前项目的标准 pyproject/distribution/entry points，禁止第二份 Host 清单。"""
+
+from __future__ import annotations
+
+import importlib.metadata as metadata
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..application import Application
+from ..modularity import AppModule
+from .errors import CommandError
+
+HOST_ENTRY_POINT_GROUP = "python_ddd_framework.hosts"
+MODULE_ENTRY_POINT_GROUP = "python_ddd_framework.modules"
+
+
+def read_project(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("rb") as stream:
+            return tomllib.load(stream)
+    except (OSError, ValueError) as error:
+        raise CommandError(
+            f"Cannot read project metadata at {path}: {type(error).__name__}"
+        ) from None
+
+
+@dataclass(frozen=True, slots=True)
+class Project:
+    root: Path
+    name: str
+
+    @classmethod
+    def current(cls) -> Project:
+        root = Path.cwd().resolve()
+        project = read_project(root / "pyproject.toml").get("project", {})
+        name = project.get("name") if isinstance(project, dict) else None
+        if not isinstance(name, str) or not name:
+            raise CommandError("Current pyproject.toml must declare project.name")
+        return cls(root, name)
+
+    def host(self, name: str) -> metadata.EntryPoint:
+        try:
+            distribution = metadata.distribution(self.name)
+        except metadata.PackageNotFoundError:
+            raise CommandError(
+                "Install the current project with uv sync, then use uv run pddd"
+            ) from None
+        matches = tuple(
+            entry
+            for entry in distribution.entry_points
+            if entry.group == HOST_ENTRY_POINT_GROUP and entry.name == name
+        )
+        if len(matches) != 1:
+            raise CommandError(f"Project must declare exactly one {HOST_ENTRY_POINT_GROUP}:{name}")
+        return matches[0]
+
+    def module(self, name: str, application: Application) -> type[AppModule]:
+        # entry point 只命名已在当前图中的正式 Module；不导入未启用的 optional provider。
+        live = {str(item.key): item.module_type for item in application.modules.dependency_order}
+        matches = {
+            entry.value
+            for entry in metadata.entry_points(group=MODULE_ENTRY_POINT_GROUP)
+            if entry.name == name and entry.value in live
+        }
+        if len(matches) != 1:
+            raise CommandError(f"Module alias {name!r} must select exactly one live Module")
+        return live[matches.pop()]

python_ddd_framework/cli/runtime.py

@@ -0,0 +1,56 @@
+"""项目运行命令只编排正式 Host、迁移与 seed，不拥有业务初始化规则。"""
+
+from __future__ import annotations
+
+import os
+
+from . import ENVIRONMENT_VARIABLE
+from .errors import CommandError
+from .project import Project
+
+
+async def database(operation: str, environment: str, module: str) -> None:
+    from ..application import Application
+    from ..application_services.seeding import DataSeeder
+    from ..sqlalchemy import SqlAlchemyMigrator
+
+    project = Project.current()
+    factory = project.host("application").load()
+    application = factory(environment=environment)
+    if not isinstance(application, Application):
+        raise CommandError("The application entry point must return Application")
+    try:
+        selected = project.module(module, application)
+        migrator = SqlAlchemyMigrator(application)
+        if operation == "revision":
+            await migrator.revision(selected)
+        elif operation == "upgrade":
+            await migrator.upgrade_heads(module=selected)
+        elif operation == "status":
+            await migrator.check_current_heads(module=selected)
+        elif operation == "seed":
+            await migrator.check_current_heads(module=selected)
+            await application._start(run_services=False)
+            await DataSeeder(application).seed_all(module=selected)
+        else:
+            raise CommandError(f"Unknown database operation: {operation}")
+    finally:
+        await application.stop()
+    print(f"Database {operation} completed")
+
+
+def development_server(host: str, port: int) -> None:
+    from ..fastapi.server import run_host
+
+    project = Project.current()
+    entry = project.host("web")
+    os.environ[ENVIRONMENT_VARIABLE] = "development"
+    # 原生 access handler 不传播到 Host 的安全 formatter，不能记录含凭据的 query。
+    run_host(
+        entry.value,
+        host=host,
+        port=port,
+        reload=True,
+        project=project.root,
+        environment="development",
+    )

python_ddd_framework/configuration/__init__.py

@@ -0,0 +1,21 @@
+"""Configuration public contracts and Application-internal composition owners."""
+
+from .contracts import (
+    ConfigurationContribution,
+    ConfigurationProvenance,
+    ConfigurationSource,
+    ConfigurationSourceDiagnostic,
+    ConfigurationSourceStatus,
+    ConfigurationValueDiagnostic,
+)
+from .root import ConfigurationRoot
+
+__all__ = (
+    "ConfigurationContribution",
+    "ConfigurationProvenance",
+    "ConfigurationRoot",
+    "ConfigurationSource",
+    "ConfigurationSourceDiagnostic",
+    "ConfigurationSourceStatus",
+    "ConfigurationValueDiagnostic",
+)

python_ddd_framework/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_ddd_framework/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_ddd_framework/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_ddd_framework/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_ddd_framework/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_ddd_framework/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