API Reference

Reference documentation for the public yeetr API.

yeetr

yeetr: a tiny, typed, signature-driven CLI runner.

Just yeet the function::

def main(thing: int, *, n: float = 0.1) -> None:
    print(thing, n)

if __name__ == "__main__":
    import yeetr
    yeetr.run(main)

Arg dataclass

CLI metadata attached to a positional parameter via Annotated.

Usage::

from typing import Annotated
from yeetr import Arg

def main(path: Annotated[Path, Arg(help="Input file")]) -> None: ...

For variadic positional parameters (*args), min=1 requires at least one value (argparse nargs="+"); the default min=0 accepts zero or more (nargs="*").

Path validators (exists, file_okay, dir_okay, readable, writable) apply only when the parameter's effective type is Path (or list[Path] / variadic *paths: Path). Setting any of these on a non-Path parameter raises YeetrError at parser-build time.

Opt dataclass

CLI metadata attached to a keyword-only parameter via Annotated.

Usage::

from typing import Annotated
from yeetr import Opt

def main(*, workers: Annotated[int, Opt(alias="-w", help="Workers")] = 4) -> None: ...

This is the only Pyright-strict-clean way to attach per-parameter CLI metadata in Python's type system: calls are only permitted inside the metadata slot of Annotated.

envvar provides a fallback value from the environment when the flag is not given on the command line. Precedence: explicit CLI > env var > default. For list[T] opts, the env var is split on os.pathsep. For bool opts, 1/0/true/false/yes/no (case-insensitive) are accepted.

hidden=True hides the option from the Rich help table and usage line; it remains fully functional on the command line.

Path validators (exists, file_okay, dir_okay, readable, writable) apply only when the parameter's effective type is Path (or list[Path]).

YeetrError

Bases: Exception

Raised when the function signature is not convertible into a CLI.

run(func, argv=None, *, prog=None, should_setup_logging=True)

Run func as a CLI.

The function signature defines the CLI: - positional parameters become positional CLI args - keyword-only parameters (after *) become options

If func is async, the coroutine is executed via uvloop.run when the optional uvloop extra is installed, otherwise via asyncio.run.

Pass argv to bypass sys.argv (useful for tests).

When should_setup_logging is True (the default), Rich-based logging is configured after argument parsing and before invoking func. If the parsed namespace contains a log_level string, its value drives the level; otherwise INFO is used. Setup is idempotent: if the root logger already has handlers, no changes are made. Set should_setup_logging=False to take full control of logging yourself.