uv-script 0.1.5__tar.gz

uv_script-0.1.5/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: uv-script
+Version: 0.1.5
+Summary: A lightweight script runner for uv — define and run project scripts from pyproject.toml
+Author: Felix Simkovic
+Author-email: Felix Simkovic <felixsimkovic@me.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# uv-script
+
+[![PyPI](https://img.shields.io/pypi/v/uv-script)](https://pypi.org/project/uv-script/)
+
+A lightweight, zero-dependency script runner for [uv](https://docs.astral.sh/uv/). Define project scripts in `pyproject.toml` and run them through `uv run`.
+
+```
+$ uvs --list
+  check   lint -> test
+  format  ruff format src/
+  lint    ruff check src/
+  test    pytest tests/ -v
+```
+
+## Why?
+
+uv is a fantastic package manager but has no built-in task runner. If you've been using [Hatch](https://hatch.pypa.io/) just for its scripts, or reaching for [Poe the Poet](https://poethepoet.natn.io/) / [Taskipy](https://github.com/taskipy/taskipy) to fill the gap, `uvs` offers a simpler alternative:
+
+- **Zero runtime dependencies** — stdlib only (`tomllib`, `argparse`, `subprocess`)
+- **uv-native** — every command runs through `uv run`, so your venv, lockfile, and Python version are always in sync
+- **Familiar** — if you've used npm scripts or Hatch scripts, you already know how this works
+
+## Installation
+
+```bash
+# As a dev dependency in your project
+uv add --dev uv-script
+
+# Or run without installing
+uvx uv-script --list
+```
+
+## Quick start
+
+Add a `[tool.uvs.scripts]` section to your `pyproject.toml`:
+
+```toml
+[tool.uvs.scripts]
+test = "pytest tests/ -v"
+lint = "ruff check src/"
+format = "ruff format src/"
+check = ["lint", "test"]
+```
+
+Then run:
+
+```bash
+uvs test       # runs: uv run pytest tests/ -v
+uvs check      # runs lint, then test (stops on first failure)
+uvs --list     # shows all available scripts
+```
+
+## Configuration
+
+Scripts are defined under `[tool.uvs.scripts]` in `pyproject.toml`. Three formats are supported:
+
+### Simple command
+
+A string value runs a single command through `uv run`:
+
+```toml
+[tool.uvs.scripts]
+test = "pytest tests/ -v"
+lint = "ruff check ."
+```
+
+### Composite script
+
+An array of strings runs multiple steps sequentially. Items can reference other script names or be raw commands. Execution stops on the first non-zero exit code.
+
+```toml
+[tool.uvs.scripts]
+lint = "ruff check ."
+test = "pytest tests/"
+check = ["lint", "test"]
+full = ["ruff format --check .", "lint", "test"]
+```
+
+### Table with options
+
+A table gives you control over environment variables and help text:
+
+```toml
+[tool.uvs.scripts.serve]
+cmd = "python -m flask run"
+env = { FLASK_DEBUG = "1", FLASK_APP = "app.py" }
+help = "Start the development server"
+
+[tool.uvs.scripts.deploy]
+cmd = "python scripts/deploy.py"
+env = { ENV = "production" }
+help = "Deploy to production"
+```
+
+| Key    | Type              | Required | Description                              |
+|--------|-------------------|----------|------------------------------------------|
+| `cmd`  | string            | yes      | The command to run                       |
+| `env`  | table of strings  | no       | Environment variables (overlays current) |
+| `help` | string            | no       | Description shown in `--list` output     |
+
+## Usage
+
+```
+uvs [options] <script> [-- extra-args...]
+```
+
+| Flag              | Description                       |
+|-------------------|-----------------------------------|
+| `-l`, `--list`    | List all available scripts        |
+| `-v`, `--verbose` | Print each command before running |
+| `-V`, `--version` | Show version and exit             |
+
+### Passing extra arguments
+
+Use `--` to forward arguments to the underlying command:
+
+```bash
+uvs test -- -k "test_parse" --no-header
+# runs: uv run pytest tests/ -v -k test_parse --no-header
+```
+
+For composite scripts, extra arguments are appended to the last command in the chain.
+
+### Running from subdirectories
+
+`uvs` walks up from your current directory to find the nearest `pyproject.toml`, just like `uv` does. You can run `uvs test` from anywhere inside your project.
+
+## How it works
+
+`uvs` is a thin orchestration layer. Every command is prefixed with `uv run`, which means:
+
+1. Your virtual environment is automatically activated
+2. Dependencies are synced from the lockfile if needed
+3. The correct Python version is used
+
+There is no magic — `uvs test` is equivalent to typing `uv run pytest tests/ -v` yourself.
+
+## Development
+
+This project uses `uvs` to manage its own scripts:
+
+```bash
+git clone <repo-url> && cd uv-script
+uv sync
+uvs test       # run tests
+uvs lint       # run linter
+uvs check      # lint + test
+```
+
+## License
+
+MIT

uv_script-0.1.5/README.md

@@ -0,0 +1,152 @@
+# uv-script
+
+[![PyPI](https://img.shields.io/pypi/v/uv-script)](https://pypi.org/project/uv-script/)
+
+A lightweight, zero-dependency script runner for [uv](https://docs.astral.sh/uv/). Define project scripts in `pyproject.toml` and run them through `uv run`.
+
+```
+$ uvs --list
+  check   lint -> test
+  format  ruff format src/
+  lint    ruff check src/
+  test    pytest tests/ -v
+```
+
+## Why?
+
+uv is a fantastic package manager but has no built-in task runner. If you've been using [Hatch](https://hatch.pypa.io/) just for its scripts, or reaching for [Poe the Poet](https://poethepoet.natn.io/) / [Taskipy](https://github.com/taskipy/taskipy) to fill the gap, `uvs` offers a simpler alternative:
+
+- **Zero runtime dependencies** — stdlib only (`tomllib`, `argparse`, `subprocess`)
+- **uv-native** — every command runs through `uv run`, so your venv, lockfile, and Python version are always in sync
+- **Familiar** — if you've used npm scripts or Hatch scripts, you already know how this works
+
+## Installation
+
+```bash
+# As a dev dependency in your project
+uv add --dev uv-script
+
+# Or run without installing
+uvx uv-script --list
+```
+
+## Quick start
+
+Add a `[tool.uvs.scripts]` section to your `pyproject.toml`:
+
+```toml
+[tool.uvs.scripts]
+test = "pytest tests/ -v"
+lint = "ruff check src/"
+format = "ruff format src/"
+check = ["lint", "test"]
+```
+
+Then run:
+
+```bash
+uvs test       # runs: uv run pytest tests/ -v
+uvs check      # runs lint, then test (stops on first failure)
+uvs --list     # shows all available scripts
+```
+
+## Configuration
+
+Scripts are defined under `[tool.uvs.scripts]` in `pyproject.toml`. Three formats are supported:
+
+### Simple command
+
+A string value runs a single command through `uv run`:
+
+```toml
+[tool.uvs.scripts]
+test = "pytest tests/ -v"
+lint = "ruff check ."
+```
+
+### Composite script
+
+An array of strings runs multiple steps sequentially. Items can reference other script names or be raw commands. Execution stops on the first non-zero exit code.
+
+```toml
+[tool.uvs.scripts]
+lint = "ruff check ."
+test = "pytest tests/"
+check = ["lint", "test"]
+full = ["ruff format --check .", "lint", "test"]
+```
+
+### Table with options
+
+A table gives you control over environment variables and help text:
+
+```toml
+[tool.uvs.scripts.serve]
+cmd = "python -m flask run"
+env = { FLASK_DEBUG = "1", FLASK_APP = "app.py" }
+help = "Start the development server"
+
+[tool.uvs.scripts.deploy]
+cmd = "python scripts/deploy.py"
+env = { ENV = "production" }
+help = "Deploy to production"
+```
+
+| Key    | Type              | Required | Description                              |
+|--------|-------------------|----------|------------------------------------------|
+| `cmd`  | string            | yes      | The command to run                       |
+| `env`  | table of strings  | no       | Environment variables (overlays current) |
+| `help` | string            | no       | Description shown in `--list` output     |
+
+## Usage
+
+```
+uvs [options] <script> [-- extra-args...]
+```
+
+| Flag              | Description                       |
+|-------------------|-----------------------------------|
+| `-l`, `--list`    | List all available scripts        |
+| `-v`, `--verbose` | Print each command before running |
+| `-V`, `--version` | Show version and exit             |
+
+### Passing extra arguments
+
+Use `--` to forward arguments to the underlying command:
+
+```bash
+uvs test -- -k "test_parse" --no-header
+# runs: uv run pytest tests/ -v -k test_parse --no-header
+```
+
+For composite scripts, extra arguments are appended to the last command in the chain.
+
+### Running from subdirectories
+
+`uvs` walks up from your current directory to find the nearest `pyproject.toml`, just like `uv` does. You can run `uvs test` from anywhere inside your project.
+
+## How it works
+
+`uvs` is a thin orchestration layer. Every command is prefixed with `uv run`, which means:
+
+1. Your virtual environment is automatically activated
+2. Dependencies are synced from the lockfile if needed
+3. The correct Python version is used
+
+There is no magic — `uvs test` is equivalent to typing `uv run pytest tests/ -v` yourself.
+
+## Development
+
+This project uses `uvs` to manage its own scripts:
+
+```bash
+git clone <repo-url> && cd uv-script
+uv sync
+uvs test       # run tests
+uvs lint       # run linter
+uvs check      # lint + test
+```
+
+## License
+
+MIT

uv_script-0.1.5/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "uv-script"
+version = "0.1.5"
+description = "A lightweight script runner for uv — define and run project scripts from pyproject.toml"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Felix Simkovic", email = "felixsimkovic@me.com" }
+]
+requires-python = ">=3.12"
+dependencies = []
+
+[project.scripts]
+uvs = "uv_script.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8.7,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.9.0",
+    "ty>=0.0.15",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.uvs.scripts]
+test = "pytest tests/ -v"
+lint = "ruff check src/"
+format = "ruff format src/"
+typecheck = "ty check src/"
+check = ["lint", "typecheck", "test"]

uv_script-0.1.5/src/uv_script/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("uv-script")

uv_script-0.1.5/src/uv_script/__main__.py

@@ -0,0 +1,3 @@
+from uv_script.cli import main
+
+main()

uv_script-0.1.5/src/uv_script/cli.py

@@ -0,0 +1,102 @@
+"""CLI entry point for uvs."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from uv_script import __version__
+from uv_script.config import ConfigError, ScriptDef, load_scripts
+from uv_script.runner import run_script
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="uvs",
+        description="Run scripts defined in [tool.uvs.scripts] via uv run",
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-l",
+        "--list",
+        action="store_true",
+        help="List available scripts",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Print commands before executing",
+    )
+    parser.add_argument(
+        "script",
+        nargs="?",
+        metavar="SCRIPT",
+        help="Name of the script to run",
+    )
+    parser.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        metavar="...",
+        help="Additional arguments passed to the script",
+    )
+
+    parsed = parser.parse_args(argv)
+
+    try:
+        scripts = load_scripts()
+    except ConfigError as e:
+        print(f"uvs: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if parsed.list:
+        _print_list(scripts)
+        return
+
+    if not parsed.script:
+        parser.print_help()
+        sys.exit(1)
+
+    if parsed.script not in scripts:
+        print(f"uvs: unknown script '{parsed.script}'", file=sys.stderr)
+        print(f"Available scripts: {', '.join(sorted(scripts))}", file=sys.stderr)
+        sys.exit(1)
+
+    script = scripts[parsed.script]
+
+    # Strip leading '--' from extra args if present
+    extra_args = parsed.args
+    if extra_args and extra_args[0] == "--":
+        extra_args = extra_args[1:]
+
+    exit_code = run_script(
+        script,
+        all_scripts=scripts,
+        extra_args=extra_args or None,
+        verbose=parsed.verbose,
+    )
+    sys.exit(exit_code)
+
+
+def _print_list(scripts: dict[str, ScriptDef]) -> None:
+    """Print a formatted list of available scripts."""
+    if not scripts:
+        print("No scripts defined.")
+        return
+
+    max_name = max(len(name) for name in scripts)
+
+    for name in sorted(scripts):
+        script = scripts[name]
+        help_text = script.help_text
+        if not help_text:
+            help_text = (
+                " -> ".join(script.commands) if script.is_composite else script.commands[0]
+            )
+
+        print(f"  {name:<{max_name}}  {help_text}")

uv_script-0.1.5/src/uv_script/config.py

@@ -0,0 +1,80 @@
+"""Load and parse script definitions from pyproject.toml."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class ScriptDef:
+    """Normalized representation of a script definition."""
+
+    name: str
+    commands: list[str]
+    env: dict[str, str] = field(default_factory=dict)
+    help_text: str = ""
+    is_composite: bool = False
+
+
+class ConfigError(Exception):
+    """Raised when pyproject.toml is missing or malformed."""
+
+
+def find_pyproject(start: Path | None = None) -> Path:
+    """Walk up from start (default: cwd) to find pyproject.toml."""
+    current = start or Path.cwd()
+    for directory in [current, *current.parents]:
+        candidate = directory / "pyproject.toml"
+        if candidate.is_file():
+            return candidate
+    raise ConfigError("No pyproject.toml found in current directory or any parent")
+
+
+def load_scripts(pyproject_path: Path | None = None) -> dict[str, ScriptDef]:
+    """Load and normalize all script definitions.
+
+    Returns dict mapping script name -> ScriptDef.
+    """
+    path = pyproject_path or find_pyproject()
+
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+
+    scripts_table = data.get("tool", {}).get("uvs", {}).get("scripts", {})
+    if not scripts_table:
+        raise ConfigError(f"No [tool.uvs.scripts] section found in {path}")
+
+    result: dict[str, ScriptDef] = {}
+    for name, value in scripts_table.items():
+        result[name] = _parse_script(name, value)
+    return result
+
+
+def _parse_script(name: str, value: str | list | dict) -> ScriptDef:
+    """Parse a single script value into a ScriptDef."""
+    if isinstance(value, str):
+        return ScriptDef(name=name, commands=[value])
+
+    if isinstance(value, list):
+        if not all(isinstance(v, str) for v in value):
+            raise ConfigError(f"Script '{name}': array items must all be strings")
+        return ScriptDef(name=name, commands=value, is_composite=True)
+
+    if isinstance(value, dict):
+        cmd = value.get("cmd")
+        if not cmd or not isinstance(cmd, str):
+            raise ConfigError(f"Script '{name}': table form requires a 'cmd' string")
+        env = value.get("env", {})
+        if not isinstance(env, dict):
+            raise ConfigError(f"Script '{name}': 'env' must be a table of strings")
+        help_text = value.get("help", "")
+        return ScriptDef(
+            name=name,
+            commands=[cmd],
+            env={str(k): str(v) for k, v in env.items()},
+            help_text=help_text,
+        )
+
+    raise ConfigError(f"Script '{name}': value must be a string, array, or table")

uv_script-0.1.5/src/uv_script/runner.py

@@ -0,0 +1,78 @@
+"""Execute scripts by delegating to uv run."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import sys
+
+from uv_script.config import ConfigError, ScriptDef
+
+
+def run_script(
+    script: ScriptDef,
+    all_scripts: dict[str, ScriptDef],
+    extra_args: list[str] | None = None,
+    verbose: bool = False,
+) -> int:
+    """Execute a script definition. Returns exit code (0 = success)."""
+    steps = resolve_steps(script, all_scripts)
+
+    for i, (cmd_str, env) in enumerate(steps):
+        if extra_args and i == len(steps) - 1:
+            cmd_str = cmd_str + " " + " ".join(shlex.quote(a) for a in extra_args)
+
+        exit_code = _exec_one(cmd_str, env, verbose)
+        if exit_code != 0:
+            return exit_code
+
+    return 0
+
+
+def resolve_steps(
+    script: ScriptDef,
+    all_scripts: dict[str, ScriptDef],
+    _seen: set[str] | None = None,
+) -> list[tuple[str, dict[str, str]]]:
+    """Resolve a script into a flat list of (command, env) pairs.
+
+    Handles references to other scripts and detects cycles.
+    """
+    if _seen is None:
+        _seen = set()
+
+    if script.name in _seen:
+        raise ConfigError(f"Circular reference detected: {script.name}")
+    _seen.add(script.name)
+
+    if not script.is_composite:
+        return [(cmd, script.env) for cmd in script.commands]
+
+    result: list[tuple[str, dict[str, str]]] = []
+    for item in script.commands:
+        if item in all_scripts:
+            referenced = all_scripts[item]
+            result.extend(resolve_steps(referenced, all_scripts, _seen.copy()))
+        else:
+            result.append((item, script.env))
+
+    return result
+
+
+def _exec_one(cmd_str: str, env: dict[str, str], verbose: bool) -> int:
+    """Execute a single command string via uv run."""
+    parts = shlex.split(cmd_str)
+    full_cmd = ["uv", "run"] + parts
+
+    if verbose:
+        env_prefix = " ".join(f"{k}={shlex.quote(v)}" for k, v in env.items())
+        display = f"{env_prefix} {' '.join(full_cmd)}".strip()
+        print(f"$ {display}", file=sys.stderr)
+
+    run_env = None
+    if env:
+        run_env = {**os.environ, **env}
+
+    result = subprocess.run(full_cmd, env=run_env)
+    return result.returncode