python-platform 0.1.1__py3-none-any.whl

python_platform/sqlalchemy/runtime.py

@@ -0,0 +1,85 @@
+"""APP 独占 engine registry；Session 由具体 UoW 按需创建与释放。"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Mapping
+from types import MappingProxyType
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    create_async_engine,
+)
+
+from ..options import Options
+from .errors import SqlAlchemyConnectionError, UnknownSqlAlchemyConnectionError
+from .metadata import SqlAlchemyModelCatalog
+from .options import ConnectionStringsOptions
+
+
+class _SqlAlchemyEngineRegistry:
+    __slots__ = ("_engines",)
+
+    def __init__(self, engines: Mapping[str, AsyncEngine]) -> None:
+        self._engines: Mapping[str, AsyncEngine] = MappingProxyType(dict(engines))
+
+    @property
+    def connection_names(self) -> tuple[str, ...]:
+        return tuple(self._engines)
+
+    def get(self, connection_name: str) -> AsyncEngine:
+        try:
+            return self._engines[connection_name]
+        except KeyError:
+            raise UnknownSqlAlchemyConnectionError(connection_name) from None
+
+    async def ping_all(self) -> None:
+        for connection_name, engine in self._engines.items():
+            try:
+                async with engine.connect() as connection:
+                    await connection.execute(text("SELECT 1"))
+            except Exception as original_error:
+                raise SqlAlchemyConnectionError(
+                    connection_name=connection_name,
+                    operation="startup ping",
+                    error_type=type(original_error).__name__,
+                ) from None
+
+    async def dispose_all(self) -> None:
+        failures: list[SqlAlchemyConnectionError] = []
+        for connection_name in reversed(self.connection_names):
+            try:
+                await self._engines[connection_name].dispose()
+            except BaseException as original_error:
+                failures.append(
+                    SqlAlchemyConnectionError(
+                        connection_name=connection_name,
+                        operation="engine disposal",
+                        error_type=type(original_error).__name__,
+                    )
+                )
+        if failures:
+            raise BaseExceptionGroup(
+                "SQLAlchemy engine disposal failed",
+                tuple(failures),
+            )
+
+
+async def _engine_registry(
+    options: Options[ConnectionStringsOptions],
+    models: SqlAlchemyModelCatalog,
+) -> AsyncIterator[_SqlAlchemyEngineRegistry]:
+    models._assert_unchanged()
+    configured_names = set(options.value.connection_names)
+    missing = set(models.connection_names) - configured_names
+    if missing:
+        raise UnknownSqlAlchemyConnectionError(sorted(missing)[0])
+    engines = {
+        name: create_async_engine(options.value._url_for(name))
+        for name in options.value.connection_names
+    }
+    registry = _SqlAlchemyEngineRegistry(engines)
+    try:
+        yield registry
+    finally:
+        await registry.dispose_all()

python_platform/sqlalchemy/session_provider.py

@@ -0,0 +1,45 @@
+"""只解析当前有效 UoW 的原生 Session，无 owner 时明确失败。"""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..domain import AggregateRoot
+from ..events.aggregate import _collect_aggregate_events
+from ..unit_of_work.manager import UnitOfWorkManager
+from ..unit_of_work.options import UnitOfWorkDeclaration
+from .unit_of_work import _SqlAlchemyUnitOfWork
+
+
+class SqlAlchemySessionProvider:
+    def __init__(self, manager: UnitOfWorkManager) -> None:
+        self._manager = manager
+
+    async def get_session(self) -> AsyncSession:
+        work = self._manager.require_current()
+        if not isinstance(work, _SqlAlchemyUnitOfWork):
+            raise TypeError("current UnitOfWork does not own SQLAlchemy persistence")
+        return work.get_session()
+
+    @asynccontextmanager
+    async def operation(
+        self,
+        method_name: str,
+        *,
+        aggregate: AggregateRoot[Any] | None = None,
+    ) -> AsyncIterator[None]:
+        """仓储暂存边界；成功后收集聚合事件，Session 仍由 get_session 懒创建。"""
+        if aggregate is not None and not isinstance(aggregate, AggregateRoot):
+            raise TypeError("aggregate must be AggregateRoot")
+        options = self._manager._resolve_options(None, UnitOfWorkDeclaration(), method_name)
+        async with self._manager._begin(options) as work:
+            owner = self._manager.require_current(transactional=aggregate is not None)
+            yield
+            if aggregate is not None:
+                # 参与者不拥有提交权；成功暂存后必须仍在进入时的同一有效事务中。
+                if self._manager.require_current(transactional=True) is not owner:
+                    raise RuntimeError("aggregate operation changed its UnitOfWork owner")
+                _collect_aggregate_events(owner, aggregate)
+            await work.complete()

python_platform/sqlalchemy/unit_of_work.py

@@ -0,0 +1,97 @@
+"""一个逻辑 UoW 拥有按需 Session；原生事务与连接配置归 SQLAlchemy。"""
+
+from __future__ import annotations
+
+from sqlalchemy import Connection, event, text
+from sqlalchemy.orm import Session, SessionTransaction
+from sqlalchemy.orm.exc import StaleDataError
+
+from ..application_services.invocation import _InvocationRuntime
+from ..domain import OptimisticConcurrencyError
+from ..unit_of_work import UnitOfWork
+from ..unit_of_work.contracts import _UnitOfWorkFactory
+from .auditing import PlatformAsyncSession, _bind_current_user
+from .runtime import _SqlAlchemyEngineRegistry
+
+
+class _SqlAlchemyUnitOfWork(UnitOfWork):
+    def __init__(self, engines: _SqlAlchemyEngineRegistry, runtime: _InvocationRuntime) -> None:
+        super().__init__()
+        self._engines = engines
+        self._runtime = runtime
+        self._session: PlatformAsyncSession | None = None
+        self._connections: list[Connection] = []
+
+    def get_session(self) -> PlatformAsyncSession:
+        self._require_active("get_session", allow_completing=True)
+        if self._session is None:
+            options = self._require_options()
+            engine = self._engines.get(options.connection_name)
+            if options.isolation_level is not None:
+                engine = engine.execution_options(isolation_level=options.isolation_level)
+            # close_resets_only=False 阻止已关闭 raw Session 再借连接；不替代 owner 检查。
+            self._session = PlatformAsyncSession(
+                engine, expire_on_commit=False, autoflush=False, close_resets_only=False
+            )
+            _bind_current_user(self._session, self._runtime.current_user())
+            event.listen(self._session.sync_session, "after_begin", self._after_begin)
+        return self._session
+
+    def _after_begin(
+        self, session: Session, transaction: SessionTransaction, connection: Connection
+    ) -> None:
+        # 保留合法取得的公开 Connection 引用；不访问 Session 私有连接缓存。
+        self._connections[:] = [item for item in self._connections if not item.closed]
+        self._connections.append(connection)
+        timeout = self._require_options().command_timeout_ms
+        if timeout is not None:
+            connection.execute(
+                text("SELECT set_config('statement_timeout', :timeout, true)"),
+                {"timeout": str(timeout)},
+            )
+
+    async def _flush(self) -> None:
+        if self._session is not None:
+            try:
+                await self._session.flush()
+            except StaleDataError:
+                raise OptimisticConcurrencyError from None
+
+    async def _commit(self) -> None:
+        if self._session is not None:
+            try:
+                await self._session.commit()
+            except StaleDataError:
+                raise OptimisticConcurrencyError from None
+
+    async def _rollback(self) -> None:
+        if self._session is not None:
+            await self._session.rollback()
+
+    async def _close(self) -> None:
+        if self._session is not None:
+            await self._session.close()
+
+    async def _invalidate(self) -> None:
+        if self._session is None:
+            return
+        # Session 部分关闭失败时仍沿已登记的公开连接失效，防止丢失活动句柄。
+        try:
+            await self._session.invalidate()
+        finally:
+            for connection in self._connections:
+                if not connection.closed:
+
+                    def invalidate_owned(session: Session, owned: Connection = connection) -> None:
+                        owned.invalidate()
+
+                    await self._session.run_sync(invalidate_owned)
+
+
+class _SqlAlchemyUnitOfWorkFactory(_UnitOfWorkFactory):
+    def __init__(self, engines: _SqlAlchemyEngineRegistry, runtime: _InvocationRuntime) -> None:
+        self._engines = engines
+        self._runtime = runtime
+
+    def create(self) -> UnitOfWork:
+        return _SqlAlchemyUnitOfWork(self._engines, self._runtime)

python_platform/testing/__init__.py

@@ -0,0 +1,5 @@
+"""Python Platform 正式 test lifecycle capability。"""
+
+from .runtime import TestApplication
+
+__all__ = ("TestApplication",)

python_platform/testing/runtime.py

@@ -0,0 +1,112 @@
+"""正式 ApplicationBuilder 上的窄测试生命周期，不建立第二套配置或 DI DSL。"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from types import TracebackType
+from typing import Concatenate, ParamSpec, TypeVar
+
+from ..application import Application, ApplicationBuilder
+from ..application_services import ApplicationServiceContract
+from ..authorization import CurrentUser
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+_TContract = TypeVar("_TContract", bound=ApplicationServiceContract)
+
+
+class TestApplication:
+    """测试拥有的 Application owner；build/start/stop 仍走正式生产路径。"""
+
+    __slots__ = ("_application", "_build_called", "_builder")
+
+    def __init__(self, builder: ApplicationBuilder) -> None:
+        if not isinstance(builder, ApplicationBuilder):
+            raise TypeError("builder must be python_platform.ApplicationBuilder")
+        self._builder = builder
+        self._build_called = False
+        self._application: Application | None = None
+
+    @property
+    def application(self) -> Application:
+        if self._application is None:
+            raise RuntimeError("TestApplication has not been built")
+        return self._application
+
+    def build(self) -> Application:
+        if self._build_called:
+            raise RuntimeError("TestApplication may only build once")
+        self._build_called = True
+        self._application = self._builder.build()
+        return self._application
+
+    async def start(self) -> None:
+        application = self._application if self._application is not None else self.build()
+        await application.start()
+
+    async def stop(self) -> None:
+        application = self._application if self._application is not None else self.build()
+        await application.stop()
+
+    async def __aenter__(self) -> TestApplication:
+        await self.start()
+        return self
+
+    async def __aexit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool:
+        del exception_type, traceback
+        cleanup_failure: BaseException | None = None
+        try:
+            await self.stop()
+        except BaseException as original_error:
+            cleanup_failure = original_error
+        if exception is not None and cleanup_failure is not None:
+            raise BaseExceptionGroup(
+                "TestApplication body and cleanup failed",
+                (exception, cleanup_failure),
+            ) from None
+        if cleanup_failure is not None:
+            raise cleanup_failure
+        return False
+
+    async def call(
+        self,
+        function: Callable[..., Awaitable[_R]],
+        /,
+        *args: object,
+        **kwargs: object,
+    ) -> _R:
+        return await self.application.call(function, *args, **kwargs)
+
+    async def call_as(
+        self,
+        current_user: CurrentUser,
+        function: Callable[..., Awaitable[_R]],
+        /,
+        *args: object,
+        **kwargs: object,
+    ) -> _R:
+        return await self.application.call_as(current_user, function, *args, **kwargs)
+
+    async def invoke(
+        self,
+        method: Callable[Concatenate[_TContract, _P], Awaitable[_R]],
+        /,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> _R:
+        return await self.application.invoke(method, *args, **kwargs)
+
+    async def invoke_as(
+        self,
+        current_user: CurrentUser,
+        method: Callable[Concatenate[_TContract, _P], Awaitable[_R]],
+        /,
+        *args: _P.args,
+        **kwargs: _P.kwargs,
+    ) -> _R:
+        return await self.application.invoke_as(current_user, method, *args, **kwargs)

python_platform/unit_of_work/__init__.py

@@ -0,0 +1,14 @@
+from .contracts import UnitOfWork, UnitOfWorkState
+from .errors import UnitOfWorkStateError
+from .manager import UnitOfWorkManager
+from .options import UnitOfWorkOptions, UnitOfWorkTransactionBehavior, unit_of_work
+
+__all__ = (
+    "UnitOfWork",
+    "UnitOfWorkManager",
+    "UnitOfWorkOptions",
+    "UnitOfWorkState",
+    "UnitOfWorkStateError",
+    "UnitOfWorkTransactionBehavior",
+    "unit_of_work",
+)

python_platform/unit_of_work/contracts.py

@@ -0,0 +1,223 @@
+"""具体 UoW 的工作状态、提交事实与资源释放事实分别保存。"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from .errors import UnitOfWorkStateError
+from .options import _ResolvedUnitOfWorkOptions
+
+if TYPE_CHECKING:
+    from ..events.runtime import _LocalEventQueue
+
+
+class UnitOfWorkState(str, Enum):
+    ACTIVE = "active"
+    COMMITTED = "committed"
+    ROLLED_BACK = "rolled_back"
+    FAILED = "failed"
+
+
+class UnitOfWork:
+    """手动 owner 显式完成；参与者只确认参与，不提交或关闭共享资源。"""
+
+    def __init__(self) -> None:
+        self._state = UnitOfWorkState.ACTIVE
+        self._task = asyncio.current_task()
+        self._completing = False
+        self._released = False
+        self._committed = False
+        self._commit_unknown = False
+        self._saved_batches = 0
+        self._cleanup_failures: tuple[BaseException, ...] = ()
+        self._options: _ResolvedUnitOfWorkOptions | None = None
+        self._event_queue: _LocalEventQueue | None = None
+        self._after_commit: Callable[[], Awaitable[None]] | None = None
+
+    @property
+    def state(self) -> UnitOfWorkState:
+        return self._state
+
+    @property
+    def is_transactional(self) -> bool:
+        return self._require_options().is_transactional
+
+    @property
+    def connection_name(self) -> str:
+        return self._require_options().connection_name
+
+    @property
+    def committed(self) -> bool:
+        return self._committed
+
+    @property
+    def commit_outcome_unknown(self) -> bool:
+        return self._commit_unknown
+
+    @property
+    def saved_batches(self) -> int:
+        return self._saved_batches
+
+    @property
+    def resources_released(self) -> bool:
+        return self._released
+
+    @property
+    def cleanup_failures(self) -> tuple[BaseException, ...]:
+        return self._cleanup_failures
+
+    def _require_options(self) -> _ResolvedUnitOfWorkOptions:
+        if self._options is None:
+            raise RuntimeError("UnitOfWork has no manager owner")
+        return self._options
+
+    def _require_active(self, operation: str, *, allow_completing: bool = False) -> None:
+        from ..application_services.errors import CrossTaskInvocationError
+
+        if asyncio.current_task() is not self._task:
+            raise CrossTaskInvocationError
+        if self._released or (self._completing and not allow_completing):
+            raise RuntimeError(f"UnitOfWork.{operation} is no longer available")
+        self._require_state(operation, (UnitOfWorkState.ACTIVE,))
+
+    async def flush(self) -> None:
+        self._require_active("flush", allow_completing=True)
+        try:
+            await self._flush()
+        except BaseException:
+            self._state = UnitOfWorkState.FAILED
+            raise
+
+    async def save_changes(self) -> None:
+        self._require_active("save_changes")
+        await self.flush()
+        if not self.is_transactional:
+            await self._save_batch()
+
+    async def complete(self) -> None:
+        self._require_active("complete")
+        self._completing = True
+        try:
+            if self._event_queue is not None:
+                await self._event_queue._dispatch_domain()
+            await self.flush()
+            await self._save_batch()
+            self._committed = True
+            self._state = UnitOfWorkState.COMMITTED
+            if self._after_commit is not None:
+                await self._after_commit()
+        except BaseException:
+            if not self._committed:
+                self._state = UnitOfWorkState.FAILED
+            raise
+        finally:
+            self._completing = False
+
+    async def _save_batch(self) -> None:
+        # await commit 抛错不证明服务端未提交；诊断独立于后续 rollback 成败。
+        self._commit_unknown = True
+        try:
+            await self._commit()
+        except BaseException:
+            self._state = UnitOfWorkState.FAILED
+            raise
+        self._commit_unknown = False
+        if self._options is not None and not self.is_transactional:
+            self._saved_batches += 1
+
+    async def rollback(self) -> None:
+        self._require_active("rollback")
+        await self._rollback_owned()
+
+    async def _rollback_owned(self) -> None:
+        try:
+            await self._rollback()
+        except BaseException:
+            self._state = UnitOfWorkState.FAILED
+            raise
+        if not self._commit_unknown:
+            self._state = UnitOfWorkState.ROLLED_BACK
+
+    async def _flush(self) -> None:
+        """未选择持久化 provider 时无需物理资源。"""
+
+    async def _commit(self) -> None:
+        pass
+
+    async def _rollback(self) -> None:
+        pass
+
+    async def _close(self) -> None:
+        pass
+
+    async def _invalidate(self) -> None:
+        pass
+
+    async def _cleanup(self) -> None:
+        failures: list[BaseException] = []
+        suspect = self._commit_unknown
+        if not self._committed and self._state is not UnitOfWorkState.ROLLED_BACK:
+            try:
+                await self._rollback_owned()
+            except BaseException as error:
+                failures.append(error)
+                suspect = True
+        # 有疑问的连接在 close 归池前失效；close 自身失败仍沿原生资源引用继续回收。
+        if suspect:
+            try:
+                await self._invalidate()
+            except BaseException as error:
+                failures.append(error)
+        try:
+            await self._close()
+            self._released = True
+        except BaseException as error:
+            failures.append(error)
+            try:
+                await self._invalidate()
+                self._released = True
+            except BaseException as invalidate_error:
+                failures.append(invalidate_error)
+        self._cleanup_failures = tuple(failures)
+
+    def _require_state(self, operation: str, allowed: tuple[UnitOfWorkState, ...]) -> None:
+        if self._state not in allowed:
+            raise UnitOfWorkStateError(operation=operation, current=self._state, allowed=allowed)
+
+
+class _UnitOfWorkParticipant(UnitOfWork):
+    def __init__(self, owner: UnitOfWork) -> None:
+        super().__init__()
+        self._owner = owner
+        self._options = owner._options
+
+    @property
+    def state(self) -> UnitOfWorkState:
+        return self._owner.state
+
+    async def complete(self) -> None:
+        self._require_active("complete")
+        self._owner._require_active("participate", allow_completing=True)
+        self._state = UnitOfWorkState.COMMITTED
+
+    async def flush(self) -> None:
+        self._require_active("flush")
+        await self._owner.flush()
+
+    async def save_changes(self) -> None:
+        self._require_active("save_changes")
+        await self._owner.save_changes()
+
+    async def rollback(self) -> None:
+        self._require_active("rollback")
+        await self._owner.rollback()
+
+
+class _UnitOfWorkFactory:
+    """原生 DI 的 provider 替换点：无数据库与 SQLAlchemy 两种实际实现。"""
+
+    def create(self) -> UnitOfWork:
+        return UnitOfWork()

python_platform/unit_of_work/errors.py

@@ -0,0 +1,27 @@
+"""Unit of Work 公开失败契约与状态诊断。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..errors.base import FrameworkError
+
+if TYPE_CHECKING:
+    from .contracts import UnitOfWorkState
+
+
+class UnitOfWorkStateError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        operation: str,
+        current: UnitOfWorkState,
+        allowed: tuple[UnitOfWorkState, ...],
+    ) -> None:
+        self.operation = operation
+        self.current = current
+        self.allowed = allowed
+        allowed_values = ", ".join(item.value for item in allowed)
+        super().__init__(
+            f"UnitOfWork.{operation} requires state in ({allowed_values}), got {current.value}"
+        )