ttasks 0.2.1__tar.gz → 0.3.0__tar.gz

{ttasks-0.2.1 → ttasks-0.3.0}/.github/workflows/docs.yml

@@ -35,8 +35,11 @@ jobs:
       - name: Install dependencies
         run: uv sync --group dev
 
+      - name: Build user documentation
+        run: uv run mkdocs build --strict --site-dir site
+
       - name: Build API documentation
-        run: uv run pdoc ttasks --output-directory site
+        run: uv run pdoc ttasks --output-directory site/api
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3

ttasks-0.3.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: ttasks
+Version: 0.3.0
+Summary: Add your description here
+Requires-Python: >=3.12
+Requires-Dist: github-copilot-sdk>=0.1.0
+Description-Content-Type: text/markdown
+
+# ttasks
+
+A small Python task ledger, executor, and DAG workflow library.
+
+`ttasks` models work as `Task` objects, executes them through a configurable
+`TaskExecutor`, persists them through an optional `Store`, and runs dependency
+graphs with `TaskGraph`.
+
+## Requirements
+
+- Python 3.12+
+- `uv` for the development workflow used by this repository
+- GitHub Copilot authentication for `TaskType.PROMPT` and `TaskType.AGENT` tasks
+
+## Quick start
+
+```python
+from ttasks import Task, TaskExecutor
+
+executor = TaskExecutor()
+task = Task.bash("echo hello", title="Say hello")
+
+result = executor.execute(task)
+
+assert task.is_done
+assert result.output == "hello\n"
+assert task.result is result
+```
+
+## What it provides
+
+- `Task` and `TaskResult` domain objects for tracking work and outcomes.
+- `TaskExecutor` for running Bash, PowerShell, Copilot prompt, Copilot agent, or
+  custom handler tasks.
+- Event streams for lifecycle, progress, and subprocess output updates.
+- `TaskGraph` for dependency-ordered DAG workflows with finally tasks.
+- In-memory and SQLite stores for task and graph persistence.
+- Async single-task submission, graceful shutdown, cancellation, timeouts, and
+  opt-in single-task retries.
+
+## Documentation
+
+User docs are published with the generated API reference on GitHub Pages:
+
+- [Quickstart](https://ipdelete.github.io/ttasks/quickstart/)
+- [Tutorials](https://ipdelete.github.io/ttasks/tutorials/task-execution/)
+- [Patterns](https://ipdelete.github.io/ttasks/patterns/finally-tasks/)
+- [API reference](https://ipdelete.github.io/ttasks/api/)
+
+Build the docs locally:
+
+```bash
+uv run mkdocs build --strict --site-dir site
+uv run pdoc ttasks --output-directory site/api
+```
+
+## Development
+
+Run the project checks:
+
+```bash
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
+
+Run the full suite including live tests:
+
+```bash
+uv run pytest -o addopts='' --cov=ttasks --cov-report=term-missing --cov-fail-under=100
+```

ttasks-0.3.0/README.md

@@ -0,0 +1,71 @@
+# ttasks
+
+A small Python task ledger, executor, and DAG workflow library.
+
+`ttasks` models work as `Task` objects, executes them through a configurable
+`TaskExecutor`, persists them through an optional `Store`, and runs dependency
+graphs with `TaskGraph`.
+
+## Requirements
+
+- Python 3.12+
+- `uv` for the development workflow used by this repository
+- GitHub Copilot authentication for `TaskType.PROMPT` and `TaskType.AGENT` tasks
+
+## Quick start
+
+```python
+from ttasks import Task, TaskExecutor
+
+executor = TaskExecutor()
+task = Task.bash("echo hello", title="Say hello")
+
+result = executor.execute(task)
+
+assert task.is_done
+assert result.output == "hello\n"
+assert task.result is result
+```
+
+## What it provides
+
+- `Task` and `TaskResult` domain objects for tracking work and outcomes.
+- `TaskExecutor` for running Bash, PowerShell, Copilot prompt, Copilot agent, or
+  custom handler tasks.
+- Event streams for lifecycle, progress, and subprocess output updates.
+- `TaskGraph` for dependency-ordered DAG workflows with finally tasks.
+- In-memory and SQLite stores for task and graph persistence.
+- Async single-task submission, graceful shutdown, cancellation, timeouts, and
+  opt-in single-task retries.
+
+## Documentation
+
+User docs are published with the generated API reference on GitHub Pages:
+
+- [Quickstart](https://ipdelete.github.io/ttasks/quickstart/)
+- [Tutorials](https://ipdelete.github.io/ttasks/tutorials/task-execution/)
+- [Patterns](https://ipdelete.github.io/ttasks/patterns/finally-tasks/)
+- [API reference](https://ipdelete.github.io/ttasks/api/)
+
+Build the docs locally:
+
+```bash
+uv run mkdocs build --strict --site-dir site
+uv run pdoc ttasks --output-directory site/api
+```
+
+## Development
+
+Run the project checks:
+
+```bash
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
+
+Run the full suite including live tests:
+
+```bash
+uv run pytest -o addopts='' --cov=ttasks --cov-report=term-missing --cov-fail-under=100
+```

ttasks-0.3.0/docs/index.md

@@ -0,0 +1,24 @@
+# ttasks
+
+`ttasks` is a small Python task ledger, executor, and DAG workflow library.
+
+Use it when you want to model units of work as durable Python objects, execute
+them through explicit handlers, observe progress and output, and compose them
+into dependency graphs.
+
+## Start here
+
+- [Quickstart](quickstart.md): run one task and one graph.
+- [Task execution tutorial](tutorials/task-execution.md): learn tasks, handlers,
+  results, events, and persistence.
+- [Graph workflows tutorial](tutorials/graph-workflows.md): build DAGs with
+  dependencies and outcome views.
+- [Finally tasks pattern](patterns/finally-tasks.md): run cleanup, reporting, and
+  artifact tasks after success or failure.
+
+## API reference
+
+The API reference is generated from docstrings with `pdoc` and published
+alongside these guides.
+
+<a href="api/">Open the API reference</a>

ttasks-0.3.0/docs/patterns/finally-tasks.md

@@ -0,0 +1,115 @@
+# Finally tasks
+
+Finally tasks are graph-scheduling semantics for work that should run after one
+or more upstream tasks become inactive. They are useful for cleanup, reporting,
+artifact collection, and recommendations.
+
+They are not Python `finally` blocks, and they are not graph-level retry. They
+are regular tasks with special readiness rules inside `TaskGraph`.
+
+## Basic form
+
+```python
+from ttasks import Task, TaskGraph
+
+lint = Task.bash("ruff check .", title="Lint")
+test = Task.bash("pytest", title="Tests")
+report = Task.bash("python scripts/report.py", title="Write report")
+
+graph = TaskGraph(title="preflight")
+graph.add(lint)
+graph.add(test)
+graph.add(report, after=[lint, test], finally_=True)
+```
+
+The finally task becomes ready once every listed `after` task is no longer
+active, even if one failed, was cancelled, or became blocked.
+
+## Cleanup after failed work
+
+Use a required finally task for cleanup that must succeed for the graph to be
+healthy.
+
+```python
+build = Task.bash("make build", title="Build")
+cleanup = Task.bash("rm -rf .tmp-build", title="Clean temporary files")
+
+graph.add(build)
+graph.add(cleanup, after=[build], finally_=True)
+```
+
+If `build` fails, `cleanup` still runs. If `cleanup` fails, it is a required
+task by default, so `graph.ok` is false.
+
+## Reports and artifacts
+
+A finally task receives the listed `after` tasks through `context.upstream`, just
+like a normal dependency. Use that to summarize results or collect artifact
+paths.
+
+```python
+def write_report(context):
+    lines = []
+    for upstream in context.upstream.values():
+        result = upstream.result
+        lines.append(f"{upstream.title}: {upstream.status.value}")
+        if result and result.error:
+            lines.append(result.error)
+    return "\n".join(lines)
+```
+
+Only direct dependencies are included. If a report needs an earlier ancestor,
+add that ancestor as an explicit dependency.
+
+## Optional recommendations
+
+Use `required=False` for best-effort reporting, artifact collection, or Copilot
+recommendation tasks. Their failures are visible, but they do not make
+`graph.ok` false by themselves.
+
+```python
+recommend = Task.prompt(
+    "Summarize preflight output and recommend the next action.",
+    title="Copilot recommendation",
+)
+
+graph.add(
+    recommend,
+    after=[lint, test, report],
+    finally_=True,
+    required=False,
+)
+```
+
+This is useful when the primary work should remain authoritative, but optional
+diagnostics should still appear in the run summary.
+
+## Required vs optional
+
+| Setting | Failure effect | Good use |
+| --- | --- | --- |
+| `required=True` | Failure makes `graph.ok` false | Cleanup that must complete |
+| `required=False` | Failure is reported but does not make `graph.ok` false | Reports, artifact collection, AI recommendations |
+
+Required and optional finally tasks are available through introspection views:
+
+- `graph.finally_tasks`
+- `graph.optional_tasks`
+- `graph.required_tasks`
+- `graph.optional_failed`
+- `graph.required_failed`
+- `graph.required_blocked`
+
+`graph.ok` remains the authoritative success predicate.
+
+## Runnable example
+
+The repository includes a local deterministic example:
+
+```bash
+uv run python examples/finally_tasks.py
+```
+
+It demonstrates failed primary work, cleanup that still runs, report generation,
+and an optional recommendation task whose failure is visible without changing
+the required outcome.

ttasks-0.3.0/docs/patterns/progress-and-output.md

@@ -0,0 +1,60 @@
+# Progress and output
+
+Every executor has an `EventBus` for task lifecycle events.
+
+```python
+from ttasks import TaskEvent, TaskEventType
+
+seen: list[TaskEvent] = []
+
+with executor.events.subscribed(seen.append):
+    executor.execute(task)
+
+assert [event.type for event in seen] == [
+    TaskEventType.STARTED,
+    TaskEventType.SUCCEEDED,
+]
+```
+
+For long-lived subscribers, use `executor.events.subscribe(callback)`, which
+returns an idempotent unsubscribe callable.
+
+## Event payloads
+
+Events include:
+
+- `type`: `STARTED`, `PROGRESS`, `OUTPUT`, `SUCCEEDED`, `FAILED`, `CANCELLED`,
+  `BLOCKED`, or `PERSISTENCE_FAILED`
+- `task_id`
+- `task`
+- `previous_status`
+- `status`
+- `timestamp`
+- `error`, when relevant
+- `progress_percent` and `progress_message`, when `type` is `PROGRESS`
+- `output_stream` and `output_chunk`, when `type` is `OUTPUT`
+
+Subscriber exceptions do not fail task execution. They are recorded on
+`executor.events.errors` so observers cannot break the work they observe.
+
+## Progress events
+
+Handlers can report progress without changing task lifecycle state:
+
+```python
+def handler(context):
+    context.emit_progress(25, "warming up")
+    context.emit_progress(message="still working")
+    return "done"
+```
+
+Progress percentages are optional finite values from 0 through 100. They are not
+required to be monotonic.
+
+## Streaming subprocess output
+
+Built-in subprocess handlers emit `OUTPUT` events as stdout and stderr lines are
+read. Complete stdout and stderr are still retained on the terminal
+`TaskResult`.
+
+Output subscribers run synchronously on reader threads, so keep callbacks fast.

ttasks-0.3.0/docs/patterns/retries-and-cancellation.md

@@ -0,0 +1,59 @@
+# Retries and cancellation
+
+## Single-task retries
+
+Single-task retries are opt-in with `RetryPolicy`.
+
+```python
+from ttasks import RetryPolicy, Task, TaskExecutor
+
+executor = TaskExecutor()
+task = Task.bash("./flaky-command", title="Flaky command")
+
+result = executor.execute(
+    task,
+    retry_policy=RetryPolicy(max_attempts=3, backoff=0.5),
+)
+```
+
+`max_attempts` is the total attempt count, including the first run. `backoff` is
+the number of seconds to sleep between failed attempts.
+
+Retries apply to single-task `execute()` and `submit()` calls. Graph-level retry
+is not provided by this policy.
+
+Each attempt emits its normal lifecycle events, and `task.result` reflects only
+the final attempt.
+
+## Cancellation is not retried
+
+Cancellation is terminal for retry policy purposes. Handlers may cooperatively
+abort by raising `TaskCancelled`; the executor owns the transition to
+`CANCELLED` and records the terminal `TaskResult`.
+
+Cancel a task through the executor to also terminate any active subprocess:
+
+```python
+executor.cancel(task)
+```
+
+For asynchronous work, prefer `executor.cancel(task)` over `future.cancel()`.
+`future.cancel()` can only cancel work that has not started yet.
+
+## Timeouts
+
+`Task.timeout` defaults to `None`, which means no automatic timeout is applied.
+
+```python
+Task.bash("sleep 30", title="Long task")
+```
+
+Use a positive timeout for bounded subprocess execution:
+
+```python
+Task.bash("sleep 30", title="Bounded task", timeout=5)
+```
+
+If the timeout is exceeded, the executor terminates the subprocess, marks the
+task failed, stores the timeout message in `task.error`, attaches a failed
+`TaskResult`, and raises `TaskTimeoutError`.

ttasks-0.3.0/docs/quickstart.md

@@ -0,0 +1,51 @@
+# Quickstart
+
+## Run one task
+
+```python
+from ttasks import Task, TaskExecutor
+
+executor = TaskExecutor()
+task = Task.bash("echo hello", title="Say hello")
+
+result = executor.execute(task)
+
+assert task.is_done
+assert result.output == "hello\n"
+assert task.result is result
+```
+
+`TaskExecutor` registers built-in handlers for Bash, PowerShell, Copilot prompt,
+and Copilot agent tasks. You can override any handler or create an executor with
+no defaults by using `TaskExecutor.empty()`.
+
+## Run a graph
+
+```python
+from ttasks import Task, TaskExecutor, TaskGraph
+
+build = Task.bash("echo build", title="Build")
+test = Task.bash("echo test", title="Test")
+package = Task.bash("echo package", title="Package")
+
+graph = TaskGraph(title="build pipeline")
+graph.add(build)
+graph.add(test, after=[build])
+graph.add(package, after=[test])
+
+graph.run(TaskExecutor())
+
+assert graph.ok
+assert graph.succeeded == [build, test, package]
+```
+
+If a task fails or is cancelled, downstream tasks are marked blocked and are not
+submitted. Use [finally tasks](patterns/finally-tasks.md) for cleanup and
+reporting work that should still run after failure.
+
+## Build docs locally
+
+```bash
+uv run mkdocs build --strict --site-dir site
+uv run pdoc ttasks --output-directory site/api
+```

ttasks-0.3.0/docs/reference/api.md

@@ -0,0 +1,13 @@
+# API reference
+
+The API reference is generated from docstrings with `pdoc` as part of the docs
+build.
+
+<a href="../../api/">Open the generated API reference</a>
+
+Local build:
+
+```bash
+uv run mkdocs build --strict --site-dir site
+uv run pdoc ttasks --output-directory site/api
+```

ttasks-0.3.0/docs/tutorials/async-execution.md

@@ -0,0 +1,48 @@
+# Async execution
+
+Use `submit()` for asynchronous single-task execution.
+
+```python
+from ttasks import Task, TaskExecutor
+
+with TaskExecutor() as executor:
+    task = Task.bash("echo async", title="Async example")
+    future = executor.submit(task)
+    result = future.result()
+
+assert result.output == "async\n"
+```
+
+`submit()` runs the same `execute()` path, so lifecycle events,
+auto-persistence, progress events, output events, results, and handler errors
+behave the same way as synchronous execution.
+
+## Shutdown
+
+The worker pool is created lazily on the first `submit()` call.
+
+```python
+executor.shutdown()
+assert executor.is_shutdown
+```
+
+`shutdown()` is idempotent, rejects later `submit()` calls, and waits for
+already-submitted tasks to finish, including queued tasks that have not started
+yet. It does not cancel running or queued tasks.
+
+`close()` is an alias for `shutdown()`, and the context-manager protocol closes
+the executor on exit.
+
+## Cancellation
+
+Use `executor.cancel(task)` for cooperative cancellation because
+`future.cancel()` can only cancel work that has not started yet.
+
+```python
+future = executor.submit(task)
+executor.cancel(task)
+```
+
+Graph execution owns graph-level scheduling. The async submit API is a
+single-task primitive; graph dependencies and finally-task semantics remain on
+`TaskGraph`.

ttasks-0.3.0/docs/tutorials/graph-workflows.md

@@ -0,0 +1,70 @@
+# Graph workflows
+
+`TaskGraph` runs tasks as a directed acyclic graph. Dependencies must be
+registered in the graph before `run()`.
+
+```python
+from ttasks import Task, TaskExecutor, TaskGraph
+
+build = Task.bash("echo build", title="Build")
+test = Task.bash("echo test", title="Test")
+package = Task.bash("echo package", title="Package")
+
+graph = TaskGraph(title="build pipeline")
+graph.add(build)
+graph.add(test, after=[build])
+graph.add(package, after=[test])
+
+graph.run(TaskExecutor())
+```
+
+## Reading outcomes
+
+Useful graph views include:
+
+- `graph.succeeded`
+- `graph.failed`
+- `graph.cancelled`
+- `graph.blocked`
+- `graph.finally_tasks`
+- `graph.optional_tasks`
+- `graph.required_tasks`
+- `graph.optional_failed`
+- `graph.required_failed`
+- `graph.required_blocked`
+- `graph.errors`
+- `graph.roots()`
+- `graph.leaves()`
+
+`graph.ok` is the authoritative success predicate. Optional finally-task
+failures are visible through outcome views without making `graph.ok` false.
+
+## Failure behavior
+
+If a task fails or is cancelled, downstream tasks are blocked and not submitted.
+Executor or setup errors raised by submitted futures are available in
+`graph.errors`, keyed by task ID.
+
+Already-succeeded tasks count as satisfied dependencies, so a graph can be rerun
+or extended after partial completion.
+
+## Upstream context
+
+When a graph submits a task, its handler receives direct dependency task refs in
+`context.upstream`. The refs come from the graph itself and are keyed by task ID:
+
+```python
+def handler(context):
+    parent = context.upstream[build.id]
+    assert parent.result is not None
+    return parent.result.output.upper()
+```
+
+Only direct dependencies are included. If a task needs an earlier ancestor, add
+that ancestor as an explicit graph dependency.
+
+## Finally tasks
+
+Use [finally tasks](../patterns/finally-tasks.md) for cleanup, reporting, and
+artifact collection work that should run after dependencies are inactive even if
+they failed or were blocked.