python-platform 0.1.1__py3-none-any.whl

python_platform/developer_kit/templates/project/{{cookiecutter.project_name}}/tests/host/test_http.py.jinja

@@ -0,0 +1,101 @@
+"""真实 Host 工作流；先按 README 生成并审查各业务模块 revision。"""
+
+from importlib.metadata import distribution
+from pathlib import Path
+
+from dotenv import dotenv_values
+from host.main import create_web
+from host.module import {{ cookiecutter.class_prefix }}HostModule
+from httpx import ASGITransport, AsyncClient
+from testcontainers.community.postgres import PostgresContainer
+from testcontainers.community.redis import RedisContainer
+
+from python_platform import ApplicationBuilder, DataSeeder
+from python_platform.sqlalchemy import SqlAlchemyMigrator
+from python_platform.testing import TestApplication as PlatformTestApplication
+
+
+async def test_host_http_workflow(monkeypatch):
+    configuration = dotenv_values(Path.cwd() / ".env")
+    with PostgresContainer(configuration["POSTGRES_IMAGE"], driver="asyncpg") as postgres:
+        with RedisContainer(configuration["REDIS_IMAGE"]) as redis:
+            monkeypatch.setenv(
+                "PP_CONNECTION_STRINGS__DEFAULT", postgres.get_connection_url(driver="asyncpg")
+            )
+            monkeypatch.setenv(
+                "PP_REDIS__URL",
+                f"redis://{redis.get_container_host_ip()}:{redis.get_exposed_port(redis.port)}/0",
+            )
+            test_application = PlatformTestApplication(
+                ApplicationBuilder(
+                    {{ cookiecutter.class_prefix }}HostModule,
+                    environment="development",
+                    base_path=Path.cwd(),
+                    env_prefix="PP_",
+                    dotenv_path=Path.cwd() / ".env",
+                    explicit_overrides={"logging": {"format": "text"}},
+                )
+            )
+            application = test_application.build()
+            try:
+                await SqlAlchemyMigrator(application).upgrade_heads()
+                await test_application.start()
+                await DataSeeder(application).seed_all()
+            finally:
+                await test_application.stop()
+            web = create_web()
+            async with web.router.lifespan_context(web):
+                async with AsyncClient(
+                    transport=ASGITransport(web), base_url="http://test"
+                ) as client:
+                    assert (await client.get("/health/ready")).status_code == 200
+                    login = await client.post(
+                        "/api/auth/login",
+                        json={
+                            "username": configuration["PP_IDENTITY__SEED_ADMIN_USERNAME"],
+                            "password": configuration["PP_IDENTITY__SEED_ADMIN_PASSWORD"],
+                        },
+                    )
+                    assert login.status_code == 200
+                    client.headers["Authorization"] = "Bearer " + login.json()["access_token"]
+                    modules = (
+                        entry.name
+                        for entry in distribution("{{ cookiecutter.project_name }}").entry_points
+                        if entry.group == "python_platform.modules"
+                    )
+                    for module in modules:
+                        path = f"/api/{module}"
+                        created = await client.post(path, json={"title": "Sample order"})
+                        assert created.status_code == 201
+                        order = created.json()
+                        assert (await client.get(f"{path}/{order['id']}")).json() == order
+                        approved = await client.post(
+                            f"{path}/{order['id']}/approve",
+                            json={"expected_version": order["version"]},
+                        )
+                        assert (
+                            approved.status_code == 200 and approved.json()["status"] == "approved"
+                        )
+                        conflict = await client.post(
+                            f"{path}/{order['id']}/approve",
+                            json={"expected_version": order["version"]},
+                        )
+                        assert conflict.status_code == 409
+                        assert (await client.get(f"{path}/{order['id']}")).json()[
+                            "status"
+                        ] == "approved"
+                        settings_path = f"/api/settings/{module}.approval_enabled"
+                        setting = (await client.get(settings_path)).json()
+                        assert (
+                            await client.put(
+                                settings_path,
+                                json={"value": False, "expected_version": setting["version"]},
+                            )
+                        ).status_code == 200
+                        second = (await client.post(path, json={"title": "Second"})).json()
+                        assert (
+                            await client.post(
+                                f"{path}/{second['id']}/approve",
+                                json={"expected_version": second["version"]},
+                            )
+                        ).status_code == 400

python_platform/developer_kit/wiring.py

@@ -0,0 +1,85 @@
+"""LibCST 只修改已识别 startup class 的依赖；不重写用户文件的格式和注释。"""
+
+from __future__ import annotations
+
+from typing import cast
+
+import libcst as cst
+import libcst.matchers as matchers
+from libcst.codemod import CodemodContext
+from libcst.codemod.visitors import AddImportsVisitor
+from libcst.metadata import ClassScope, MetadataWrapper, ScopeProvider
+
+from ..cli.errors import CommandError
+
+
+class _AddDependency(cst.CSTTransformer):
+    def __init__(self, startup: cst.ClassDef, dependency: str) -> None:
+        self._startup = startup
+        self._dependency = dependency
+        self.matches = 0
+
+    def leave_ClassDef(
+        self, original_node: cst.ClassDef, updated_node: cst.ClassDef
+    ) -> cst.ClassDef:
+        if original_node is not self._startup:
+            return updated_node
+        body = cast(cst.IndentedBlock, updated_node.body)
+        statements = list(body.body)
+        for index, statement in enumerate(statements):
+            if not isinstance(statement, cst.SimpleStatementLine) or len(statement.body) != 1:
+                continue
+            assignment = statement.body[0]
+            if isinstance(assignment, cst.Assign) and len(assignment.targets) == 1:
+                target = assignment.targets[0].target
+            elif isinstance(assignment, cst.AnnAssign):
+                target = assignment.target
+            else:
+                continue
+            if not isinstance(target, cst.Name) or target.value != "dependencies":
+                continue
+            value = assignment.value
+            if not isinstance(value, cst.Tuple) or any(
+                isinstance(item, cst.StarredElement) for item in value.elements
+            ):
+                raise CommandError(
+                    "Startup dependencies must be an explicit tuple without unpacking"
+                )
+            self.matches += 1
+            replacement = value.with_changes(
+                elements=(*value.elements, cst.Element(cst.Name(self._dependency)))
+            )
+            statements[index] = statement.with_changes(
+                body=(assignment.with_changes(value=replacement),)
+            )
+        return updated_node.with_changes(body=body.with_changes(body=statements))
+
+
+def add_dependency(source: str, startup: str, import_path: str, dependency: str) -> str:
+    wrapper = MetadataWrapper(cst.parse_module(source))
+    module = wrapper.module
+    # 星号导出的绑定无法由静态 scope 确定，不能冒险覆盖用户的既有依赖。
+    if matchers.findall(module, matchers.ImportStar()):
+        raise CommandError("Star imports prevent safe startup dependency wiring")
+    # 原生作用域绑定防止覆盖用户符号；仅修改实际顶层节点，不触及嵌套同名类。
+    candidates = tuple(
+        statement
+        for statement in module.body
+        if isinstance(statement, cst.ClassDef) and statement.name.value == startup
+    )
+    if len(candidates) != 1:
+        raise CommandError("Startup Module must be a unique top-level class")
+    candidate = candidates[0]
+    if not isinstance(candidate.body, cst.IndentedBlock):
+        raise CommandError("Startup Module must use an indented class body")
+    # 类体的名称查找包含本类和外层模块；两层绑定均不得被新增裸名称遮蔽。
+    scope = cast(ClassScope, wrapper.resolve(ScopeProvider)[candidate.body.body[0]])
+    if dependency in scope:
+        raise CommandError(f"Dependency name already bound in startup module: {dependency}")
+    transformer = _AddDependency(candidate, dependency)
+    updated = module.visit(transformer)
+    if transformer.matches != 1:
+        raise CommandError("Cannot uniquely identify the startup Module dependencies assignment")
+    context = CodemodContext()
+    AddImportsVisitor.add_needed_import(context, import_path, dependency)
+    return AddImportsVisitor(context).transform_module(updated).code

python_platform/diagnostics/__init__.py

@@ -0,0 +1,23 @@
+"""Diagnostic contracts 与 Application-owned journal 的 capability 边界。"""
+
+from .model import (
+    DiagnosticMessage,
+    DiagnosticSnapshot,
+    EventStatus,
+    FailureRecord,
+    LifecyclePhase,
+    LifecycleStage,
+    PhaseEvent,
+    SourceLocation,
+)
+
+__all__ = (
+    "DiagnosticMessage",
+    "DiagnosticSnapshot",
+    "EventStatus",
+    "FailureRecord",
+    "LifecyclePhase",
+    "LifecycleStage",
+    "PhaseEvent",
+    "SourceLocation",
+)

python_platform/diagnostics/journal.py

@@ -0,0 +1,174 @@
+"""单个 Application 拥有的 append-only diagnostic journal。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from time import perf_counter_ns
+from uuid import UUID, uuid4
+
+from ..errors import InvalidDiagnosticCodeError
+from .model import (
+    DiagnosticMessage,
+    DiagnosticSnapshot,
+    EventStatus,
+    FailureRecord,
+    LifecyclePhase,
+    LifecycleStage,
+    PhaseEvent,
+    SourceLocation,
+)
+
+_DIAGNOSTIC_CODE_PUNCTUATION = frozenset("._-")
+_MAX_DIAGNOSTIC_CODE_LENGTH = 128
+
+
+@dataclass(frozen=True, slots=True)
+class _ActiveEvent:
+    phase: LifecyclePhase
+    stage: LifecycleStage
+    subject: str
+    source: SourceLocation | None
+    started_ns: int
+
+
+class _DiagnosticJournal:
+    """Application-owned journal；外部只能取得不可变的时点快照。"""
+
+    __slots__ = ("_events", "_failure_order", "_failures", "_messages", "_sequence")
+
+    def __init__(self) -> None:
+        self._sequence = 0
+        self._events: list[PhaseEvent] = []
+        self._messages: list[DiagnosticMessage] = []
+        self._failure_order: list[UUID] = []
+        self._failures: dict[UUID, FailureRecord] = {}
+
+    def _next_sequence(self) -> int:
+        self._sequence += 1
+        return self._sequence
+
+    def start_event(
+        self,
+        *,
+        phase: LifecyclePhase,
+        stage: LifecycleStage,
+        subject: str,
+        source: SourceLocation | None,
+    ) -> _ActiveEvent:
+        started_ns = perf_counter_ns()
+        active_event = _ActiveEvent(phase, stage, subject, source, started_ns)
+        self._events.append(
+            PhaseEvent(
+                sequence=self._next_sequence(),
+                phase=phase,
+                stage=stage,
+                subject=subject,
+                status=EventStatus.STARTED,
+                started_monotonic_ns=started_ns,
+                duration_ns=None,
+                source=source,
+                failure_id=None,
+            )
+        )
+        return active_event
+
+    def finish_event(
+        self,
+        active_event: _ActiveEvent,
+        *,
+        status: EventStatus,
+        failure_id: UUID | None,
+    ) -> int:
+        # start 返回的 value object 是一次事件的唯一事实，finish 不重复传递上下文。
+        duration_ns = perf_counter_ns() - active_event.started_ns
+        self._events.append(
+            PhaseEvent(
+                sequence=self._next_sequence(),
+                phase=active_event.phase,
+                stage=active_event.stage,
+                subject=active_event.subject,
+                status=status,
+                started_monotonic_ns=active_event.started_ns,
+                duration_ns=duration_ns,
+                source=active_event.source,
+                failure_id=failure_id,
+            )
+        )
+        return duration_ns
+
+    def begin_failure(
+        self,
+        *,
+        error_type: str,
+        phase: LifecyclePhase,
+        stage: LifecycleStage,
+        subject: str | None,
+        message: str,
+        source: SourceLocation | None,
+        dependency_path: tuple[str, ...],
+    ) -> UUID:
+        failure_id = uuid4()
+        # 先发布不可变记录，rollback 后替换 cleanup 关联，snapshot 不出现悬空引用。
+        failure = FailureRecord(
+            id=failure_id,
+            error_type=error_type,
+            phase=phase,
+            stage=stage,
+            subject=subject,
+            message=message,
+            source=source,
+            dependency_path=dependency_path,
+            cleanup_failure_ids=(),
+        )
+        self._failure_order.append(failure_id)
+        self._failures[failure_id] = failure
+        return failure_id
+
+    def complete_failure(
+        self,
+        failure_id: UUID,
+        *,
+        cleanup_failure_ids: tuple[UUID, ...] = (),
+    ) -> None:
+        self._failures[failure_id] = replace(
+            self._failures[failure_id], cleanup_failure_ids=cleanup_failure_ids
+        )
+
+    def emit(
+        self,
+        *,
+        phase: LifecyclePhase,
+        stage: LifecycleStage,
+        subject: str,
+        code: str,
+        source: SourceLocation | None,
+    ) -> None:
+        if not _is_diagnostic_code(code):
+            raise InvalidDiagnosticCodeError(code, max_length=_MAX_DIAGNOSTIC_CODE_LENGTH)
+        self._messages.append(
+            DiagnosticMessage(
+                sequence=self._next_sequence(),
+                phase=phase,
+                stage=stage,
+                subject=subject,
+                code=code,
+                source=source,
+            )
+        )
+
+    def snapshot(self, application_id: UUID) -> DiagnosticSnapshot:
+        failures = tuple(self._failures[failure_id] for failure_id in self._failure_order)
+        return DiagnosticSnapshot(
+            application_id=application_id,
+            events=tuple(self._events),
+            failures=failures,
+            messages=tuple(self._messages),
+        )
+
+
+def _is_diagnostic_code(code: str) -> bool:
+    if not code or len(code) > _MAX_DIAGNOSTIC_CODE_LENGTH or not code[0].isalpha():
+        return False
+    return all(
+        character.isalnum() or character in _DIAGNOSTIC_CODE_PUNCTUATION for character in code
+    )

python_platform/diagnostics/model.py

@@ -0,0 +1,83 @@
+"""不可变 diagnostic contract；不拥有 journal mutation。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from uuid import UUID
+
+
+class LifecyclePhase(str, Enum):
+    COMPOSITION = "composition"
+    RUNTIME = "runtime"
+    CLEANUP = "cleanup"
+
+
+class LifecycleStage(str, Enum):
+    PRE_CONFIGURE = "pre_configure"
+    CONFIGURE = "configure"
+    POST_CONFIGURE = "post_configure"
+    PRE_INITIALIZE = "pre_initialize"
+    INITIALIZE = "initialize"
+    POST_INITIALIZE = "post_initialize"
+    SHUTDOWN = "shutdown"
+
+
+class EventStatus(str, Enum):
+    STARTED = "started"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True, slots=True)
+class SourceLocation:
+    owner: str
+    file: str | None
+    line: int | None
+    symbol: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class PhaseEvent:
+    sequence: int
+    phase: LifecyclePhase
+    stage: LifecycleStage
+    subject: str
+    status: EventStatus
+    started_monotonic_ns: int
+    duration_ns: int | None
+    source: SourceLocation | None
+    failure_id: UUID | None
+
+
+@dataclass(frozen=True, slots=True)
+class FailureRecord:
+    id: UUID
+    error_type: str
+    phase: LifecyclePhase
+    stage: LifecycleStage
+    subject: str | None
+    message: str
+    source: SourceLocation | None
+    dependency_path: tuple[str, ...]
+    cleanup_failure_ids: tuple[UUID, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class DiagnosticMessage:
+    sequence: int
+    phase: LifecyclePhase
+    stage: LifecycleStage
+    subject: str
+    code: str
+    source: SourceLocation | None
+
+
+@dataclass(frozen=True, slots=True)
+class DiagnosticSnapshot:
+    """一次读取产生的不可变诊断视图，不随后续 lifecycle 变化。"""
+
+    application_id: UUID
+    events: tuple[PhaseEvent, ...]
+    failures: tuple[FailureRecord, ...]
+    messages: tuple[DiagnosticMessage, ...]

python_platform/diagnostics/source.py

@@ -0,0 +1,25 @@
+"""贡献诊断的调用位置；depth 由公开贡献入口指定。"""
+
+from __future__ import annotations
+
+import inspect
+
+from .model import SourceLocation
+
+
+def caller_source(owner: str, *, depth: int) -> SourceLocation:
+    frame = inspect.currentframe()
+    try:
+        for _ in range(depth):
+            frame = None if frame is None else frame.f_back
+        if frame is None:
+            return SourceLocation(owner=owner, file=None, line=None, symbol=None)
+        return SourceLocation(
+            owner=owner,
+            file=frame.f_code.co_filename,
+            line=frame.f_lineno,
+            symbol=frame.f_code.co_name,
+        )
+    finally:
+        # 不让 frame 引用延长 Module/composition 对象的生命周期。
+        del frame

python_platform/distributed_lock/__init__.py

@@ -0,0 +1,6 @@
+"""Provider-neutral 业务互斥与租约失败契约。"""
+
+from .contracts import DistributedLock, DistributedLockError
+from .options import DistributedLockOptions
+
+__all__ = ("DistributedLock", "DistributedLockError", "DistributedLockOptions")

python_platform/distributed_lock/contracts.py

@@ -0,0 +1,20 @@
+"""锁的业务使用与错误边界；provider 不进入稳定契约。"""
+
+from contextlib import AbstractAsyncContextManager
+from typing import Protocol
+
+from ..errors.base import FrameworkError
+
+
+class DistributedLock(Protocol):
+    def acquire(self, key: str, /) -> AbstractAsyncContextManager[bool]:
+        """进入后返回是否取得锁；持有者必须配合取消并在退出上下文前完成清理。"""
+        ...
+
+
+class DistributedLockError(FrameworkError):
+    def __init__(self, *, key: str, operation: str, error_type: str) -> None:
+        self.key = key
+        self.operation = operation
+        self.error_type = error_type
+        super().__init__(f"Distributed lock {key!r} {operation} failed with {error_type}")

python_platform/distributed_lock/options.py

@@ -0,0 +1,19 @@
+"""获取等待和租约时序的唯一默认值来源。"""
+
+from datetime import timedelta
+
+from pydantic import Field, model_validator
+
+from ..options import BaseOptions
+
+
+class DistributedLockOptions(BaseOptions):
+    wait_timeout: timedelta = Field(default=timedelta(seconds=5), ge=timedelta(0))
+    lease_timeout: timedelta = Field(default=timedelta(seconds=30), ge=timedelta(milliseconds=1))
+    renewal_interval: timedelta = Field(default=timedelta(seconds=10), ge=timedelta(milliseconds=1))
+
+    @model_validator(mode="after")
+    def _validate_renewal(self) -> "DistributedLockOptions":
+        if self.renewal_interval >= self.lease_timeout:
+            raise ValueError("renewal_interval must be shorter than lease_timeout")
+        return self

python_platform/domain/__init__.py

@@ -0,0 +1,13 @@
+"""Provider-neutral DDD foundations owned by Python Platform."""
+
+from .aggregates import AggregateRoot
+from .entities import Entity
+from .errors import OptimisticConcurrencyError
+from .value_objects import ValueObject
+
+__all__ = (
+    "AggregateRoot",
+    "Entity",
+    "OptimisticConcurrencyError",
+    "ValueObject",
+)

python_platform/domain/aggregates.py

@@ -0,0 +1,64 @@
+"""Aggregate identity, version and pending local-event ownership."""
+
+from __future__ import annotations
+
+from dataclasses import is_dataclass
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+from .entities import Entity
+from .errors import OptimisticConcurrencyError
+
+_TId = TypeVar("_TId")
+
+
+class AggregateRoot(Entity[_TId], Generic[_TId]):
+    """一个 invocation 内聚合版本和待提交事件的唯一 mutable owner。"""
+
+    __slots__ = ("_local_events", "_version", "_version_staged")
+
+    def __init__(self, entity_id: _TId, *, version: int = 0) -> None:
+        super().__init__(entity_id)
+        if not isinstance(version, int) or isinstance(version, bool) or version < 0:
+            raise ValueError("aggregate version must be a non-negative integer")
+        self._version = version
+        self._version_staged = False
+        self._local_events: list[object] = []
+
+    @property
+    def version(self) -> int:
+        return self._version
+
+    def raise_local_event(self, event: object) -> None:
+        if not _is_immutable_event(event):
+            raise TypeError("aggregate local events must be immutable dataclass or Pydantic values")
+        self._local_events.append(event)
+
+    def release_local_events(self) -> tuple[object, ...]:
+        events = tuple(self._local_events)
+        self._local_events.clear()
+        return events
+
+    def stage_next_version(self, expected_version: int) -> int:
+        """Repository SPI：一次聚合实例只允许暂存一个下一版本。"""
+
+        if (
+            not isinstance(expected_version, int)
+            or isinstance(expected_version, bool)
+            or expected_version < 0
+        ):
+            raise ValueError("expected_version must be a non-negative integer")
+        if self._version_staged or self._version != expected_version:
+            raise OptimisticConcurrencyError
+        self._version += 1
+        self._version_staged = True
+        return self._version
+
+
+def _is_immutable_event(event: object) -> bool:
+    event_type = type(event)
+    dataclass_parameters = getattr(event_type, "__dataclass_params__", None)
+    if is_dataclass(event) and bool(getattr(dataclass_parameters, "frozen", False)):
+        return True
+    return isinstance(event, BaseModel) and event.model_config.get("frozen") is True

python_platform/domain/entities.py

@@ -0,0 +1,33 @@
+"""Entity identity semantics independent from persistence providers."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+_TId = TypeVar("_TId")
+
+
+class Entity(Generic[_TId]):
+    """Identity owner whose identifier cannot change after construction."""
+
+    __slots__ = ("_id",)
+
+    def __init__(self, entity_id: _TId) -> None:
+        if entity_id is None:
+            raise ValueError("entity id cannot be None")
+        self._id = entity_id
+
+    @property
+    def id(self) -> _TId:
+        return self._id
+
+    def __eq__(self, other: object) -> bool:
+        if self is other:
+            return True
+        if type(self) is not type(other):
+            return False
+        return self.id == other.id
+
+    def __hash__(self) -> int:
+        # 类型是 identity 的一部分，避免不同聚合偶然共用相同标识时发生碰撞语义。
+        return hash((type(self), self.id))

python_platform/domain/errors.py

@@ -0,0 +1,12 @@
+"""DDD boundary failures safe for transport mapping."""
+
+from __future__ import annotations
+
+from ..errors import ResourceConflictError
+
+
+class OptimisticConcurrencyError(ResourceConflictError):
+    """调用方版本与持久化 authority 不一致；不携带真实行版本或 SQL。"""
+
+    def __init__(self) -> None:
+        super().__init__("Aggregate version conflict")