uv-task-runner 0.1.1__py3-none-any.whl

uv_task_runner/__init__.py

@@ -0,0 +1,29 @@
+from uv_task_runner import errors, pipeline, settings, task
+
+ConfigError = errors.ConfigError
+TaskError = errors.TaskError
+OnPipelineEnd = pipeline.OnPipelineEnd
+OnPipelineStart = pipeline.OnPipelineStart
+Pipeline = pipeline.Pipeline
+PipelineResult = pipeline.PipelineResult
+run_tasks = pipeline.run_tasks
+OnTaskEnd = task.OnTaskEnd
+OnTaskStart = task.OnTaskStart
+Settings = settings.Settings
+TaskConfig = task.TaskConfig
+TaskResult = task.TaskResult
+
+__all__ = [
+    "ConfigError",
+    "TaskError",
+    "OnPipelineEnd",
+    "OnPipelineStart",
+    "OnTaskEnd",
+    "OnTaskStart",
+    "Pipeline",
+    "PipelineResult",
+    "run_tasks",
+    "Settings",
+    "TaskConfig",
+    "TaskResult",
+]

uv_task_runner/__main__.py

@@ -0,0 +1,92 @@
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+#     "pydantic-settings>=2.13.1",
+# ]
+# ///
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+from pydantic_settings import (
+    BaseSettings,
+    CliSettingsSource,
+    PydanticBaseSettingsSource,
+    TomlConfigSettingsSource,
+)
+
+from uv_task_runner import pipeline, settings
+
+logger = logging.getLogger(__name__)
+
+
+class _CliSettings(settings.Settings):
+    """Settings subclass that adds CLI argument and TOML file parsing.
+
+    Used only by main(). Library users should construct Settings directly.
+    """
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        config_path, cli_args = settings._parse_config_path()
+        return (
+            init_settings,
+            CliSettingsSource(
+                settings_cls,
+                cli_parse_args=cli_args,
+                cli_kebab_case=True,
+                cli_implicit_flags=True,
+            ),
+            TomlConfigSettingsSource(settings_cls, toml_file=config_path),
+        )
+
+
+def main() -> None:
+    # Handle --init as a unique case then exit:
+    if "--init" in sys.argv[1:]:
+        import argparse
+
+        p = argparse.ArgumentParser(add_help=False)
+        p.add_argument("--init", nargs="?", const=settings.DEFAULT_CONFIG_PATH)
+        args, _ = p.parse_known_args(sys.argv[1:])
+        try:
+            dest = settings.write_template_config(args.init)
+            print(f"Created {dest}")
+        except FileExistsError as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            raise SystemExit(1) from None
+        return
+
+    config_path, _ = settings._parse_config_path()
+    if not Path(config_path).exists():
+        if "--config" in sys.argv[1:]:
+            print(f"Error: config file not found: {config_path}", file=sys.stderr)
+            raise SystemExit(1)
+        print(
+            f"No config file found at '{Path(config_path).resolve()}'. "
+            f"Run --init <dest> to create a template, or pass --config <src>.",
+            file=sys.stderr,
+        )
+
+    s = _CliSettings()
+
+    logging.basicConfig(
+        level=s.log_level,
+        format="%(asctime)s | %(levelname)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    pipeline.Pipeline.from_settings(s).run()
+
+
+if __name__ == "__main__":
+    main()

uv_task_runner/errors.py

@@ -0,0 +1,6 @@
+class ConfigError(Exception):
+    """Raised for invalid configuration: bad TOML, missing fields, invalid settings values."""
+
+
+class TaskError(Exception):
+    """Raised for task infrastructure failures: uv not found, script path missing, etc."""

uv_task_runner/pipeline.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import concurrent.futures as cf
+import logging
+import sys
+from dataclasses import dataclass
+from typing import Protocol
+
+from uv_task_runner import settings, task, utils
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class PipelineResult:
+    task_results: tuple[task.TaskResult, ...]
+    aborted: bool
+    aborted_by: str | None  # task_path that triggered fail_fast, or None
+
+
+class OnPipelineStart(Protocol):
+    def __call__(self) -> None: ...  # pragma: no cover
+
+
+class OnPipelineEnd(Protocol):
+    def __call__(self, pipeline_result: PipelineResult) -> None: ...  # pragma: no cover
+
+
+@dataclass
+class Pipeline:
+    tasks: list[task.TaskConfig]
+    parallel: bool = False
+    fail_fast: bool = False
+    log_multiline: bool = False
+    dry_run: bool = False
+    on_pipeline_start: OnPipelineStart | list[OnPipelineStart] | None = None
+    on_pipeline_end: OnPipelineEnd | list[OnPipelineEnd] | None = None
+
+    @classmethod
+    def from_settings(cls, s: settings.Settings) -> Pipeline:
+        return cls(
+            tasks=s.tasks,
+            parallel=s.parallel,
+            fail_fast=s.fail_fast,
+            log_multiline=s.log_multiline,
+            dry_run=s.dry_run,
+        )
+
+    def run(self) -> PipelineResult:
+        utils._call_hooks(self.on_pipeline_start)
+        if self.dry_run:
+            logger.info(f"DRY RUN: {len(self.tasks)} task(s) would run.")
+        else:
+            logger.info(f"Running {len(self.tasks)} task(s).")
+
+        task_results: list[task.TaskResult] = []
+        task_handles: dict[str, task._TaskHandle] = {}
+        aborted = False
+        aborted_by: str | None = None
+
+        def _execute(task_config: task.TaskConfig) -> task.TaskResult:
+            if self.dry_run:
+                result = task.dry_run_task(task_config)
+                utils._call_hooks(task_config.on_task_end, task_config.task_path, result)
+                return result
+            handle = task.run_task(task_config, log_multiline=self.log_multiline)
+            task_handles[task_config.task_path] = handle
+            result = task._collect_result(handle, wait=task_config.wait)
+            utils._call_hooks(task_config.on_task_end, task_config.task_path, result)
+            return result
+
+        def _should_abort(result: task.TaskResult) -> bool:
+            """Log task outcome. Return True if fail_fast should trigger."""
+            if result.exit_code is None:
+                msg = f"{result.task_path} is running: not waiting for it to finish."
+                if self.log_multiline:
+                    msg += " No output will be logged for this task, because log_multiline=true buffers until process exit."
+                logger.info(msg)
+                return False
+            if result.exit_code != 0:
+                logger.error(f"{result.task_path} failed with exit code {result.exit_code}")
+                return self.fail_fast
+            logger.info(f"{result.task_path} completed successfully.")
+            return False
+
+        if self.parallel:
+            with cf.ThreadPoolExecutor() as executor:
+                future_to_config = {executor.submit(_execute, tc): tc for tc in self.tasks}
+                for future in cf.as_completed(future_to_config):
+                    result = future.result()
+                    task_results.append(result)
+                    if _should_abort(result):
+                        aborted = True
+                        aborted_by = result.task_path
+                        logger.warning("Fail fast enabled: terminating any tasks still running.")
+                        for tp, handle in task_handles.items():
+                            if handle.process.poll() is None:
+                                logger.warning(f"Terminating {tp} with PID {handle.process.pid}")
+                                task._terminate_tree(handle.process)
+                        if sys.version_info >= (3, 9):
+                            executor.shutdown(wait=False, cancel_futures=True)  # pragma: no cover
+                        else:
+                            logger.warning("Python <3.9: pending futures cannot be cancelled.")
+                            executor.shutdown(wait=False)
+                        break
+        else:
+            for task_config in self.tasks:
+                result = _execute(task_config)
+                task_results.append(result)
+                if _should_abort(result):
+                    aborted = True
+                    aborted_by = result.task_path
+                    logger.warning("Fail fast enabled, exiting.")
+                    break
+
+        # Warn about still-running background processes
+        for tp, handle in task_handles.items():
+            if handle.process.poll() is None:
+                logger.warning(
+                    f"{tp} with PID {handle.process.pid} is still running after main "
+                    "process completed: subsequent messages from the task will not be "
+                    "captured (Hint: set TaskConfig.wait=true to change this behavior)"
+                )
+
+        pipeline_result = PipelineResult(
+            task_results=tuple(task_results),
+            aborted=aborted,
+            aborted_by=aborted_by,
+        )
+        utils._call_hooks(self.on_pipeline_end, pipeline_result)
+        return pipeline_result
+
+
+def run_tasks(
+    tasks: list[task.TaskConfig],
+    parallel: bool = False,
+    fail_fast: bool = False,
+    log_multiline: bool = False,
+    dry_run: bool = False,
+    on_pipeline_start: OnPipelineStart | list[OnPipelineStart] | None = None,
+    on_pipeline_end: OnPipelineEnd | list[OnPipelineEnd] | None = None,
+) -> PipelineResult:
+    """Convenience wrapper: construct a Pipeline and run it."""
+    return Pipeline(
+        tasks=tasks,
+        parallel=parallel,
+        fail_fast=fail_fast,
+        log_multiline=log_multiline,
+        dry_run=dry_run,
+        on_pipeline_start=on_pipeline_start,
+        on_pipeline_end=on_pipeline_end,
+    ).run()

uv_task_runner/settings.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource
+
+from uv_task_runner import task
+
+DEFAULT_CONFIG_PATH = Path("uv_task_runner.toml")
+
+_TEMPLATE_CONFIG_PATH = Path(__file__).parent / "template_config.toml"
+
+
+def write_template_config(dest: Path | str = DEFAULT_CONFIG_PATH) -> Path:
+    """Write the annotated default config to *dest*.
+
+    Returns the resolved path that was written.
+    Raises FileExistsError if *dest* already exists.
+    """
+    dest = Path(dest)
+    if dest.is_dir():
+        dest = dest.resolve() / DEFAULT_CONFIG_PATH
+    if dest.exists():
+        raise FileExistsError(f"{dest} already exists. Delete it or choose a different path.")
+    dest.write_text(_TEMPLATE_CONFIG_PATH.read_text(encoding="utf-8"), encoding="utf-8")
+    return dest.resolve()
+
+
+def _parse_config_path() -> tuple[str, list[str]]:
+    """Pre-parse --config before full settings initialization.
+
+    Returns (config_path, remaining_args) where remaining_args is sys.argv[1:]
+    with --config and its value removed. Pass remaining_args to CliSettingsSource
+    so the --config flag is not treated as an unrecognised argument.
+    """
+    import argparse
+
+    pre = argparse.ArgumentParser(add_help=False)
+    pre.add_argument("--config", default=DEFAULT_CONFIG_PATH)
+    args, remaining = pre.parse_known_args(sys.argv[1:])
+    return args.config, remaining
+
+
+class Settings(BaseSettings):
+    parallel: bool = False
+    fail_fast: bool = False
+    dry_run: bool = False
+    log_level: str | int = "INFO"
+    # Emit subprocess output line-by-line (false) or buffer per stream (true).
+    # Line-by-line is the default: output appears in real-time and is not lost
+    # for wait=false tasks. Set to true to keep multiline output (e.g. stack
+    # traces) together at the cost of buffering until the subprocess exits:
+    log_multiline: bool = False
+    tasks: list[task.TaskConfig] = Field(default_factory=list)
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        # Library-safe: only uses init kwargs. No CLI parsing, no TOML file.
+        # For CLI usage, see _CliSettings in __main__.py.
+        return (init_settings,)
+
+    @field_validator("log_level")
+    def validate_log_level(cls, v: str | int) -> str:
+        if isinstance(v, str) and v.isnumeric() or isinstance(v, int):
+            # Numeric value: look up the name
+            name = logging.getLevelName(int(v))
+            if name.startswith("Level "):
+                raise ValueError(f"Invalid log level: {v}")
+            return name
+        else:
+            # String name: normalise and verify it's a known level
+            level_name = v.upper()
+            if not isinstance(getattr(logging, level_name, None), int):
+                raise ValueError(f"Invalid log level: {v}")
+            return level_name

uv_task_runner/task.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import logging
+import os
+import signal
+import subprocess
+import sys
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import IO, Any, Callable, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from uv_task_runner import utils
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class OnTaskStart(Protocol):
+    def __call__(self, task_path: str, pid: int) -> None: ...  # pragma: no cover
+
+
+@runtime_checkable
+class OnTaskEnd(Protocol):
+    def __call__(self, task_path: str, result: TaskResult) -> None: ...  # pragma: no cover
+
+
+class TaskConfig(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    task_path: str
+    task_args: list[str] = Field(default_factory=list)
+    uv_run_args: list[str] = Field(default_factory=lambda: ["--quiet", "--script"])
+    wait: bool = True
+    # Hooks below are Python-only (not settable via TOML/CLI), and run in parent environment.
+    # Called synchronously; keep them fast. For slow operations open a background thread inside the hook itself.
+    on_task_start: OnTaskStart | list[OnTaskStart] | None = None
+    on_task_end: OnTaskEnd | list[OnTaskEnd] | None = None
+
+
+@dataclass(frozen=True)
+class TaskResult:
+    task_path: str
+    exit_code: int | None  # None if wait=False
+    success: bool
+    duration_seconds: float
+    stdout: str  # Empty string if wait=False
+    stderr: str  # Empty string if wait=False
+    pid: int
+
+
+@dataclass
+class _TaskHandle:
+    """Internal: bundles a running process with its output-capture state."""
+
+    process: subprocess.Popen
+    stdout_thread: threading.Thread
+    stderr_thread: threading.Thread
+    stdout_capture: list[str]
+    stderr_capture: list[str]
+    task_path: str
+    start_time: float
+
+
+def _pipe_to_log(
+    stream: IO[str],
+    log_fn: Callable[[str], None],
+    prefix: str,
+    buffer_output: bool = True,
+    capture: list[str] | None = None,  # mutated in-place
+) -> None:
+    """Read stream, send to logger, and optionally accumulate into capture list."""
+    if buffer_output:
+        content = stream.read()
+        if content.strip():
+            log_fn(f"{prefix}{content.rstrip()}")
+        if capture is not None:
+            capture.append(content)
+    else:
+        lines: list[str] = []
+        for line in stream:
+            log_fn(f"{prefix}{line.rstrip()}")
+            lines.append(line)
+        if capture is not None:
+            capture.append("".join(lines))
+
+
+def _terminate_tree(proc: subprocess.Popen) -> None:
+    """Terminate a process and all its children."""
+    if sys.platform.startswith("win"):
+        subprocess.run(["taskkill", "/F", "/T", "/PID", str(proc.pid)], capture_output=True)
+    else:
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+        except ProcessLookupError:
+            pass
+
+
+def _build_args(task_config: TaskConfig) -> list[str]:
+    if any(c in task_config.uv_run_args for c in ("--help", "-h")):
+        raise ValueError("uv_run_args cannot contain --help or -h")
+    if any(c in task_config.uv_run_args for c in ("--python", "-p")):
+        if "--no-project" not in task_config.uv_run_args:
+            logger.warning(
+                f"Detected --python without --no-project in uv_run_args for task {task_config.task_path}. "
+                "This may cause unexpected behavior if the task's Python version conflicts with the parent process's '.python-version' file. "
+            )
+    return ["uv", "run"] + task_config.uv_run_args + [task_config.task_path] + task_config.task_args
+
+
+def dry_run_task(task_config: TaskConfig) -> TaskResult:
+    """Log the command that would run without executing it. Returns a synthetic TaskResult."""
+    logger.info("DRY RUN: would run: %s", " ".join(_build_args(task_config)))
+    return TaskResult(
+        task_path=task_config.task_path,
+        exit_code=0,
+        success=True,
+        duration_seconds=0.0,
+        stdout="",
+        stderr="",
+        pid=0,
+    )
+
+
+def run_task(
+    task_config: TaskConfig,
+    popen_kwargs: dict[str, Any] | None = None,
+    log_multiline: bool = False,
+) -> _TaskHandle:
+    """Spawn a uv run subprocess for task_config. Fires on_task_start hooks.
+
+    Returns a _TaskHandle. Call pipeline._collect_result() to wait and get TaskResult.
+    """
+    task_path = task_config.task_path
+    args = _build_args(task_config)
+    kwargs = dict(popen_kwargs or {})
+    if sys.platform.startswith("win"):
+        kwargs.setdefault("start_new_session", True)
+    logger.debug(
+        "uv_run_args=%r task_args=%r popen_kwargs=%r",
+        task_config.uv_run_args,
+        task_config.task_args,
+        kwargs,
+    )
+    logger.info("Running command: %s", " ".join(args))
+    process = subprocess.Popen(
+        args, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, **kwargs
+    )
+    start_time = time.monotonic()
+    prefix = f"[{Path(task_path).name}:{process.pid}] "
+    logger.debug("Spawned pid=%s for %r", process.pid, task_path)
+
+    stdout_capture: list[str] = []
+    stderr_capture: list[str] = []
+    threads: list[threading.Thread] = []
+    for stream, capture in (
+        (process.stdout, stdout_capture),
+        (process.stderr, stderr_capture),
+    ):
+        t = threading.Thread(
+            target=_pipe_to_log,
+            kwargs={
+                "stream": stream,
+                "log_fn": logger.info,
+                "prefix": prefix,
+                "buffer_output": log_multiline,
+                "capture": capture,
+            },
+            daemon=True,
+        )
+        t.start()
+        threads.append(t)
+
+    if task_config.on_task_start:
+        logger.debug("Calling on_task_start hooks for %r with pid=%s", task_path, process.pid)
+        utils._call_hooks(task_config.on_task_start, task_path, process.pid)
+        logger.debug("on_task_start hooks complete for %r", task_path)
+
+    return _TaskHandle(
+        process=process,
+        stdout_thread=threads[0],
+        stderr_thread=threads[1],
+        stdout_capture=stdout_capture,
+        stderr_capture=stderr_capture,
+        task_path=task_path,
+        start_time=start_time,
+    )
+
+
+def _collect_result(handle: _TaskHandle, wait: bool) -> TaskResult:
+    """Wait for a running task (if wait=True) and return its TaskResult."""
+    if wait:
+        logger.debug("Waiting for pid=%s (%r) to exit", handle.process.pid, handle.task_path)
+        handle.process.wait()
+        handle.stdout_thread.join()
+        handle.stderr_thread.join()
+        logger.debug("pid=%s exited with code %s", handle.process.pid, handle.process.returncode)
+    return TaskResult(
+        task_path=handle.task_path,
+        exit_code=handle.process.returncode,
+        success=handle.process.returncode == 0,
+        duration_seconds=time.monotonic() - handle.start_time,
+        stdout=handle.stdout_capture[0] if handle.stdout_capture else "",
+        stderr=handle.stderr_capture[0] if handle.stderr_capture else "",
+        pid=handle.process.pid,
+    )

uv_task_runner/template_config.toml

@@ -0,0 +1,50 @@
+# uv_task_runner.toml — configuration for uv-task-runner
+#
+# Run tasks sequentially or in parallel. Each [[tasks]] entry is one task.
+# Paths are relative to this config file; GitHub raw file URLs are also supported.
+
+# ---------------------------------------------------------------------------
+# Global settings
+# ---------------------------------------------------------------------------
+
+# Run all tasks concurrently instead of sequentially (default: false)
+parallel = false
+
+# Abort remaining tasks as soon as one fails (default: false)
+fail_fast = false
+
+# Log the commands that would run without executing anything (default: false)
+dry_run = false
+
+# Logging verbosity: DEBUG | INFO | WARNING | ERROR | CRITICAL (default: "INFO")
+log_level = "INFO"
+
+# Buffer subprocess output per stream instead of streaming line-by-line.
+# false (default): output appears in real-time; never lost for wait=false tasks.
+# true: keeps multiline output (e.g. stack traces) together, but buffers until
+#       the subprocess exits.
+log_multiline = false
+
+# ---------------------------------------------------------------------------
+# Tasks — add one [[tasks]] block per script to run
+# ---------------------------------------------------------------------------
+
+# Minimal example: only task_path is required.
+# [[tasks]]
+# task_path = "scripts/my_script.py"
+
+# Full example showing all per-task options:
+#
+# [[tasks]]
+# task_path = "scripts/my_script.py"
+#
+# # Arguments forwarded to the script itself (default: [])
+# task_args = ["--param", "value"]
+#
+# # Arguments forwarded to `uv run` (default: ["--quiet", "--script"])
+# # Note: --python without --no-project will warn; --help/-h are disallowed.
+# uv_run_args = ["--quiet", "--script"]
+#
+# # Wait for this task to finish before continuing (default: true)
+# # Set false to fire-and-forget; the process outlives the main runner.
+# wait = true

uv_task_runner/utils.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+def _call_hooks(
+    hooks: Callable[..., None] | list[Callable[..., None]] | None,
+    *args: Any,
+    **kwargs: Any,
+) -> None:
+    """Call a single hook or each hook in a list with the given inputs.
+    No results are collected.
+
+    Hooks are called synchronously and block the caller until they return.
+    Keep hooks fast. If a hook needs to do slow I/O (e.g. network requests),
+    spawn a background thread inside the hook itself.
+
+    To pass extra context to a hook, use a closure or functools.partial:
+
+        def on_start(task_path: str, pid: int) -> None:
+            my_client.notify(task_path, pid, env=env)
+
+        TaskConfig(task_path="...", on_task_start=on_start)
+    """
+    if hooks is None:
+        return
+    for hook in [hooks] if callable(hooks) else hooks:
+        hook(*args, **kwargs)  # type: ignore[call-top-callable]

uv_task_runner-0.1.1.dist-info/METADATA

@@ -0,0 +1,353 @@
+Metadata-Version: 2.3
+Name: uv-task-runner
+Version: 0.1.1
+Summary: A simple utility to run multiple Python scripts sequentially or in parallel, with isolated environments, monitoring and error handling.
+Author: bjhardcastle
+Author-email: bjhardcastle <ben.hardcastle@alleninstitute.org>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: eval-type-backport ; python_full_version < '3.10'
+Requires-Python: >=3.8
+Project-URL: Issues, https://github.com/AllenNeuralDynamics/uv-task-runner/issues
+Project-URL: Repository, https://github.com/AllenNeuralDynamics/uv-task-runner
+Description-Content-Type: text/markdown
+
+# uv-task-runner
+
+Run multiple Python scripts in parallel or in sequence, with per-script dependency and Python version isolation via [uv](https://docs.astral.sh/uv/).
+
+Each script is invoked as `uv run <script>`, so scripts can declare their own dependencies and Python version using [PEP 723 inline metadata](https://peps.python.org/pep-0723/). No more shared mega-environments.
+
+[![PyPI](https://img.shields.io/pypi/v/uv-task-runner.svg?label=PyPI&color=blue)](https://pypi.org/project/uv-task-runner/)
+[![Python version](https://img.shields.io/pypi/pyversions/uv-task-runner)](https://pypi.org/project/uv-task-runner/)
+
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![Coverage](https://img.shields.io/badge/coverage-98%25-green?logo=codecov)](https://app.codecov.io/github/AllenNeuralDynamics/uv-task-runner)
+[![CI/CD](https://img.shields.io/github/actions/workflow/status/AllenNeuralDynamics/uv-task-runner/publish.yaml?label=CI/CD&logo=github)](https://github.com/AllenNeuralDynamics/uv-task-runner/actions/workflows/publish.yaml)
+[![GitHub issues](https://img.shields.io/github/issues/AllenNeuralDynamics/uv-task-runner?logo=github)](https://github.com/AllenNeuralDynamics/uv-task-runner/issues)
+
+
+---
+
+## Requirements
+
+- Python 3.8+
+- `uv` on PATH. See https://docs.astral.sh/uv/getting-started/installation/
+
+## Installation
+
+Make available globally:
+```bash
+uv install uv-task-runner
+```
+
+Or run CLI tool in temporary environment:
+```bash
+uv run uv-task-runner
+```
+
+Or add library to Python project:
+```bash
+uv add uv-task-runner
+```
+
+---
+
+## Usage
+
+### CLI
+
+Generate an annotated config file in the current directory:
+
+```bash
+uv run uv-task-runner --init              # writes uv_task_runner.toml
+uv run uv-task-runner --init my_tasks.toml  # custom path
+```
+
+Or write it by hand. Minimal `uv_task_runner.toml`:
+
+```toml
+[[tasks]]
+task_path = "scripts/preprocess.py"
+
+[[tasks]]
+task_path = "scripts/analyze.py"
+task_args = ["--output", "results/"]
+```
+
+Then run:
+
+```bash
+uv run uv-task-runner
+```
+
+Use a different config file:
+
+```bash
+uv run uv-task-runner --config path/to/config.toml
+```
+
+Override settings at the command line (CLI args take precedence over TOML):
+
+```bash
+uv run uv-task-runner --parallel --fail-fast --log-level DEBUG
+```
+
+Tasks can also be passed directly via `--tasks` as a JSON array (the TOML config is recommended for anything beyond a quick one-off, as shell escaping is error-prone):
+
+```bash
+# Single task
+uv run uv-task-runner --tasks "[{\"task_path\":\"scripts/my_script.py\"}]"
+
+# Multiple tasks with args
+uv run uv-task-runner --tasks "[{\"task_path\":\"scripts/a.py\"},{\"task_path\":\"scripts/b.py\",\"task_args\":[\"--verbose\"]}]"
+```
+
+Note: double quotes inside the JSON must be escaped with `\"`. All `TaskConfig` fields are supported.
+
+### Example output
+
+Given a `uv_task_runner.toml`:
+
+```toml
+# Tasks are executed in order below if parallel=false (default):
+[[tasks]]
+task_path = "examples/script_a.py"
+task_args = ["--param1", "updated_value"]
+wait = false # don't wait for script_a.py to finish before starting the next task
+
+[[tasks]]
+task_path = "https://gist.githubusercontent.com/TAJD/1d389deba4221343caef5155090674eb/raw/13984206c008fdb35d2d574fa76b682991f00a08/error_handling.py"
+
+[[tasks]]
+task_path = "examples/script_b.py"
+# if script does not declare dependencies with PEP 723 metadata it's possible to customize uv run args:
+uv_run_args = ["--python", "3.14", "--verbose", "--script", "--no-project"]
+
+[[tasks]]
+task_path = "examples/script_c.py"
+```
+
+Running `uv run uv-task-runner` produces:
+
+```
+2026-03-02 13:32:27 | INFO | Running 4 task(s).
+2026-03-02 13:32:27 | INFO | Running command: uv run --quiet --script examples/script_a.py --param1 updated_value
+2026-03-02 13:32:27 | INFO | examples/script_a.py is running: not waiting for it to finish.
+2026-03-02 13:32:27 | INFO | Running command: uv run --quiet --script https://gist.githubusercontent.com/TAJD/1d389deba4221343caef5155090674eb/raw/13984206c008fdb35d2d574fa76b682991f00a08/error_handling.py
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824] Error: The divisor 'b' cannot be zero.
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824] Error: The divisor 'b' cannot be zero.
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824] Stack trace:
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824]   File "C:\Users\BEN~1.HAR\AppData\Local\Temp\error_handlingjKocFl.py", line 52, in <module>
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824]     simple_example()
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824]   File "C:\Users\BEN~1.HAR\AppData\Local\Temp\error_handlingjKocFl.py", line 47, in simple_example
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824]     result = divide_numbers_stacktrace(10, 0)
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824]   File "C:\Users\BEN~1.HAR\AppData\Local\Temp\error_handlingjKocFl.py", line 37, in divide_numbers_stacktrace
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824]     return nested_division()
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824]   File "C:\Users\BEN~1.HAR\AppData\Local\Temp\error_handlingjKocFl.py", line 34, in nested_division
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824]     stack_trace = ''.join(traceback.format_stack())
+2026-03-02 13:32:27 | INFO | [error_handling.py:164824]
+2026-03-02 13:32:27 | INFO | https://gist.githubusercontent.com/TAJD/1d389deba4221343caef5155090674eb/raw/13984206c008fdb35d2d574fa76b682991f00a08/error_handling.py completed successfully.
+2026-03-02 13:32:27 | INFO | Running command: uv run --python 3.14 --verbose --script --no-project examples/script_b.py
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG uv 0.10.7 (08ab1a344 2026-02-27)
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Found project root: `C:\Users\ben.hardcastle\github\uv-plugin-architecture`
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG No workspace root found, using project root
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Ignoring discovered project due to `--no-project`
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG No project found; searching for Python interpreter
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Using request connect timeout of 10s and read timeout of 30s
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Searching for Python 3.14 in virtual environments, managed installations, search path, or registry
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Found `cpython-3.13.1-windows-x86_64-none` at `C:\Users\ben.hardcastle\github\uv-plugin-architecture\.venv\Scripts\python.exe` (active virtual environment)
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Skipping interpreter at `.venv\Scripts\python.exe` from active virtual environment: does not satisfy request `3.14`
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Found `cpython-3.13.1-windows-x86_64-none` at `C:\Users\ben.hardcastle\github\uv-plugin-architecture\.venv\Scripts\python.exe` (virtual environment)
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Skipping interpreter at `.venv\Scripts\python.exe` from virtual environment: does not satisfy request `3.14`
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Searching for managed installations at `C:\Users\ben.hardcastle\cache\uv\python`
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Skipping managed installation `cpython-3.13.1-windows-x86_64-none`: does not satisfy `3.14`
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Found `cpython-3.13.1-windows-x86_64-none` at `C:\Users\ben.hardcastle\github\uv-plugin-architecture\.venv\Scripts\python.exe` (first executable in the search path)
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Skipping interpreter at `.venv\Scripts\python.exe` from first executable in the search path: does not satisfy request `3.14`
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] INFO Fetching requested Python...
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Downloading https://github.com/astral-sh/python-build-standalone/releases/download/20260211/cpython-3.14.3%2B20260211-x86_64-pc-windows-msvc-install_only_stripped.tar.gz
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] DEBUG Extracting cpython-3.14.3-20260211-x86_64-pc-windows-msvc-install_only_stripped.tar.gz to temporary location: C:\Users\ben.hardcastle\cache\uv\python\.temp\.tmpajp9EC
+2026-03-02 13:32:27 | INFO | [script_b.py:145032] Downloading cpython-3.14.3-windows-x86_64-none (download) (21.3MiB)
+2026-03-02 13:32:35 | INFO | [script_a.py:162304] script_a.py loaded polars version 1.38.1
+2026-03-02 13:32:35 | INFO | [script_a.py:162304] script_a.py running on Python 3.11.9
+2026-03-02 13:32:35 | INFO | [script_a.py:162304] script_a.py successfully received param1 from command line: updated_value       
+2026-03-02 13:32:35 | INFO | [script_a.py:162304] script_a.py finished
+2026-03-02 13:32:38 | INFO | [script_b.py:145032]  Downloaded cpython-3.14.3-windows-x86_64-none (download)
+2026-03-02 13:32:38 | INFO | [script_b.py:145032] DEBUG Moving C:\Users\ben.hardcastle\cache\uv\python\.temp\.tmpajp9EC\python to C:\Users\ben.hardcastle\cache\uv\python\cpython-3.14.3-windows-x86_64-none
+2026-03-02 13:32:38 | INFO | [script_b.py:145032] DEBUG Created link C:\Users\ben.hardcastle\cache\uv\python\cpython-3.14-windows-x86_64-none -> C:\Users\ben.hardcastle\cache\uv\python\cpython-3.14.3-windows-x86_64-none
+2026-03-02 13:32:39 | INFO | [script_b.py:145032] DEBUG Using Python 3.14.3 interpreter at: C:\Users\ben.hardcastle\cache\uv\python\cpython-3.14.3-windows-x86_64-none\python.exe
+2026-03-02 13:32:39 | INFO | [script_b.py:145032] DEBUG Running `python examples/script_b.py`
+2026-03-02 13:32:39 | INFO | [script_b.py:145032] script_b.py loaded on Python 3.14.3
+2026-03-02 13:32:39 | INFO | [script_b.py:145032] Traceback (most recent call last):
+2026-03-02 13:32:39 | INFO | [script_b.py:145032]   File "C:\Users\ben.hardcastle\github\uv-plugin-architecture\scripts\script_b.py", line 5, in <module>
+2026-03-02 13:32:39 | INFO | [script_b.py:145032]     raise ValueError(f"Simulated error in {Path(__file__).name}")
+2026-03-02 13:32:39 | INFO | [script_b.py:145032] ValueError: Simulated error in script_b.py
+2026-03-02 13:32:39 | INFO | [script_b.py:145032] DEBUG Command exited with code: 1
+2026-03-02 13:32:39 | ERROR | examples/script_b.py failed with exit code 1
+2026-03-02 13:32:39 | INFO | Running command: uv run --quiet --script examples/script_c.py
+2026-03-02 13:32:44 | INFO | [script_c.py:36208] script_c.py loaded on Python 3.13.1
+2026-03-02 13:32:44 | INFO | [script_c.py:36208] script_c.py finished
+2026-03-02 13:32:44 | INFO | examples/script_c.py completed successfully.
+```
+
+Key things to note:
+- `script_a.py` has `wait=false`: it starts immediately and execution continues without waiting for it. With `log_multiline=true`, its output is buffered until exit — but since the parent exits first, **no output is captured** and a warning is emitted.
+- `error_handling.py` is fetched from a URL. Its multiline stderr (a stack trace) is emitted as a single log block because `log_multiline=true`.
+- `script_b.py` exits non-zero, logged at `ERROR` level.
+- `script_c.py` mixes stdout lines directly into the log stream (lines without the `[name:pid]` prefix come from the script's own `print()` calls).
+
+### Python API
+
+```python
+from uv_task_runner import run_tasks, TaskConfig
+
+results = run_tasks([
+    TaskConfig(task_path="scripts/preprocess.py"),
+    TaskConfig(task_path="scripts/analyze.py", task_args=["--output", "results/"]),
+])
+
+for r in results.task_results:
+    print(r.task_path, r.exit_code, r.duration_seconds)
+```
+
+For more control, use `Pipeline` directly:
+
+```python
+from uv_task_runner import Pipeline, Settings, TaskConfig
+
+pipeline = Pipeline(
+    tasks=[
+        TaskConfig(task_path="scripts/a.py"),
+        TaskConfig(task_path="scripts/b.py"),
+    ],
+    parallel=True,
+    fail_fast=True,
+)
+result = pipeline.run()
+print(result.aborted, result.aborted_by)
+```
+
+---
+
+## Configuration reference
+
+### Global settings applied to `Pipeline`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `parallel` | bool | `false` | Run all tasks concurrently. `false` runs them one at a time in listed order. |
+| `fail_fast` | bool | `false` | Terminate remaining tasks on the first failure. |
+| `dry_run` | bool | `false` | Print what would run without executing any tasks. |
+| `log_level` | string or int | `"INFO"` | Standard logging level names: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`, case-insensitive. |
+| `log_multiline` | bool | `false` | Buffer each task's stdout/stderr and emit as a single log message per stream. Default `false` logs lines as they arrive. With `parallel=true`, interleaved output from concurrent tasks can make multiline output (e.g. stack traces) hard to read: set `log_multiline=true` to keep them together at the cost of buffering until process exit. Has no readability effect when `parallel=false`. |
+
+### Per-task settings applied to `TaskConfig`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `task_path` | string | required | Path to the script, relative to the config file. Can also be a URL (e.g. a GitHub raw file). |
+| `task_args` | list[string] | `[]` | Arguments passed to the script (`sys.argv`). |
+| `uv_run_args` | list[string] | `["--quiet", "--script"]` | Arguments passed to `uv run` before the script path. |
+| `wait` | bool | `true` | Wait for the task to finish before proceeding. `false` spawns the process and continues immediately. |
+
+### Callback hooks (Python API only)
+
+`TaskConfig` accepts Python callables for `on_task_start` and `on_task_end`. These are not settable via TOML.
+
+```python
+def on_start(task_path: str, pid: int) -> None:
+    print(f"Started {task_path} (PID {pid})")
+
+def on_end(task_path: str, result: TaskResult) -> None:
+    print(f"{task_path} exited {result.exit_code} after {result.duration_seconds:.1f}s")
+
+TaskConfig(
+    task_path="scripts/a.py",
+    on_task_start=on_start,
+    on_task_end=on_end,
+)
+```
+
+`Pipeline` accepts `on_pipeline_start` and `on_pipeline_end` in the same way.
+
+Hooks run synchronously in the parent process. Keep them fast; for slow operations, open a background thread inside the hook.
+
+---
+
+## How scripts are run
+
+Each task is executed as:
+
+```
+uv run [uv_run_args] [task_path] [task_args]
+```
+
+Scripts can declare their own Python version and dependencies using PEP 723 metadata:
+
+```python
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["polars>=0.20", "requests"]
+# ///
+
+import polars as pl
+# ...
+```
+
+`uv` resolves and installs dependencies for each script independently. Scripts with different Python versions or incompatible dependency sets run without conflict.
+
+---
+
+## Return values
+
+`Pipeline.run()` and `run_tasks()` return a `PipelineResult`:
+
+```python
+@dataclass
+class PipelineResult:
+    task_results: list[TaskResult]
+    aborted: bool           # True if fail_fast triggered early termination
+    aborted_by: str | None  # task_path that caused the abort, or None
+```
+
+Each `TaskResult`:
+
+```python
+@dataclass
+class TaskResult:
+    task_path: str
+    exit_code: int | None   # None if wait=False
+    success: bool
+    duration_seconds: float
+    stdout: str             # Empty string if wait=False
+    stderr: str             # Empty string if wait=False
+    pid: int
+```
+
+The CLI entry point always exits with code 0. Inspect `PipelineResult` when using the Python API.
+
+---
+
+## Limitations
+
+**No DAG-style task dependencies.** Sequential pipelines with `fail_fast=True` naturally express
+linear chains ("run B only after A succeeds"). What is not supported is graph-style dependencies,
+e.g. "run C after both A and B succeed" when A and B run in parallel. To implement phased parallel
+execution, call `run_tasks()` or `Pipeline.run()` multiple times in sequence, or consider Snakemake,
+Airflow, Prefect, or similar tools.
+
+**`log_multiline=true` always buffers until process exit.** Output is held in a `stream.read()` call that blocks until the subprocess closes stdout. For normal `wait=true` tasks this means output appears as a single block at the end rather than in real-time. For `wait=false` (fire-and-forget) tasks it is worse: if the parent exits before the subprocess finishes, the daemon thread is killed and **no output is logged at all**. The default (`log_multiline=false`) logs lines as they arrive, which avoids both problems at the cost of interleaved output from concurrent tasks.
+
+`TaskResult.stdout`/`stderr` are always empty for `wait=false` tasks regardless of buffering mode, because the capture threads are not joined before the result is collected. The subprocess will be reported as still running on pipeline exit.
+
+**No per-task timeouts.** A hung task will block indefinitely. As a workaround, wrap the script invocation with `timeout` (Unix) or a similar mechanism.
+
+**No task naming.** Tasks are identified by `task_path` in results and log output. Long paths or URLs can make logs harder to read.

uv_task_runner-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+uv_task_runner/__init__.py,sha256=aN6TA-qOIxLnTzmm9J3WPELA6v47gv5jOSOFp_ozXvY,689
+uv_task_runner/__main__.py,sha256=AjJ5LfchuddF_FuOvDYW7ChWlgO3-EX9Q-_25T9zRmI,2655
+uv_task_runner/errors.py,sha256=KbwjWWn_V22PFnSR7qQe9S4FJXIZ6sGF6dE__vvUNIg,246
+uv_task_runner/pipeline.py,sha256=SU3nVu57V9jUcLgaMu2JptPDoDQcuHnoR9ACRM2t8bE,6013
+uv_task_runner/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+uv_task_runner/settings.py,sha256=yzf8BWVQUhVl7mMRjH8gwW48TKFUUgZsKrhX63iJgdg,3254
+uv_task_runner/task.py,sha256=b8jLVPM1kmZHHZzAeZcbY6PX5Q-cH7XmKuixLeOtYt8,7053
+uv_task_runner/template_config.toml,sha256=gGT4PJf0jKVQAQQnyFbNZG2-7cRT8oFqao1ZvB71PiI,1891
+uv_task_runner/utils.py,sha256=asxG8N8kTmkQ_RexJaohL6fVN8CxHAmQ1crQ-9wSKiw,921
+uv_task_runner-0.1.1.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+uv_task_runner-0.1.1.dist-info/entry_points.txt,sha256=6Z7L5bvTNHhU_8huNXXJGLIBeTNEGC7GcBPb-7eqjjs,88
+uv_task_runner-0.1.1.dist-info/METADATA,sha256=6SrHYYXRCp7qQ6xkHlZomodkqu-niamsf9CtfknQVdc,18259
+uv_task_runner-0.1.1.dist-info/RECORD,,

uv_task_runner-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any

uv_task_runner-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+task = poethepoet:main
+uv-task-runner = uv_task_runner.__main__:main
+