python-scriptlisted

# PEP 723 Standalone Python Scripts Write single-file Python CLI scripts with inline dependency metadata (PEP 723) executed via `uv run` — no virtualenv, no `pyproject.toml`, no project scaffolding required. ## When to Use - Agent scratch scripts (store in `.agents/tmp/`). - Any situation where a full Python project is overkill. - Quick automation, data processing, or one-off CLI tools. ## Template Base every script on [script.py](references/script.py). Key elements: 1. **Shebang + PEP 723 block** (must be at the top of the file): ```python #!/usr/bin/env -S uv run --quiet --script # /// script # requires-python = ">=3.14" # dependencies = [ # "rich>=15.0.0", # "typer>=0.27.0", # ] # /// ``` 1. **CLI framework**: Use `Typer` with `Rich` for argument parsing and formatted output. 1. **Dual consoles**: `Console()` for stdout results, `Console(stderr=True)` for logs/errors. 1. **Typed arguments**: Use `Annotated[..., typer.Argument/Option(...)]` with help text. 1. **Error handling**: Catch exceptions at the CLI boundary with `err.print_exception(show_locals=False)` and exit via `raise typer.Exit(code=1) from None`; never render locals because they can contain secrets. ## Execution ```bash # Direct execution (after chmod +x) ./script.py input.txt # Or via uv explicitly uv run script.py input.txt --verbose ``` `uv` resolves and caches the declared dependencies automatically — no manual install step. For a durable script, commit its