python-platform 0.1.1__py3-none-any.whl

python_platform/background_workers/runtime.py

@@ -0,0 +1,203 @@
+"""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,
+    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 for item in worker_catalog.definitions}, options.workers
+        )
+        self._register_tasks("job", {item.name 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, names: set[str], configured: Mapping[str, BackgroundTaskOptions]
+    ) -> None:
+        unknown = set(configured) - names
+        if unknown:
+            raise ValueError(f"Unknown background {kind} configuration: {sorted(unknown)}")
+        for name in sorted(names):
+            key = f"{kind}:{name}"
+            options = configured.get(name, BackgroundTaskOptions())
+            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_platform/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_platform/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_platform/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_platform/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_platform/cli/__init__.py

@@ -0,0 +1,87 @@
+"""pp 的轻量 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"
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pp")
+    commands = parser.add_subparsers(dest="command", required=True)
+    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).add_subparsers(dest="kind", required=True)
+    module = add.add_parser("module")
+    module.add_argument("name")
+    module.add_argument("--dry-run", action="store_true")
+    dev = commands.add_parser(_Command.DEV.value)
+    dev.add_argument("--host", default="127.0.0.1")
+    dev.add_argument("--port", type=int, default=8000)
+    for command in (_Command.DEV_INIT, _Command.DB):
+        action = commands.add_parser(command.value)
+        action.add_argument(
+            "--environment", default=os.environ.get(ENVIRONMENT_VARIABLE, "development")
+        )
+        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)
+    try:
+        return _execute(args)
+    except CommandError as error:
+        parser.exit(2, f"pp: {error}\n")
+    except subprocess.CalledProcessError as error:
+        parser.exit(
+            error.returncode, "pp: 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-platform[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, dev_init, development_server
+
+        if command is _Command.DEV:
+            development_server(args.host, args.port)
+        elif command is _Command.DEV_INIT:
+            asyncio.run(dev_init(args.environment))
+        else:
+            asyncio.run(database(args.operation, args.environment, args.module))
+    return 0

python_platform/cli/errors.py

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

python_platform/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_platform.hosts"
+MODULE_ENTRY_POINT_GROUP = "python_platform.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 pp"
+            ) 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_platform/cli/runtime.py

@@ -0,0 +1,68 @@
+"""项目运行命令只编排正式 Host、迁移与 seed，不拥有业务初始化规则。"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+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")
+
+
+async def dev_init(environment: str) -> None:
+    if environment != "development":
+        raise CommandError("dev-init is only available in the development environment")
+    project = Project.current()
+    subprocess.run(
+        ["docker", "compose", "-f", str(project.root / "compose.dev.yaml"), "up", "-d", "--wait"],
+        cwd=project.root,
+        check=True,
+    )
+
+
+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_platform/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",
+)