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

python_ddd_framework/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}"
+        )

python_ddd_framework/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_ddd_framework_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_ddd_framework/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_ddd_framework_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