pythonboot 0.1.0__py3-none-any.whl

pythonboot/task/executor.py

@@ -0,0 +1,241 @@
+"""Application-scoped task executors with Spring-style pool admission."""
+
+import asyncio
+import inspect
+import logging
+from abc import ABC, abstractmethod
+from collections import deque
+from collections.abc import Callable
+from concurrent.futures import Future
+from contextvars import Context
+from enum import StrEnum
+from functools import partial
+from threading import Condition, Thread, current_thread
+from time import monotonic
+from typing import Any, ParamSpec, TypeVar
+
+P = ParamSpec("P")
+T = TypeVar("T")
+TaskDecorator = Callable[[Callable[[], Any]], Callable[[], Any]]
+_logger = logging.getLogger(__name__)
+
+
+class TaskRejectedError(RuntimeError):
+    """The executor is shut down or its pool and queue are saturated."""
+
+
+class RejectionPolicy(StrEnum):
+    ABORT = "abort"
+    CALLER_RUNS = "caller_runs"
+    DISCARD = "discard"
+    DISCARD_OLDEST = "discard_oldest"
+
+
+class TaskExecutor(ABC):
+    """Submit synchronous work for execution outside the calling thread."""
+
+    @abstractmethod
+    def submit(self, task: Callable[P, T], /, *args: P.args, **kwargs: P.kwargs) -> Future[T]:
+        """Return a future containing the task result or exception."""
+
+    def execute(self, task: Callable[P, Any], /, *args: P.args, **kwargs: P.kwargs) -> None:
+        """Submit fire-and-forget work and log unhandled task failures."""
+        future = self.submit(task, *args, **kwargs)
+
+        def report(completed: Future[Any]) -> None:
+            if not completed.cancelled() and (error := completed.exception()) is not None:
+                _logger.error("Task execution failed", exc_info=(type(error), error, error.__traceback__))
+
+        future.add_done_callback(report)
+
+    async def asubmit(self, task: Callable[P, T], /, *args: P.args, **kwargs: P.kwargs) -> T:
+        """Await synchronous work without blocking the event loop."""
+        return await asyncio.wrap_future(self.submit(task, *args, **kwargs))
+
+
+class ThreadPoolTaskExecutor(TaskExecutor):
+    """Grow core workers, enqueue work, then grow to max workers before rejecting.
+
+    A queue capacity of None is unbounded; zero allows direct handoff only.
+    Threads are created on demand. Extra workers expire after keep_alive_seconds.
+    Running tasks cannot be forcibly interrupted during cancellation or shutdown.
+    """
+
+    def __init__(
+        self, *, core_pool_size: int = 8, max_pool_size: int = 32,
+        queue_capacity: int | None = 256, keep_alive_seconds: float = 60,
+        thread_name_prefix: str = "pythonboot-task-",
+        allow_core_thread_timeout: bool = False,
+        rejection_policy: RejectionPolicy | str = RejectionPolicy.ABORT,
+        wait_for_tasks_to_complete_on_shutdown: bool = True,
+        await_termination_seconds: float | None = None,
+        task_decorator: TaskDecorator | None = None,
+    ) -> None:
+        for name, value in (("core_pool_size", core_pool_size), ("max_pool_size", max_pool_size)):
+            if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+                raise ValueError(f"{name} must be a positive integer")
+        if max_pool_size < core_pool_size:
+            raise ValueError("max_pool_size must be at least core_pool_size")
+        if queue_capacity is not None and (
+            isinstance(queue_capacity, bool) or not isinstance(queue_capacity, int) or queue_capacity < 0
+        ):
+            raise ValueError("queue_capacity must be a non-negative integer or None")
+        if not 0 < keep_alive_seconds < float("inf"):
+            raise ValueError("keep_alive_seconds must be positive and finite")
+        if await_termination_seconds is not None and not 0 <= await_termination_seconds < float("inf"):
+            raise ValueError("await_termination_seconds must be non-negative and finite or None")
+        if not isinstance(thread_name_prefix, str) or not thread_name_prefix:
+            raise ValueError("thread_name_prefix must be a non-empty string")
+        if task_decorator is not None and not callable(task_decorator):
+            raise TypeError("task_decorator must be callable")
+        self.core_pool_size = core_pool_size
+        self.max_pool_size = max_pool_size
+        self.queue_capacity = queue_capacity
+        self.keep_alive_seconds = keep_alive_seconds
+        self.thread_name_prefix = thread_name_prefix
+        self.allow_core_thread_timeout = allow_core_thread_timeout
+        self.rejection_policy = RejectionPolicy(rejection_policy)
+        self.wait_for_tasks_to_complete_on_shutdown = wait_for_tasks_to_complete_on_shutdown
+        self.await_termination_seconds = await_termination_seconds
+        self.task_decorator = task_decorator
+        self._condition = Condition()
+        self._queue: deque[tuple[Future[Any], Callable[[], Any]]] = deque()
+        self._threads: set[Thread] = set()
+        self._idle = 0
+        self._sequence = 0
+        self._shutdown = False
+
+    @property
+    def pool_size(self) -> int:
+        with self._condition:
+            return len(self._threads)
+
+    @property
+    def queue_size(self) -> int:
+        with self._condition:
+            return len(self._queue)
+
+    def submit(self, task: Callable[P, T], /, *args: P.args, **kwargs: P.kwargs) -> Future[T]:
+        if not callable(task) or inspect.iscoroutinefunction(task) or inspect.iscoroutinefunction(getattr(task, "__call__", None)):
+            raise TypeError("Thread pool tasks must be synchronous callables")
+        callback = partial(task, *args, **kwargs)
+        if self.task_decorator is not None:
+            callback = self.task_decorator(callback)
+            if not callable(callback):
+                raise TypeError("task_decorator must return a callable")
+        future: Future[T] = Future()
+        work = (future, callback)
+        discarded: Future[Any] | None = None
+        with self._condition:
+            if self._shutdown:
+                raise TaskRejectedError("Task executor has been shut down")
+            if len(self._threads) < self.core_pool_size:
+                self._start_worker(work)
+                return future
+            available = (
+                self.queue_capacity is None
+                or self.queue_capacity > 0 and len(self._queue) < self.queue_capacity
+                or self.queue_capacity == 0 and len(self._queue) < self._idle
+            )
+            if available:
+                self._queue.append(work)
+                self._condition.notify()
+                return future
+            if len(self._threads) < self.max_pool_size:
+                self._start_worker(work)
+                return future
+            if self.rejection_policy == RejectionPolicy.ABORT:
+                raise TaskRejectedError("Task executor pool and queue are saturated")
+            if self.rejection_policy == RejectionPolicy.DISCARD_OLDEST and self._queue:
+                discarded, _ = self._queue.popleft()
+                self._queue.append(work)
+                self._condition.notify()
+        if discarded is not None:
+            discarded.cancel()
+        elif self.rejection_policy == RejectionPolicy.CALLER_RUNS:
+            self._run(work)
+        else:
+            future.cancel()
+        return future
+
+    def _start_worker(self, work: tuple[Future[Any], Callable[[], Any]]) -> None:
+        self._sequence += 1
+        thread = Thread(
+            target=Context().run, args=(self._worker, work),
+            name=f"{self.thread_name_prefix}{self._sequence}", daemon=False,
+        )
+        self._threads.add(thread)
+        try:
+            thread.start()
+        except BaseException:
+            self._threads.remove(thread)
+            raise
+
+    @staticmethod
+    def _run(work: tuple[Future[Any], Callable[[], Any]]) -> None:
+        future, callback = work
+        if not future.set_running_or_notify_cancel():
+            return
+        try:
+            result = callback()
+            if inspect.isawaitable(result):
+                if inspect.iscoroutine(result):
+                    result.close()
+                raise TypeError("Thread pool tasks must not return awaitables")
+        except BaseException as error:
+            future.set_exception(error)
+        else:
+            future.set_result(result)
+
+    def _worker(self, work: tuple[Future[Any], Callable[[], Any]]) -> None:
+        try:
+            while True:
+                self._run(work)
+                with self._condition:
+                    deadline = monotonic() + self.keep_alive_seconds
+                    while not self._queue:
+                        if self._shutdown:
+                            self._threads.remove(current_thread())
+                            return
+                        may_expire = self.allow_core_thread_timeout or len(self._threads) > self.core_pool_size
+                        remaining = deadline - monotonic() if may_expire else None
+                        if remaining is not None and remaining <= 0:
+                            self._threads.remove(current_thread())
+                            return
+                        self._idle += 1
+                        try:
+                            self._condition.wait(remaining)
+                        finally:
+                            self._idle -= 1
+                    work = self._queue.popleft()
+        finally:
+            with self._condition:
+                self._threads.discard(current_thread())
+                self._condition.notify_all()
+
+    def shutdown(self, wait: bool = True, *, cancel_futures: bool = False) -> None:
+        """Reject new submissions, optionally cancel queued work, and join workers."""
+        with self._condition:
+            self._shutdown = True
+            pending = tuple(self._queue) if cancel_futures else ()
+            if cancel_futures:
+                self._queue.clear()
+            threads = tuple(self._threads)
+            self._condition.notify_all()
+        for future, _ in pending:
+            future.cancel()
+        if wait:
+            deadline = (
+                monotonic() + self.await_termination_seconds
+                if self.await_termination_seconds is not None else None
+            )
+            for thread in threads:
+                if thread is not current_thread():
+                    thread.join(None if deadline is None else max(0, deadline - monotonic()))
+
+    async def close(self) -> None:
+        """Release workers through the container's asynchronous destruction hook."""
+        await asyncio.to_thread(
+            self.shutdown, self.wait_for_tasks_to_complete_on_shutdown,
+            cancel_futures=not self.wait_for_tasks_to_complete_on_shutdown,
+        )

pythonboot/transaction/__init__.py

@@ -0,0 +1,24 @@
+"""Public resource-independent transaction contracts and declarations."""
+
+from pythonboot.transaction.decorators import get_transaction_attribute, transactional
+from pythonboot.transaction.definition import Isolation, Propagation, TransactionAttribute, TransactionDefinition
+from pythonboot.transaction.exceptions import (
+    IllegalTransactionStateError, InvalidIsolationLevelError,
+    NestedTransactionNotSupportedError, NoTransactionError,
+    TransactionError, TransactionTimedOutError, UnexpectedRollbackError,
+)
+from pythonboot.transaction.manager import (
+    AsyncPlatformTransactionManager, AsyncSavepointManager,
+    PlatformTransactionManager, SavepointManager, TransactionStatus,
+)
+from pythonboot.transaction.interceptor import TransactionInterceptor
+
+__all__ = [
+    "Propagation", "Isolation", "TransactionDefinition", "TransactionAttribute",
+    "TransactionStatus", "PlatformTransactionManager", "AsyncPlatformTransactionManager",
+    "SavepointManager", "AsyncSavepointManager", "transactional", "get_transaction_attribute",
+    "TransactionError", "NoTransactionError", "IllegalTransactionStateError",
+    "InvalidIsolationLevelError", "TransactionTimedOutError",
+    "NestedTransactionNotSupportedError", "UnexpectedRollbackError",
+    "TransactionInterceptor",
+]

pythonboot/transaction/decorators.py

@@ -0,0 +1,48 @@
+"""Declarative transaction metadata compatible with annotation pointcuts."""
+
+from typing import Callable, TypeVar
+
+from pythonboot.aop.pointcut import MethodAnnotation
+from pythonboot.transaction.definition import Isolation, Propagation, TransactionAttribute
+
+
+F = TypeVar("F", bound=Callable)
+
+
+class Transactional(MethodAnnotation):
+    """Mark a method for a resource-specific transaction interceptor."""
+
+    def __call__(
+        self,
+        method: F | None = None,
+        *,
+        propagation: Propagation = Propagation.REQUIRED,
+        isolation: Isolation = Isolation.DEFAULT,
+        timeout: int = -1,
+        read_only: bool = False,
+        name: str | None = None,
+        rollback_for: tuple[type[BaseException], ...] = (Exception,),
+        no_rollback_for: tuple[type[BaseException], ...] = (),
+        transaction_manager: str | None = None,
+    ) -> F | Callable[[F], F]:
+        """Support both @transactional and @transactional(...), without wrapping."""
+        attribute = TransactionAttribute(
+            propagation=propagation, isolation=isolation, timeout=timeout,
+            read_only=read_only, name=name, rollback_for=rollback_for,
+            no_rollback_for=no_rollback_for, transaction_manager=transaction_manager,
+        )
+
+        def decorate(target: F) -> F:
+            super(Transactional, self).__call__(target)
+            target.__pythonboot_transaction__ = attribute
+            return target
+
+        return decorate(method) if method is not None else decorate
+
+
+transactional = Transactional("pythonboot.transactional")
+
+
+def get_transaction_attribute(method: Callable) -> TransactionAttribute | None:
+    """Read transaction metadata from a function or bound instance method."""
+    return getattr(method, "__pythonboot_transaction__", None)

pythonboot/transaction/definition.py

@@ -0,0 +1,90 @@
+"""Resource-independent transaction definitions and rollback rules."""
+
+from dataclasses import dataclass
+from enum import IntEnum
+
+
+class Propagation(IntEnum):
+    """Spring-compatible transaction propagation policies."""
+
+    REQUIRED = 0
+    SUPPORTS = 1
+    MANDATORY = 2
+    REQUIRES_NEW = 3
+    NOT_SUPPORTED = 4
+    NEVER = 5
+    NESTED = 6
+
+
+class Isolation(IntEnum):
+    """Standard transaction isolation levels; DEFAULT uses the resource default."""
+
+    DEFAULT = -1
+    READ_UNCOMMITTED = 1
+    READ_COMMITTED = 2
+    REPEATABLE_READ = 4
+    SERIALIZABLE = 8
+
+
+@dataclass(frozen=True)
+class TransactionDefinition:
+    """Describe a transaction without creating or binding resource connections."""
+
+    propagation: Propagation = Propagation.REQUIRED
+    isolation: Isolation = Isolation.DEFAULT
+    timeout: int = -1
+    read_only: bool = False
+    name: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.propagation, Propagation):
+            raise TypeError("propagation must be a Propagation value")
+        if not isinstance(self.isolation, Isolation):
+            raise TypeError("isolation must be an Isolation value")
+        if isinstance(self.timeout, bool) or not isinstance(self.timeout, int) or self.timeout < -1:
+            raise ValueError("timeout must be -1 or a non-negative number of seconds")
+        if not isinstance(self.read_only, bool):
+            raise TypeError("read_only must be a boolean")
+        if self.name is not None and (not isinstance(self.name, str) or not self.name.strip()):
+            raise ValueError("name must be a non-empty string or None")
+
+
+@dataclass(frozen=True)
+class TransactionAttribute(TransactionDefinition):
+    """Add rollback rules and an optional transaction manager bean name."""
+
+    rollback_for: tuple[type[BaseException], ...] = (Exception,)
+    no_rollback_for: tuple[type[BaseException], ...] = ()
+    transaction_manager: str | None = None
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        for label in ("rollback_for", "no_rollback_for"):
+            rules = getattr(self, label)
+            if not isinstance(rules, (tuple, list)) or any(
+                not isinstance(rule, type) or not issubclass(rule, BaseException)
+                for rule in rules
+            ):
+                raise TypeError(f"{label} must be a sequence of exception classes")
+            object.__setattr__(self, label, tuple(dict.fromkeys(rules)))
+        if self.transaction_manager is not None and (
+            not isinstance(self.transaction_manager, str) or not self.transaction_manager.strip()
+        ):
+            raise ValueError("transaction_manager must be a non-empty bean name or None")
+
+    def rollback_on(self, error: BaseException) -> bool:
+        """Use the closest exception rule; exclusions win ties; fatal errors roll back."""
+        if not isinstance(error, BaseException):
+            raise TypeError("error must be an exception instance")
+        if not isinstance(error, Exception):
+            return True
+        hierarchy = type(error).__mro__
+        rollback_depth = min(
+            (hierarchy.index(rule) for rule in self.rollback_for if rule in hierarchy),
+            default=float("inf"),
+        )
+        exclusion_depth = min(
+            (hierarchy.index(rule) for rule in self.no_rollback_for if rule in hierarchy),
+            default=float("inf"),
+        )
+        return rollback_depth < exclusion_depth

pythonboot/transaction/exceptions.py

@@ -0,0 +1,31 @@
+"""Resource-independent transaction exceptions."""
+
+from pythonboot.exceptions import PythonBootError
+
+
+class TransactionError(PythonBootError):
+    """Base class for transaction failures."""
+
+
+class NoTransactionError(TransactionError):
+    """A required existing transaction is missing."""
+
+
+class IllegalTransactionStateError(TransactionError):
+    """Invalid transaction participation, status ownership, or completion state."""
+
+
+class InvalidIsolationLevelError(TransactionError):
+    """The requested isolation level cannot be applied by the resource."""
+
+
+class TransactionTimedOutError(TransactionError):
+    """A transaction exceeded its configured timeout."""
+
+
+class NestedTransactionNotSupportedError(TransactionError):
+    """The resource does not support nested transactions or savepoints."""
+
+
+class UnexpectedRollbackError(TransactionError):
+    """Commit was requested for a transaction already marked rollback-only."""

pythonboot/transaction/interceptor.py

@@ -0,0 +1,71 @@
+"""Application-scoped around advice for declarative transactions."""
+
+from dataclasses import replace
+import inspect
+from typing import Any, Callable
+
+from pythonboot.aop.decorators import around
+from pythonboot.aop.joinpoint import ProceedingJoinPoint
+from pythonboot.transaction.decorators import get_transaction_attribute, transactional
+from pythonboot.transaction.definition import TransactionAttribute
+from pythonboot.transaction.exceptions import IllegalTransactionStateError
+from pythonboot.transaction.manager import AsyncPlatformTransactionManager, PlatformTransactionManager
+
+
+class TransactionInterceptor:
+    """Resolve managers from the owning container and complete transaction scopes."""
+
+    def __init__(
+        self,
+        resolver: Callable[[type, str | None], Any],
+        async_resolver: Callable[[type, str | None], Any] | None = None,
+    ) -> None:
+        self._resolver = resolver
+        self._async_resolver = async_resolver
+
+    @around(transactional)
+    def invoke(self, join_point: ProceedingJoinPoint) -> Any:
+        """Dispatch using the original method's coroutine type."""
+        attribute = get_transaction_attribute(join_point.method)
+        if attribute is None:
+            raise IllegalTransactionStateError("Transaction advice requires transaction metadata")
+        if attribute.name is None:
+            attribute = replace(attribute, name=join_point.qualified_name)
+        if inspect.iscoroutinefunction(join_point.method):
+            return self._invoke_async(join_point, attribute)
+        return self._invoke_sync(join_point, attribute)
+
+    def _invoke_sync(self, join_point: ProceedingJoinPoint, attribute: TransactionAttribute) -> Any:
+        manager = self._resolver(PlatformTransactionManager, attribute.transaction_manager)
+        if not isinstance(manager, PlatformTransactionManager):
+            raise IllegalTransactionStateError("Synchronous transaction methods require PlatformTransactionManager")
+        status = manager.get_transaction(attribute)
+        try:
+            result = join_point.proceed()
+        except BaseException as error:
+            if attribute.rollback_on(error):
+                manager.rollback(status)
+            else:
+                manager.commit(status)
+            raise
+        manager.commit(status)
+        return result
+
+    async def _invoke_async(self, join_point: ProceedingJoinPoint, attribute: TransactionAttribute) -> Any:
+        if self._async_resolver is None:
+            manager = self._resolver(AsyncPlatformTransactionManager, attribute.transaction_manager)
+        else:
+            manager = await self._async_resolver(AsyncPlatformTransactionManager, attribute.transaction_manager)
+        if not isinstance(manager, AsyncPlatformTransactionManager):
+            raise IllegalTransactionStateError("Asynchronous transaction methods require AsyncPlatformTransactionManager")
+        status = await manager.get_transaction(attribute)
+        try:
+            result = await join_point.proceed()
+        except BaseException as error:
+            if attribute.rollback_on(error):
+                await manager.rollback(status)
+            else:
+                await manager.commit(status)
+            raise
+        await manager.commit(status)
+        return result

pythonboot/transaction/manager.py

@@ -0,0 +1,114 @@
+"""Contracts for synchronous and asynchronous resource transaction managers."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pythonboot.transaction.definition import TransactionDefinition
+
+
+class SavepointManager(ABC):
+    """Optional synchronous savepoint capability for nested transactions."""
+
+    @abstractmethod
+    def create_savepoint(self) -> Any:
+        """Create and return an opaque resource savepoint."""
+
+    @abstractmethod
+    def rollback_to_savepoint(self, savepoint: Any) -> None:
+        """Roll back to the given savepoint without completing the transaction."""
+
+    @abstractmethod
+    def release_savepoint(self, savepoint: Any) -> None:
+        """Release the given savepoint."""
+
+
+class AsyncSavepointManager(ABC):
+    """Optional asynchronous savepoint capability for nested transactions."""
+
+    @abstractmethod
+    async def create_savepoint(self) -> Any:
+        """Create and return an opaque resource savepoint."""
+
+    @abstractmethod
+    async def rollback_to_savepoint(self, savepoint: Any) -> None:
+        """Roll back to the given savepoint without completing the transaction."""
+
+    @abstractmethod
+    async def release_savepoint(self, savepoint: Any) -> None:
+        """Release the given savepoint."""
+
+
+class TransactionStatus(ABC):
+    """Expose transaction participation, rollback-only state, and completion."""
+
+    @property
+    @abstractmethod
+    def is_new_transaction(self) -> bool:
+        """Whether this scope owns a newly created physical transaction."""
+
+    @property
+    @abstractmethod
+    def has_transaction(self) -> bool:
+        """Whether this scope participates in a physical transaction."""
+
+    @property
+    @abstractmethod
+    def has_savepoint(self) -> bool:
+        """Whether this scope uses a savepoint in an existing transaction."""
+
+    @property
+    @abstractmethod
+    def is_rollback_only(self) -> bool:
+        """Whether the underlying transaction must be rolled back."""
+
+    @abstractmethod
+    def set_rollback_only(self) -> None:
+        """Mark the transaction for rollback even if the business method returns."""
+
+    @property
+    @abstractmethod
+    def is_completed(self) -> bool:
+        """Whether this scope has already been committed or rolled back."""
+
+
+class PlatformTransactionManager(ABC):
+    """Synchronous transaction manager implemented by resource-specific starters.
+
+    Managers implement propagation and isolation, reject unsupported options,
+    and validate status ownership and completion. Completion must release owned
+    resources and restore suspended contexts, including on failure. Participating
+    rollback marks the shared transaction rollback-only; an owner attempting to
+    commit that transaction must raise UnexpectedRollbackError.
+    """
+
+    @abstractmethod
+    def get_transaction(self, definition: TransactionDefinition | None = None) -> TransactionStatus:
+        """Create, join, suspend, or reject a transaction according to its definition."""
+
+    @abstractmethod
+    def commit(self, status: TransactionStatus) -> None:
+        """Complete a scope; only the owning scope commits the physical transaction."""
+
+    @abstractmethod
+    def rollback(self, status: TransactionStatus) -> None:
+        """Roll back an owned transaction or mark a participating transaction."""
+
+
+class AsyncPlatformTransactionManager(ABC):
+    """Asynchronous manager with the same completion contract as the sync manager.
+
+    Implementations must clean up resources on cancellation and prevent sharing
+    a non-concurrent resource transaction across independent asyncio tasks.
+    """
+
+    @abstractmethod
+    async def get_transaction(self, definition: TransactionDefinition | None = None) -> TransactionStatus:
+        """Create, join, suspend, or reject a transaction according to its definition."""
+
+    @abstractmethod
+    async def commit(self, status: TransactionStatus) -> None:
+        """Complete a scope; only the owning scope commits the physical transaction."""
+
+    @abstractmethod
+    async def rollback(self, status: TransactionStatus) -> None:
+        """Roll back an owned transaction or mark a participating transaction."""

pythonboot/util/__init__.py

@@ -0,0 +1,5 @@
+"""Public framework utility interfaces."""
+
+from pythonboot.util.context_util import ContextUtil
+
+__all__ = ["ContextUtil"]