python-platform 0.1.1__py3-none-any.whl

python_platform/unit_of_work/manager.py

@@ -0,0 +1,210 @@
+"""Application-owned ambient UoW 与取消监督；不捕获 Session。"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+from dishka import Scope
+
+from ..invocation import ApplicationInvocationContext
+from .contracts import UnitOfWork, _UnitOfWorkFactory, _UnitOfWorkParticipant
+from .options import (
+    UnitOfWorkDeclaration,
+    UnitOfWorkOptions,
+    UnitOfWorkTransactionBehavior,
+    _ResolvedUnitOfWorkOptions,
+)
+
+if TYPE_CHECKING:
+    from ..application_services.invocation import _InvocationRuntime
+    from ..events import LocalEventCatalog
+
+
+class UnitOfWorkManager:
+    def __init__(
+        self,
+        runtime: _InvocationRuntime,
+        factory: _UnitOfWorkFactory,
+        options: UnitOfWorkOptions,
+        catalog: LocalEventCatalog,
+    ) -> None:
+        self._runtime = runtime
+        self._factory = factory
+        self._options = options
+        self._catalog = catalog
+        self._ambient: ContextVar[UnitOfWork | None] = ContextVar(
+            f"python_platform_uow_{runtime.application_id}", default=None
+        )
+
+    @property
+    def current(self) -> UnitOfWork | None:
+        work = self._ambient.get()
+        if work is not None:
+            work._require_active("current", allow_completing=True)
+        return work
+
+    def require_current(self, *, transactional: bool = False) -> UnitOfWork:
+        work = self.current
+        if work is None:
+            raise RuntimeError("operation requires an active UnitOfWork")
+        if transactional and not work.is_transactional:
+            raise RuntimeError("operation requires a transactional UnitOfWork")
+        return work
+
+    def _resolve_options(
+        self, connection_name: str | None, declaration: UnitOfWorkDeclaration, method_name: str
+    ) -> _ResolvedUnitOfWorkOptions:
+        from ..application_services.contracts import (
+            _DEFAULT_CONNECTION_NAME,
+            _validate_connection_name,
+        )
+
+        ambient = self.current
+        execution = self._runtime.current()
+        connection = (
+            connection_name
+            if connection_name is not None
+            else (
+                ambient.connection_name
+                if ambient is not None
+                else (
+                    execution.context.connection_name
+                    if execution is not None
+                    else _DEFAULT_CONNECTION_NAME
+                )
+            )
+        )
+        transactional = declaration.is_transactional
+        if transactional is None:
+            behavior = self._options.transaction_behavior
+            if behavior is UnitOfWorkTransactionBehavior.AUTO:
+                verb = self._runtime.http_method()
+                transactional = (
+                    verb != "GET"
+                    if verb is not None
+                    else not (method_name == "get" or method_name.startswith("get_"))
+                )
+            else:
+                transactional = behavior is UnitOfWorkTransactionBehavior.ENABLED
+        return _ResolvedUnitOfWorkOptions(
+            _validate_connection_name(connection),
+            transactional,
+            declaration.isolation_level or self._options.isolation_level,
+            declaration.command_timeout_ms
+            if declaration.command_timeout_ms is not None
+            else self._options.command_timeout_ms,
+        )
+
+    @asynccontextmanager
+    async def begin(
+        self,
+        *,
+        requires_new: bool = False,
+        connection_name: str | None = None,
+        is_transactional: bool | None = None,
+        isolation_level: str | None = None,
+        command_timeout_ms: int | None = None,
+    ) -> AsyncIterator[UnitOfWork]:
+        declaration = UnitOfWorkDeclaration(
+            is_transactional=is_transactional,
+            isolation_level=isolation_level,
+            command_timeout_ms=command_timeout_ms,
+        )
+        options = self._resolve_options(connection_name, declaration, "begin")
+        async with self._begin(options, requires_new=requires_new) as work:
+            yield work
+
+    def _check_current(self, connection_name: str) -> UnitOfWork | None:
+        from ..application_services.errors import NestedConnectionError
+
+        outer = self.current
+        # disabled 只控制自动创建；参与外层仍须满足同 task、有效状态与同连接。
+        if outer is not None and outer.connection_name != connection_name:
+            raise NestedConnectionError(outer=outer.connection_name, requested=connection_name)
+        return outer
+
+    @asynccontextmanager
+    async def _begin(
+        self, options: _ResolvedUnitOfWorkOptions, *, requires_new: bool = False
+    ) -> AsyncIterator[UnitOfWork]:
+        outer = self.current if requires_new else self._check_current(options.connection_name)
+        if outer is not None and not requires_new:
+            participant = _UnitOfWorkParticipant(outer)
+            try:
+                yield participant
+            finally:
+                participant._released = True
+            return
+        async with self._runtime.outer_lease():
+            async with self._own_work(options) as work:
+                yield work
+
+    @asynccontextmanager
+    async def _own_work(self, options: _ResolvedUnitOfWorkOptions) -> AsyncIterator[UnitOfWork]:
+        from ..application_services.errors import ApplicationInvocationCleanupError
+        from ..events.runtime import _LocalEventQueue
+
+        execution = self._runtime.current()
+        container = (
+            execution.action_container
+            if execution is not None
+            else self._runtime.current_call_scope()
+        )
+        if container is None:
+            raise RuntimeError("UnitOfWork.begin requires a managed execution scope")
+        context = ApplicationInvocationContext(
+            application_id=self._runtime.application_id,
+            invocation_id=uuid4(),
+            parent_invocation_id=execution.context.invocation_id if execution else None,
+            connection_name=options.connection_name,
+        )
+        work = self._factory.create()
+        work._options = options
+        work._event_queue = _LocalEventQueue(container, context, self._catalog)
+
+        async def after_commit() -> None:
+            # 新服务调用既不能复用旧事务，也不能落入旧 ACTION 的对象缓存。
+            token = self._ambient.set(None)
+            parent = container.parent_container if container.scope is Scope.ACTION else container
+            assert parent is not None
+            try:
+                with self._runtime.detached_execution(parent):
+                    assert work._event_queue is not None
+                    await work._event_queue._dispatch_after_commit()
+            finally:
+                self._ambient.reset(token)
+
+        work._after_commit = after_commit
+        token = self._ambient.set(work)
+        primary: BaseException | None = None
+        try:
+            yield work
+        except BaseException as error:
+            primary = error
+        finally:
+            # 仅原生资源 I/O 移入受监督 task；ContextVar token 始终由原 task 恢复。
+            cleanup = asyncio.create_task(work._cleanup())
+            try:
+                while not cleanup.done():
+                    try:
+                        await asyncio.shield(cleanup)
+                    except asyncio.CancelledError as cancellation:
+                        if primary is None:
+                            primary = cancellation
+                cleanup.result()
+            finally:
+                self._ambient.reset(token)
+        if work.cleanup_failures:
+            failure = ApplicationInvocationCleanupError(
+                primary=primary, cleanup_failures=work.cleanup_failures, committed=work.committed
+            )
+            if isinstance(primary, asyncio.CancelledError):
+                raise primary from failure
+            raise failure from (primary or work.cleanup_failures[0])
+        if primary is not None:
+            raise primary

python_platform/unit_of_work/options.py

@@ -0,0 +1,92 @@
+"""UoW 声明整项覆盖；默认值只来自不可变全局 Options。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import TypeVar
+
+from pydantic import ConfigDict, Field, field_validator
+
+from ..options import BaseOptions
+
+_UNIT_OF_WORK_ATTRIBUTE = "__python_platform_unit_of_work__"
+_T = TypeVar("_T")
+
+
+class UnitOfWorkTransactionBehavior(str, Enum):
+    AUTO = "auto"
+    ENABLED = "enabled"
+    DISABLED = "disabled"
+
+
+class UnitOfWorkOptions(BaseOptions):
+    model_config = ConfigDict(extra="forbid")
+
+    transaction_behavior: UnitOfWorkTransactionBehavior = UnitOfWorkTransactionBehavior.AUTO
+    isolation_level: str | None = None
+    command_timeout_ms: int | None = Field(default=None, strict=True, ge=0)
+
+    @field_validator("isolation_level")
+    @classmethod
+    def _validate_isolation_level(cls, value: str | None) -> str | None:
+        if value is not None and (
+            not value or value != value.strip() or value.upper() == "AUTOCOMMIT"
+        ):
+            # 事务隔离沿用原生 provider；DBAPI AUTOCOMMIT 会破坏本框架的批次/回滚语义。
+            raise ValueError("isolation_level must name a database transaction isolation level")
+        return value
+
+
+@dataclass(frozen=True, slots=True)
+class UnitOfWorkDeclaration:
+    disabled: bool = False
+    is_transactional: bool | None = None
+    isolation_level: str | None = None
+    command_timeout_ms: int | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.disabled, bool):
+            raise TypeError("disabled must be bool")
+        if self.is_transactional is not None and not isinstance(self.is_transactional, bool):
+            raise TypeError("is_transactional must be bool or None")
+        UnitOfWorkOptions(
+            isolation_level=self.isolation_level, command_timeout_ms=self.command_timeout_ms
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class _ResolvedUnitOfWorkOptions:
+    connection_name: str
+    is_transactional: bool
+    isolation_level: str | None
+    command_timeout_ms: int | None
+
+
+def unit_of_work(
+    *,
+    disabled: bool = False,
+    is_transactional: bool | None = None,
+    isolation_level: str | None = None,
+    command_timeout_ms: int | None = None,
+) -> Callable[[_T], _T]:
+    declaration = UnitOfWorkDeclaration(
+        disabled, is_transactional, isolation_level, command_timeout_ms
+    )
+
+    def decorate(target: _T) -> _T:
+        setattr(target, _UNIT_OF_WORK_ATTRIBUTE, declaration)
+        return target
+
+    return decorate
+
+
+def _declaration(implementation: type[object], method: object) -> UnitOfWorkDeclaration:
+    # 方法替换整项声明，未填写的字段只补全全局默认，不能泄漏类配置。
+    result = getattr(method, _UNIT_OF_WORK_ATTRIBUTE, None)
+    if result is None:
+        result = getattr(implementation, _UNIT_OF_WORK_ATTRIBUTE, UnitOfWorkDeclaration())
+    if not isinstance(result, UnitOfWorkDeclaration):
+        raise TypeError("invalid unit_of_work metadata")
+    return result

python_platform-0.1.1.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: python-platform
+Version: 0.1.1
+Summary: Modular Python application framework with project CLI and bundled templates
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+License-File: src/python_platform/background_jobs/pgqueuer/UPSTREAM_LICENSE.txt
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: dishka>=1.10.1,<2
+Requires-Dist: filelock==3.32.6
+Requires-Dist: pydantic>=2.13.5,<3
+Requires-Dist: pydantic-settings[yaml]>=2.15.0,<3
+Requires-Dist: croniter>=6.2.4,<7 ; extra == 'background-jobs'
+Requires-Dist: pgqueuer[asyncpg]>=1.3.2,<1.4 ; extra == 'background-jobs'
+Requires-Dist: cookiecutter>=2.7.1,<2.8 ; extra == 'developer-kit'
+Requires-Dist: libcst>=1.9.0,<1.10 ; extra == 'developer-kit'
+Requires-Dist: fastapi>=0.141.1,<0.142 ; extra == 'fastapi'
+Requires-Dist: httpx>=0.28.1,<0.29 ; extra == 'fastapi'
+Requires-Dist: python-multipart==0.0.32 ; extra == 'fastapi'
+Requires-Dist: uvicorn>=0.52.4,<0.53 ; extra == 'fastapi'
+Requires-Dist: wsproto>=1.3.2,<2 ; extra == 'fastapi'
+Requires-Dist: pyjwt>=2.13.0,<3 ; extra == 'identity'
+Requires-Dist: pwdlib[argon2]>=0.3.1,<0.4 ; extra == 'identity'
+Requires-Dist: python-json-logger==4.2.0 ; extra == 'logging'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.52,<2.1 ; extra == 'postgresql'
+Requires-Dist: alembic>=1.19.1,<2 ; extra == 'postgresql'
+Requires-Dist: asyncpg>=0.31,<0.32 ; extra == 'postgresql'
+Requires-Dist: anyio>=4.14.2,<5 ; extra == 'redis'
+Requires-Dist: redis>=8.1.0,<9 ; extra == 'redis'
+Requires-Dist: opentelemetry-api==1.44.0 ; extra == 'tracing'
+Requires-Dist: opentelemetry-sdk==1.44.0 ; extra == 'tracing'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http==1.44.0 ; extra == 'tracing'
+Requires-Dist: opentelemetry-instrumentation-fastapi==0.65b0 ; extra == 'tracing'
+Requires-Dist: opentelemetry-instrumentation-httpx==0.65b0 ; extra == 'tracing'
+Requires-Python: >=3.12, <3.15
+Provides-Extra: background-jobs
+Provides-Extra: developer-kit
+Provides-Extra: fastapi
+Provides-Extra: identity
+Provides-Extra: logging
+Provides-Extra: postgresql
+Provides-Extra: redis
+Provides-Extra: tracing
+Description-Content-Type: text/markdown
+
+# python-platform
+
+`python-platform` 是面向模块化业务应用的 Python 框架，提供显式 Module 组合、统一业务调用与事务边界，以及 `pp` CLI 和包内项目模板。Host 选择 Web、数据库和后台 provider，业务模块保持明确的契约与依赖方向。
+
+源码仓库私有，交付模型为 PyPI 公开安装包；框架、CLI、模板同包同版本。采用 [hank-repo 专有许可](LICENSE)，使用须取得单独书面授权，公开下载不增加使用权；PgQueuer 派生内容保留 [上游许可](src/python_platform/background_jobs/pgqueuer/UPSTREAM_LICENSE.txt)。
+
+版本、Python/OS 支持范围和 extras 以 [pyproject.toml](pyproject.toml) 为准，依赖解析以 [uv.lock](uv.lock) 为准。安装前查看 [发布状态与验收证据](docs/status.md#当前发布)。
+
+## 开始使用
+
+确认目标版本已发布后，安装 CLI 并创建应用：
+
+```powershell
+uv tool install "python-platform[developer-kit]"
+pp new my-app
+cd my-app
+uv run pp dev-init
+uv run pp add module orders
+```
+
+CLI 将生成项目的运行依赖和 developer-kit 精确固定到自身 distribution 版本；已有项目使用 `uv run pp`。按生成项目 README 完成初次数据库迁移与 Seed，再运行应用；dev-init 只准备开发基础设施，Host 不自动迁移。
+
+需要验证未发布制品时使用 `pp new my-app --framework-wheel <同版本wheel路径>`。模块开发、配置、HTTP、数据库和部署步骤见 [开发指南](docs/development.md)。完整命令与参数使用 `pp --help` 及子命令帮助，不另维护命令清单。
+
+## 阅读项目
+
+- [重构入口](docs/README.md#重构的最短阅读路径)：按改动定位 owner 和必要上下文，不重新通读项目。
+- [当前架构与契约](docs/architecture.md)：职责、源码入口、生命周期、依赖和失败不变量。
+- [协作规范](AGENTS.md)：后续改代码的范围、授权、验证与交接规则。
+- [状态记录](docs/status.md)：适用基线、最近有效证据和未完成事项。
+
+## 版本与升级
+
+本节是版本变化与消费者迁移的唯一正文入口。框架升级只更新依赖，不重新生成业务源码、Host、模板或应用迁移；全局 CLI 升级也不改变已有项目。
+
+1. 阅读目标版本说明，在项目运行依赖和开发组的 `python-platform[developer-kit]` 中同时固定目标版本，保留现有 extras。
+2. 旧 Git/wheel 项目首次转 PyPI 时，仅移除 `[tool.uv.sources]` 中 python-platform 的来源覆盖，保留其他依赖来源和 vendor 文件。
+3. 更新锁与环境，完成说明要求的代码适配，再运行应用原有验证：
+
+```powershell
+uv lock --upgrade-package python-platform
+uv sync --locked
+uv run pytest
+uv build --no-sources
+```
+
+日常代码或文档提交可以保持版本不变；推送 main 仍执行完整 CI，但跳过发布。真正发布不同内容时必须升级版本：0.x 中兼容修复使用 patch，需要消费者适配的变更使用 minor 并说明迁移。首次新建 main 发布当前版本，之后只有整个 push 前后版本升高才发布；Actions 手动运行只验证。失败可重跑原任务，修改后同版本推送不会续发，须再次升级版本。首次 OIDC 配置及重试边界见 [发布操作](docs/development.md#发布操作)；尚不存在的下一版本不能作为已验证升级案例。
+
+### 0.1.1
+
+- 首次公开安装包的目标版本；公开发布完成与否见状态记录。0.1.0 未完成公开发布，本次 patch 升版重新触发发布，不改变公开 API、依赖或数据库契约。new 默认生成 PyPI 精确依赖，保留同版本本地 wheel 验证入口，移除 `--framework-source` 与 Git 来源推断。
+- 从私有预发布迁移时，同步将运行/开发组依赖改为 `==0.1.1`，移除仅属于框架的来源覆盖并重新锁定。已有 Dockerfile 可移除专用于框架下载的 Git/SSH 工具和凭据 mounts；应用自己的其他 Git 依赖由应用维护者判断。本次发布消费变更没有新增框架 Schema 迁移。
+- 新项目使用纯 Host 骨架，业务由 add module 接入。既有应用不自动改目录或重生成；按 [模块与数据库操作](docs/development.md#数据库聚合与迁移) 核对标准 Host/module entry points 和数据库 owner。
+
+### 更早私有版本的迁移
+
+已经完成以下迁移的应用无需重复执行；这些是仍可能影响旧消费者的要求，不是当前待实施计划。
+
+| 旧用法 | 当前迁移要求 |
+| --- | --- |
+| 应用 TOML、OptionDefinition/class metadata、Editor.patch、具体 Options 类型自动注入 | 转 app.yaml；使用阶段 pre_configure/configure 与 values；服务注入 Options[T]。覆盖父配置 hook 时显式 super 或依赖 owner Module；无兼容加载/alias。 |
+| 公开 ApplicationServiceInvoker 或 invoke(ServiceType, method, ...) | 注入公开服务代理，或 invoke(Service.method, ...)；策略移到最终实现，Contract 保留签名。IntegrationService 保留独立 Contract。 |
+| Module 的 Settings/权限定义清单、GlobalSettings | 在 scan_packages 内使用同步 SettingDefinitionProvider/PermissionDefinitionProvider；读取用 SettingProvider，写入用 SettingManager，构造期间不使用未绑定的便捷属性。 |
+| HostedRuntime/Definition、ready/not_ready/failure 回调 | 使用 HostedService 类型 tuple 与 async start/stop；组件自己负责运行故障和恢复，确需后台子进程实例时显式声明进程归属。 |
+| SoftDeleteMixin、include_soft_deleted、恢复类接口 | 使用物理删除/外键约束和已发布后续迁移；历史软删除数据须先处理，不能修改旧 revision 或绕过 guard。 |
+| 旧 Settings 整数版本、重置删除版本记录 | 执行已有版本令牌迁移；update/reset 使用查询得到的 UUID/null 预期版本，reset 保留新的版本记录，旧 token 不能复用。 |
+| 手工聚合事件收集与仓储私有 operation | 使用公开 SessionProvider.operation(..., aggregate=...)，成功暂存后只收集一次，保留显式 DTO/聚合/ORM 映射。 |
+| 旧约定 HTTP 动作路径 | 按当前 HTTP Module/生成 OpenAPI 核对路径与公开签名，CRUD 省略动作段、静态段优先；无旧 URL alias。 |
+| ReferenceOrderView、公开 fail_after_add 参数 | 改用 ReferenceOrderDto，移除故障注入参数；参考 Orders 的 reference_orders_0002 为存量数据增加 version，更新按预期版本竞争，无旧类型 alias。 |
+| 超出当前 requires-python 的解释器/backport 路径 | 选择 metadata 声明的受支持解释器，重新锁定并执行应用验证，不强装范围外版本。 |
+
+持久 Job 的旧 payload version 不能因清理 Python API 而随意删除；须先证明队列 drain 或执行显式数据迁移。数据库迁移、版本并发及已提交数据的边界见 [架构契约](docs/architecture.md#uow持久化与本地事件)。