ttasks 0.2.0__py3-none-any.whl

ttasks/__init__.py

@@ -0,0 +1,53 @@
+"""ttasks — a small task runner with DAG support.
+
+The public surface is intentionally flat: ``from ttasks import X`` is the
+canonical and only supported import path for every name in ``__all__``.
+"""
+
+from ._events import EventBus, TaskEvent, TaskEventType
+from ._exceptions import TaskCancelled, TaskExecutionError, TaskTimeoutError
+from ._executor import (
+    TaskContext,
+    TaskExecutor,
+    make_copilot_agent_handler,
+    make_copilot_prompt_handler,
+)
+from ._graph import TaskGraph
+from ._sqlite import SQLiteStore
+from ._store import (
+    InMemoryStore,
+    Store,
+)
+from ._task import Task, TaskResult, TaskStatus, TaskType
+
+__all__ = [
+    "EventBus",
+    "InMemoryStore",
+    "SQLiteStore",
+    "Store",
+    "Task",
+    "TaskCancelled",
+    "TaskContext",
+    "TaskExecutionError",
+    "TaskEvent",
+    "TaskEventType",
+    "TaskExecutor",
+    "TaskGraph",
+    "TaskResult",
+    "TaskTimeoutError",
+    "TaskStatus",
+    "TaskType",
+    "make_copilot_agent_handler",
+    "make_copilot_prompt_handler",
+]
+
+# Rewrite ``__module__`` on every public name so tracebacks and ``repr()`` show
+# ``ttasks.TaskTimeoutError`` rather than the internal submodule path. This is
+# the same idiom used verbatim by httpx, openai-python, and anthropic-python.
+import contextlib as _contextlib
+
+_locals = locals()
+for _name in __all__:
+    with _contextlib.suppress(TypeError, AttributeError):
+        _locals[_name].__module__ = "ttasks"
+del _locals, _name, _contextlib

ttasks/_events.py

@@ -0,0 +1,96 @@
+"""Task event types and publish/subscribe helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from threading import RLock
+
+from ._task import Task, TaskStatus
+
+
+class TaskEventType(Enum):
+    """Kinds of task events emitted during execution."""
+
+    STARTED = "started"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    BLOCKED = "blocked"
+    PERSISTENCE_FAILED = "persistence_failed"
+
+
+@dataclass(frozen=True)
+class TaskEvent:
+    """A task execution event delivered to event subscribers."""
+
+    type: TaskEventType
+    task_id: str
+    task: Task
+    timestamp: datetime
+    previous_status: TaskStatus | None
+    status: TaskStatus
+    error: str | None = None
+
+
+TaskEventHandler = Callable[[TaskEvent], None]
+
+
+class EventBus:
+    """Thread-safe publish/subscribe bus for task events."""
+
+    def __init__(self) -> None:
+        """Create an event bus with no subscribers or recorded errors."""
+        self._subscribers: list[TaskEventHandler] = []
+        self._errors: list[BaseException] = []
+        self._lock = RLock()
+
+    @property
+    def errors(self) -> list[BaseException]:
+        """Return subscriber errors recorded while emitting events."""
+        with self._lock:
+            return list(self._errors)
+
+    def subscribe(self, subscriber: TaskEventHandler) -> Callable[[], None]:
+        """Register subscriber and return an idempotent unsubscribe callback."""
+        if not callable(subscriber):
+            raise TypeError("subscriber must be callable")
+
+        with self._lock:
+            self._subscribers.append(subscriber)
+
+        def unsubscribe() -> None:
+            """Remove subscriber if it is still registered."""
+            with self._lock:
+                if subscriber in self._subscribers:
+                    self._subscribers.remove(subscriber)
+
+        return unsubscribe
+
+    @contextmanager
+    def subscribed(self, subscriber: TaskEventHandler) -> Iterator[None]:
+        """Subscribe for the duration of a ``with`` block, then auto-unsubscribe.
+
+        The callback is unsubscribed on normal exit and on exception so a
+        short-lived observer cannot leak past its scope.
+        """
+        unsubscribe = self.subscribe(subscriber)
+        try:
+            yield
+        finally:
+            unsubscribe()
+
+    def emit(self, event: TaskEvent) -> None:
+        """Publish event to subscribers without letting observers fail execution."""
+        with self._lock:
+            subscribers = list(self._subscribers)
+
+        for subscriber in subscribers:
+            try:
+                subscriber(event)
+            except BaseException as error:
+                with self._lock:
+                    self._errors.append(error)

ttasks/_exceptions.py

@@ -0,0 +1,45 @@
+"""Exceptions raised by task execution.
+
+Kept in a dedicated module so users can catch the full hierarchy without
+importing executor machinery and so the executor module stays focused on
+execution logic.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+
+class TaskCancelled(RuntimeError):
+    """Signal that task execution was cancelled.
+
+    Handlers should not mutate Task lifecycle state directly. They may raise
+    TaskCancelled to cooperatively abort; TaskExecutor owns the transition to
+    CANCELLED and records the terminal TaskResult.
+    """
+
+
+class TaskExecutionError(RuntimeError):
+    """Raised when a subprocess exits unsuccessfully.
+
+    completed preserves stdout, stderr, and returncode so TaskExecutor can
+    attach structured failure details to Task.result instead of keeping only
+    the exception string.
+    """
+
+    def __init__(self, message: str, completed: subprocess.CompletedProcess[str]):
+        """Create an execution error for completed."""
+        super().__init__(message)
+        self.completed = completed
+
+
+class TaskTimeoutError(TimeoutError):
+    """Raised when a subprocess exceeds its timeout.
+
+    completed preserves any output collected after terminating the process.
+    """
+
+    def __init__(self, message: str, completed: subprocess.CompletedProcess[str]):
+        """Create a timeout error for completed."""
+        super().__init__(message)
+        self.completed = completed