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

python_ddd_framework/background_workers/runtime.py

@@ -0,0 +1,219 @@
+"""Application-owned 任务编排；目录提供任务事实，执行 owner 各自管理本地或子进程资源。"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import defaultdict
+from collections.abc import Mapping
+
+from dishka import AsyncContainer
+
+from ..application.build_spec import _ApplicationBuildSpec
+from ..application_services.invocation import _InvocationRuntime
+from ..background_execution import (
+    BackgroundExecutionMode,
+    BackgroundJobOptions,
+    BackgroundTaskOptions,
+    BackgroundTaskSnapshot,
+)
+from ..background_execution.lifecycle import _BackgroundRuntimeFailure, _TaskExecution
+from ..background_execution.local import _LocalTask
+from ..background_execution.locks import _check_previous_owners
+from ..background_execution.processes import _ProcessSlot
+from ..background_jobs import BackgroundJobCatalog
+from ..invocation import BackgroundSystemCaller
+from .catalog import BackgroundWorkerCatalog
+from .contracts import BackgroundExecutionOptions, BackgroundExecutionProfile
+from .execution import _WorkerExecution
+
+
+class _BackgroundCoordinator:
+    def __init__(
+        self,
+        *,
+        worker_catalog: BackgroundWorkerCatalog,
+        job_catalog: BackgroundJobCatalog,
+        options: BackgroundExecutionOptions,
+        invocation_runtime: _InvocationRuntime,
+        build_spec: _ApplicationBuildSpec,
+    ) -> None:
+        self._worker_catalog = worker_catalog
+        self._job_catalog = job_catalog
+        self._options = options
+        self._invocation_runtime = invocation_runtime
+        self._spec = build_spec
+        self._caller = BackgroundSystemCaller()
+        self._container: AsyncContainer | None = None
+        self._started = False
+        self._prepared = False
+        self._child = False
+        self._database_only = False
+        self._failures: asyncio.Queue[_BackgroundRuntimeFailure] = asyncio.Queue()
+        self._tasks: dict[str, _LocalTask] = {}
+        self._slots: dict[str, _ProcessSlot] = {}
+        self._task_slots: dict[str, _ProcessSlot] = {}
+        self._register_tasks(
+            "worker",
+            {item.name: item.enabled for item in worker_catalog.definitions},
+            options.workers,
+        )
+        self._register_tasks(
+            "job", {item.name: True for item in job_catalog.definitions}, options.jobs
+        )
+        self._local = {
+            key
+            for key, task in self._tasks.items()
+            if task.options.mode is BackgroundExecutionMode.HOST
+        }
+        self._initial = {key for key in self._local if self._tasks[key].options.enabled}
+
+    def _register_tasks(
+        self,
+        kind: str,
+        declarations: Mapping[str, bool],
+        configured: Mapping[str, BackgroundJobOptions],
+    ) -> None:
+        unknown = set(configured) - declarations.keys()
+        if unknown:
+            raise ValueError(f"Unknown background {kind} configuration: {sorted(unknown)}")
+        for name, admitted in sorted(declarations.items()):
+            key = f"{kind}:{name}"
+            configured_options = configured.get(name, BackgroundJobOptions())
+            enabled = (
+                configured_options.enabled
+                if isinstance(configured_options, BackgroundTaskOptions)
+                else True
+            )
+            options = BackgroundTaskOptions(
+                mode=configured_options.mode, enabled=admitted and enabled
+            )
+            self._tasks[key] = _LocalTask(
+                key,
+                options,
+                self._options.graceful_shutdown_timeout.total_seconds(),
+                self._failures.put_nowait,
+            )
+
+    @property
+    def profile(self) -> BackgroundExecutionProfile:
+        return BackgroundExecutionProfile.DISABLED if self._database_only else self._options.profile
+
+    def disable_for_database(self) -> None:
+        if self._started or self._prepared:
+            raise RuntimeError("Database execution must be selected before initialization")
+        self._database_only = True
+
+    @property
+    def system_caller(self) -> BackgroundSystemCaller:
+        return self._caller
+
+    @property
+    def has_runtime_failure_source(self) -> bool:
+        return any(
+            task.execution is not None and task.execution.wait_for_failure is not None
+            for key, task in self._tasks.items()
+            if key in self._local
+        )
+
+    @property
+    def local_job_names(self) -> tuple[str, ...]:
+        if self.profile is BackgroundExecutionProfile.DISABLED:
+            return ()
+        return tuple(
+            key.removeprefix("job:")
+            for key in self._local
+            if key.startswith("job:") and self._tasks[key].options.enabled
+        )
+
+    def select_child(
+        self, tasks: dict[str, BackgroundTaskOptions], initial: tuple[str, ...]
+    ) -> None:
+        if self._prepared or self._started:
+            raise RuntimeError("Child task assignment is frozen before startup")
+        for key, options in tasks.items():
+            if key not in self._tasks or self._tasks[key].options != options:
+                raise RuntimeError("Child task catalog/configuration differs from parent")
+        self._child = True
+        self._local = set(tasks)
+        self._initial = set(initial)
+
+    def prepare(self) -> None:
+        if self._prepared:
+            raise RuntimeError("Background coordinator is already prepared")
+        self._prepared = True
+        self._worker_catalog._assert_unchanged()
+        self._job_catalog._assert_unchanged()
+        if self._child or self.profile is BackgroundExecutionProfile.DISABLED:
+            return
+        groups: dict[str, dict[str, BackgroundTaskOptions]] = defaultdict(dict)
+        for key, task in self._tasks.items():
+            mode = task.options.mode
+            if mode is not BackgroundExecutionMode.HOST:
+                position = "shared" if mode is BackgroundExecutionMode.SHARED else key
+                groups[position][key] = task.options
+        if groups:
+            _check_previous_owners(self._spec.project, self._spec.environment)
+        for position, tasks in groups.items():
+            slot = _ProcessSlot(position, tasks, self._spec, self._options)
+            slot.reserve()
+            self._slots[position] = slot
+            self._task_slots.update({key: slot for key in tasks})
+
+    def attach_container(self, container: AsyncContainer) -> None:
+        if self._container is not None:
+            raise RuntimeError("Background coordinator container is already attached")
+        self._container = container
+        for definition in self._worker_catalog.definitions:
+            self._tasks[f"worker:{definition.name}"].execution = _WorkerExecution(
+                definition, container, self._invocation_runtime, self._caller
+            ).binding
+
+    def bind_durable(self, name: str, binding: _TaskExecution) -> None:
+        task = self._tasks[f"job:{name}"]
+        if self._started or task.execution is not None:
+            raise RuntimeError("Durable background task may only be bound once before start")
+        task.execution = binding
+
+    async def start(self) -> None:
+        if self._started:
+            raise RuntimeError("Background coordinator is already started")
+        self._started = True
+        self.prepare()
+        if self.profile is BackgroundExecutionProfile.DISABLED:
+            return
+        for key in self._tasks:
+            if key in self._initial:
+                await self._tasks[key].start()
+        for slot in self._slots.values():
+            await slot.start()
+
+    def snapshots(self) -> tuple[BackgroundTaskSnapshot, ...]:
+        remote = {item.id: item for slot in self._slots.values() for item in slot.snapshots()}
+        return tuple(
+            remote.get(key, task.snapshot())
+            for key, task in self._tasks.items()
+            if not self._child or key in self._local
+        )
+
+    def request(self, key: str, *, start: bool) -> BackgroundTaskSnapshot:
+        if not self._started or self.profile is BackgroundExecutionProfile.DISABLED:
+            raise ValueError("Background execution is not active")
+        if key not in self._tasks or (self._child and key not in self._local):
+            raise KeyError(key)
+        slot = self._task_slots.get(key)
+        if slot is not None:
+            return slot.request(key, start)
+        return self._tasks[key].request(start)
+
+    async def stop(self) -> None:
+        # 即使启动前的预占或 Module 初始化失败，也必须释放已取得的位置。
+        operations = [task.shutdown() for key, task in self._tasks.items() if key in self._local]
+        operations.extend(slot.shutdown() for slot in self._slots.values())
+        outcomes = await asyncio.gather(*operations, return_exceptions=True)
+        self._started = False
+        failures = tuple(item for item in outcomes if isinstance(item, BaseException))
+        if failures:
+            raise BaseExceptionGroup("Background runtime drain failed", failures)
+
+    async def wait_for_runtime_failure(self) -> _BackgroundRuntimeFailure:
+        return await self._failures.get()

python_ddd_framework/caching/__init__.py

@@ -0,0 +1,11 @@
+from .catalog import CacheCatalog
+from .contracts import CacheDefinition, DistributedCache
+from .errors import CacheDefinitionError, DistributedCacheError
+
+__all__ = (
+    "CacheCatalog",
+    "CacheDefinition",
+    "CacheDefinitionError",
+    "DistributedCache",
+    "DistributedCacheError",
+)

python_ddd_framework/caching/catalog.py

@@ -0,0 +1,73 @@
+"""Cache metadata 的 Application-local 动态聚合与 immutable view。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from types import MappingProxyType
+from typing import Any
+
+from ..modularity import ModuleRegistry
+from .contracts import CacheDefinition
+from .errors import CacheDefinitionError
+
+
+class CacheCatalog:
+    __slots__ = ("_definitions",)
+
+    def __init__(self, definitions: tuple[CacheDefinition[Any], ...]) -> None:
+        by_name: dict[str, CacheDefinition[Any]] = {}
+        for definition in definitions:
+            if not isinstance(definition, CacheDefinition):
+                raise CacheDefinitionError(
+                    cache=repr(definition),
+                    reason="catalog entries must be CacheDefinition values",
+                )
+            if definition.name in by_name:
+                raise CacheDefinitionError(
+                    cache=definition.name,
+                    reason="cache is declared more than once",
+                )
+            by_name[definition.name] = definition
+        self._definitions: Mapping[str, CacheDefinition[Any]] = MappingProxyType(
+            dict(sorted(by_name.items()))
+        )
+
+    @property
+    def definitions(self) -> tuple[CacheDefinition[Any], ...]:
+        return tuple(self._definitions.values())
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._definitions)
+
+    def get(self, name: str) -> CacheDefinition[Any] | None:
+        return self._definitions.get(name)
+
+    def owns(self, definition: CacheDefinition[Any]) -> bool:
+        return self._definitions.get(definition.name) is definition
+
+
+def _build_cache_catalog(registry: ModuleRegistry) -> CacheCatalog:
+    definitions: list[CacheDefinition[Any]] = []
+    owners: dict[str, str] = {}
+    for descriptor in registry.dependency_order:
+        declared = descriptor.module_type.cache_definitions
+        if not isinstance(declared, tuple):
+            raise CacheDefinitionError(
+                cache=str(descriptor.key),
+                reason="Module cache_definitions must be an immutable tuple",
+            )
+        for definition in declared:
+            if not isinstance(definition, CacheDefinition):
+                raise CacheDefinitionError(
+                    cache=str(descriptor.key),
+                    reason="Module cache_definitions contains an invalid item",
+                )
+            previous = owners.get(definition.name)
+            if previous is not None:
+                raise CacheDefinitionError(
+                    cache=definition.name,
+                    reason=f"cache is already owned by {previous}",
+                )
+            owners[definition.name] = str(descriptor.key)
+            definitions.append(definition)
+    return CacheCatalog(tuple(definitions))

python_ddd_framework/caching/contracts.py

@@ -0,0 +1,73 @@
+"""强制 TTL 的 typed cache definition 与最小读写契约。"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any, Generic, Protocol, TypeVar
+
+from pydantic import TypeAdapter
+
+from .errors import CacheDefinitionError
+
+_T = TypeVar("_T")
+
+
+class CacheDefinition(Generic[_T]):
+    __slots__ = ("_adapter", "_name", "_ttl", "_value_type")
+
+    def __init__(self, name: str, value_type: type[_T], *, ttl: timedelta) -> None:
+        if (
+            not isinstance(name, str)
+            or not name
+            or name != name.strip()
+            or name.startswith(":")
+            or name.endswith(":")
+            or "::" in name
+            # ':' 是 Redis key 的结构分隔符，definition name 不得制造跨 cache key 歧义。
+            or any(not (item.isalnum() or item in "._-") for item in name)
+        ):
+            raise CacheDefinitionError(
+                cache=name if isinstance(name, str) else repr(name),
+                reason="name must be a trimmed cache identifier",
+            )
+        if not isinstance(value_type, type):
+            raise CacheDefinitionError(cache=name, reason="value_type must be a runtime type")
+        if not isinstance(ttl, timedelta) or ttl.total_seconds() <= 0:
+            raise CacheDefinitionError(cache=name, reason="ttl must be a positive timedelta")
+        if ttl.total_seconds() > 2_147_483_647:
+            raise CacheDefinitionError(cache=name, reason="ttl exceeds the supported Redis range")
+        self._name = name
+        self._value_type = value_type
+        self._ttl = ttl
+        self._adapter: TypeAdapter[_T] = TypeAdapter(value_type)
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def value_type(self) -> type[_T]:
+        return self._value_type
+
+    @property
+    def ttl(self) -> timedelta:
+        return self._ttl
+
+    def __repr__(self) -> str:
+        return (
+            f"CacheDefinition(name={self.name!r}, value_type={self.value_type!r}, ttl={self.ttl!r})"
+        )
+
+    def _serialize(self, value: _T) -> bytes:
+        return self._adapter.dump_json(self._adapter.validate_python(value))
+
+    def _deserialize(self, value: bytes | str) -> _T:
+        return self._adapter.validate_json(value)
+
+
+class DistributedCache(Protocol):
+    async def get(self, definition: CacheDefinition[_T], key: str) -> _T | None: ...
+
+    async def set(self, definition: CacheDefinition[_T], key: str, value: _T) -> None: ...
+
+    async def remove(self, definition: CacheDefinition[Any], key: str) -> None: ...

python_ddd_framework/caching/errors.py

@@ -0,0 +1,20 @@
+"""Typed distributed cache definition 与 serialization failures。"""
+
+from __future__ import annotations
+
+from ..errors.base import FrameworkError
+
+
+class CacheDefinitionError(FrameworkError):
+    def __init__(self, *, cache: str, reason: str) -> None:
+        self.cache = cache
+        self.reason = reason
+        super().__init__(f"Invalid cache {cache!r}: {reason}")
+
+
+class DistributedCacheError(FrameworkError):
+    def __init__(self, *, operation: str, cache: str, error_type: str) -> None:
+        self.operation = operation
+        self.cache = cache
+        self.error_type = error_type
+        super().__init__(f"Distributed cache {operation} failed for {cache!r} with {error_type}")

python_ddd_framework/cli/__init__.py

@@ -0,0 +1,105 @@
+"""pddd 的轻量 argparse 入口；只有生成命令才加载 Developer Kit。"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import subprocess
+from collections.abc import Sequence
+from enum import Enum
+from pathlib import Path
+
+from ..hosting import ENVIRONMENT_VARIABLE as ENVIRONMENT_VARIABLE
+from .errors import CommandError
+
+
+class _Command(str, Enum):
+    NEW = "new"
+    ADD = "add"
+    DEV = "dev"
+    DEV_INIT = "dev-init"
+    DB = "db"
+    INSPECT = "inspect"
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pddd", description="Tools for modular DDD applications")
+    commands = parser.add_subparsers(dest="command", title="commands")
+    new = commands.add_parser(_Command.NEW.value, help="Create a project from bundled templates")
+    new.add_argument("name")
+    new.add_argument("--framework-wheel", type=Path, help="Validate with a local framework wheel")
+    new.add_argument("--dry-run", action="store_true")
+    add = commands.add_parser(
+        _Command.ADD.value, help="Add a business module to the current project"
+    ).add_subparsers(dest="kind", required=True)
+    module = add.add_parser("module", help="Generate and register a business module")
+    module.add_argument("name")
+    module.add_argument("--dry-run", action="store_true")
+    dev = commands.add_parser(_Command.DEV.value, help="Run the development web server")
+    dev.add_argument("--host", default="127.0.0.1")
+    dev.add_argument("--port", type=int, default=8000)
+    for command, description in (
+        (_Command.DEV_INIT, "Prepare local development infrastructure"),
+        (_Command.DB, "Manage module migrations and seed data"),
+        (_Command.INSPECT, "Inspect modules, services and redacted configuration"),
+    ):
+        action = commands.add_parser(command.value, help=description, description=description)
+        action.add_argument(
+            "--environment",
+            default=os.environ.get(ENVIRONMENT_VARIABLE, "development"),
+            help="Host environment (default: %(default)s)",
+        )
+        if command is _Command.DB:
+            action.add_argument("operation", choices=("revision", "upgrade", "status", "seed"))
+            action.add_argument("--module", required=True)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 0
+    try:
+        return _execute(args)
+    except CommandError as error:
+        parser.exit(2, f"pddd: {error}\n")
+    except subprocess.CalledProcessError as error:
+        parser.exit(
+            error.returncode, "pddd: external command failed; diagnostic files were retained\n"
+        )
+
+
+def _execute(args: argparse.Namespace) -> int:
+    command = _Command(args.command)
+    if command in (_Command.NEW, _Command.ADD):
+        try:
+            from ..developer_kit.generation import add_module, new_project
+        except ModuleNotFoundError as error:
+            if error.name not in {"cookiecutter", "libcst"}:
+                raise
+            raise CommandError(
+                "Install python-ddd-framework[developer-kit] to use generation commands"
+            ) from None
+        if command is _Command.NEW:
+            new_project(args.name, args.framework_wheel, args.dry_run)
+        else:
+            add_module(args.name, args.dry_run)
+    else:
+        from .runtime import database, development_server
+
+        if command is _Command.DEV:
+            development_server(args.host, args.port)
+        elif command is _Command.DEV_INIT:
+            from .development import dev_init
+
+            asyncio.run(dev_init(args.environment))
+        elif command is _Command.INSPECT:
+            from .inspection import inspect_application
+
+            asyncio.run(inspect_application(args.environment))
+        else:
+            asyncio.run(database(args.operation, args.environment, args.module))
+    return 0

python_ddd_framework/cli/development.py

@@ -0,0 +1,85 @@
+"""开发依赖的 Compose 接线；配置只来自当前 Host 构建出的快照。"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+from ..application import Application
+from .errors import CommandError
+from .project import Project
+
+
+async def dev_init(environment: str) -> None:
+    if environment != "development":
+        raise CommandError("dev-init is only available in the development environment")
+    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:
+        subprocess.run(
+            [
+                "docker",
+                "compose",
+                "-f",
+                str(project.root / "compose.dev.yaml"),
+                "up",
+                "-d",
+                "--wait",
+            ],
+            cwd=project.root,
+            env=_compose_environment(application),
+            check=True,
+        )
+    finally:
+        # build 只组合，关闭仍交给 Application；解析和子进程失败也不得遗留 APP owner。
+        await application.stop()
+
+
+def _compose_environment(application: Application) -> dict[str, str]:
+    from sqlalchemy.engine import make_url
+    from sqlalchemy.exc import ArgumentError
+
+    from ..redis import RedisOptions
+    from ..sqlalchemy import ConnectionStringsOptions
+
+    try:
+        postgres = make_url(
+            application.options.get(ConnectionStringsOptions).default.get_secret_value()
+        )
+        redis = make_url(application.options.get(RedisOptions).url.get_secret_value())
+        images = {
+            "POSTGRES_IMAGE": application.configuration.get_path(
+                "development.compose.postgres_image"
+            ),
+            "REDIS_IMAGE": application.configuration.get_path("development.compose.redis_image"),
+        }
+        if any(not isinstance(value, str) or not value.strip() for value in images.values()):
+            raise ValueError("Compose images require non-empty strings")
+        # 模板只提供本机 TCP 依赖，拒绝无法兑现的远端、TLS 或查询参数覆盖。
+        for url in (postgres, redis):
+            if url.host not in ("127.0.0.1", "localhost") or not url.port or url.query:
+                raise ValueError("Compose requires local URLs with explicit ports and no query")
+        if not postgres.username or not postgres.password or not postgres.database:
+            raise ValueError("PostgreSQL URL requires credentials and database")
+        if redis.drivername != "redis" or redis.username or redis.password:
+            raise ValueError("Development Redis requires a plain local connection")
+    except (ArgumentError, KeyError, TypeError, ValueError):
+        # 原生 parser 异常可能包含完整 URL，CLI 只公开需要检查的配置位置。
+        raise CommandError(
+            "Invalid development Compose configuration; check connection_strings.default, "
+            "redis.url and development.compose (local URLs require explicit ports)"
+        ) from None
+    environment = dict(os.environ)
+    environment.pop("COMPOSE_ENV_FILES", None)
+    environment.update(
+        COMPOSE_DISABLE_ENV_FILE="1",
+        POSTGRES_DB=postgres.database,
+        POSTGRES_USER=postgres.username,
+        POSTGRES_PASSWORD=postgres.password,
+        POSTGRES_PORT=str(postgres.port),
+        REDIS_PORT=str(redis.port),
+    )
+    environment.update({key: str(value) for key, value in images.items()})
+    return environment

python_ddd_framework/cli/errors.py

@@ -0,0 +1,5 @@
+"""CLI 可直接展示的操作诊断；依赖命令的退出码由调用方保留。"""
+
+
+class CommandError(Exception):
+    pass