slick-cli 0.1.0__py3-none-any.whl

slick_cli/__init__.py

@@ -0,0 +1,40 @@
+"""slick_cli: ergonomic, type-hint driven command-line apps on the standard library.
+
+Quick example::
+
+    from slick_cli import App, echo
+
+    app = App("hello")
+
+    @app.command
+    def greet(name: str, count: int = 1, shout: bool = False) -> None:
+        '''Greet someone.'''
+        for _ in range(count):
+            echo(name.upper() if shout else name)
+
+    if __name__ == "__main__":
+        app()
+"""
+
+from .app import App, Command, run
+from .errors import CliError, abort
+from .params import Arg
+from .style import confirm, echo, secho, should_color, style, unstyle
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "App",
+    "Arg",
+    "CliError",
+    "Command",
+    "abort",
+    "confirm",
+    "echo",
+    "run",
+    "secho",
+    "should_color",
+    "style",
+    "unstyle",
+    "__version__",
+]

slick_cli/app.py

@@ -0,0 +1,255 @@
+"""Applications, commands and dispatch."""
+
+from __future__ import annotations
+
+import argparse
+import inspect
+import sys
+from collections.abc import Sequence
+from typing import Any, Callable, NoReturn, TypeVar, overload
+
+from .docstrings import parse_docstring
+from .errors import CliError
+from .params import Param, params_from_function
+from .style import echo, style
+
+__all__ = ["App", "Command", "run"]
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_TARGET = "_slick_target"
+
+
+class _HelpFormatter(argparse.RawDescriptionHelpFormatter):
+    """Keeps docstring line breaks and gives the help column a bit more room."""
+
+    def __init__(self, prog: str) -> None:
+        super().__init__(prog, max_help_position=30)
+
+
+class Command:
+    """A function exposed as a CLI command.
+
+    Normally created through :meth:`App.command`; the decorated function itself
+    is returned unchanged, so it stays directly callable and testable.
+    """
+
+    def __init__(
+        self,
+        func: Callable[..., Any],
+        name: str | None = None,
+        *,
+        help: str | None = None,
+        aliases: Sequence[str] = (),
+    ) -> None:
+        doc = parse_docstring(func.__doc__)
+        self.func = func
+        self.name = name or func.__name__.strip("_").replace("_", "-")
+        self.help = help or doc.summary
+        self.description = "\n\n".join(p for p in (self.help, doc.description) if p)
+        self.aliases = tuple(aliases)
+        self.params: list[Param] = params_from_function(func, doc.params)
+
+    def configure(self, parser: argparse.ArgumentParser) -> None:
+        """Add this command's arguments to ``parser`` and mark it as the target."""
+        for param in self.params:
+            param.add_to(parser)
+        parser.set_defaults(**{_TARGET: (self, parser)})
+
+    def invoke(self, namespace: argparse.Namespace) -> Any:
+        """Call the function with values taken from a parsed ``namespace``."""
+        args: list[Any] = []
+        kwargs: dict[str, Any] = {}
+        for param in self.params:
+            value = param.resolve(namespace)
+            if param.kind == "varargs":
+                args.extend(value)
+            elif param.call_kind is inspect.Parameter.KEYWORD_ONLY:
+                kwargs[param.name] = value
+            else:
+                args.append(value)
+        return self.func(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"Command({self.name!r})"
+
+
+class App:
+    """A command-line application: a named collection of commands and sub-apps.
+
+    Example::
+
+        app = App("tool", version="1.0")
+
+        @app.command
+        def hello(name: str, count: int = 1) -> None:
+            '''Say hello.'''
+            for _ in range(count):
+                echo(f"Hello, {name}!")
+
+        if __name__ == "__main__":
+            app()
+    """
+
+    def __init__(self, name: str | None = None, help: str | None = None, *, version: str | None = None) -> None:
+        self.name = name
+        self.help = help
+        self.version = version
+        self.commands: dict[str, Command | App] = {}
+
+    # -- registration -----------------------------------------------------------
+
+    @overload
+    def command(self, func: F, /) -> F: ...
+
+    @overload
+    def command(
+        self, *, name: str | None = None, help: str | None = None, aliases: Sequence[str] = ()
+    ) -> Callable[[F], F]: ...
+
+    def command(
+        self,
+        func: F | None = None,
+        /,
+        *,
+        name: str | None = None,
+        help: str | None = None,
+        aliases: Sequence[str] = (),
+    ) -> F | Callable[[F], F]:
+        """Register a function as a command. Usable as ``@app.command`` or ``@app.command(...)``.
+
+        The command name defaults to the function name with ``_`` replaced by ``-``.
+        The function is returned unchanged.
+        """
+
+        def register(f: F) -> F:
+            cmd = Command(f, name, help=help, aliases=aliases)
+            self._add(cmd.name, cmd)
+            return f
+
+        return register(func) if func is not None else register
+
+    def group(self, name: str, help: str | None = None) -> App:
+        """Create, register and return a nested :class:`App` for subcommands."""
+        sub = App(name, help)
+        self._add(name, sub)
+        return sub
+
+    def add_app(self, app: App, name: str | None = None) -> App:
+        """Mount an existing :class:`App` as a subcommand group and return it."""
+        mount = name or app.name
+        if not mount:
+            raise ValueError("a mounted App needs a name")
+        self._add(mount, app)
+        return app
+
+    def _taken_names(self) -> set[str]:
+        names = set(self.commands)
+        for entry in self.commands.values():
+            if isinstance(entry, Command):
+                names.update(entry.aliases)
+        return names
+
+    def _add(self, name: str, entry: Command | App) -> None:
+        aliases = entry.aliases if isinstance(entry, Command) else ()
+        taken = self._taken_names()
+        for candidate in (name, *aliases):
+            if candidate in taken:
+                raise ValueError(f"command name {candidate!r} is already registered")
+        self.commands[name] = entry
+
+    # -- parsing and dispatch ---------------------------------------------------
+
+    def build_parser(self, prog: str | None = None) -> argparse.ArgumentParser:
+        """Build the full :class:`argparse.ArgumentParser` tree for this app."""
+        parser = argparse.ArgumentParser(prog=prog or self.name, description=self.help, formatter_class=_HelpFormatter)
+        self._configure(parser)
+        return parser
+
+    def _configure(self, parser: argparse.ArgumentParser) -> None:
+        if self.version:
+            parser.add_argument("--version", action="version", version=f"%(prog)s {self.version}")
+        parser.set_defaults(**{_TARGET: (self, parser)})
+        if not self.commands:
+            return
+        subparsers = parser.add_subparsers(title="commands", metavar="COMMAND")
+        for name, entry in self.commands.items():
+            if isinstance(entry, App):
+                sub = subparsers.add_parser(
+                    name, help=entry.help, description=entry.help, formatter_class=_HelpFormatter
+                )
+                entry._configure(sub)
+            else:
+                sub = subparsers.add_parser(
+                    name,
+                    aliases=list(entry.aliases),
+                    help=entry.help,
+                    description=entry.description,
+                    formatter_class=_HelpFormatter,
+                )
+                entry.configure(sub)
+
+    def run(self, argv: Sequence[str] | None = None) -> int:
+        """Parse ``argv`` (default ``sys.argv[1:]``), run the command, return an exit code.
+
+        Never raises ``SystemExit``; see :func:`run` for exit-code rules.
+        """
+        return _dispatch(self.build_parser(), argv)
+
+    def main(self, argv: Sequence[str] | None = None) -> NoReturn:
+        """Like :meth:`run`, then exit the process with the resulting code."""
+        sys.exit(self.run(argv))
+
+    __call__ = main
+
+
+def _exit_code(result: Any) -> int:
+    if result is None:
+        return 0
+    if isinstance(result, bool):
+        return 0 if result else 1
+    if isinstance(result, int):
+        return result
+    echo(result)
+    return 0
+
+
+def _dispatch(parser: argparse.ArgumentParser, argv: Sequence[str] | None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    try:
+        namespace = parser.parse_args(args)
+        target, target_parser = getattr(namespace, _TARGET)
+        if isinstance(target, App):  # a group was invoked without a subcommand
+            target_parser.print_help()
+            return 0
+        return _exit_code(target.invoke(namespace))
+    except SystemExit as exc:  # argparse --help / --version / usage errors
+        code = exc.code
+        return code if isinstance(code, int) else (0 if code is None else 1)
+    except CliError as exc:
+        echo(style("Error: ", fg="red", bold=True) + exc.message, err=True)
+        return exc.exit_code
+    except KeyboardInterrupt:
+        echo("\n" + style("Aborted!", fg="red"), err=True)
+        return 130
+
+
+def run(
+    func: Callable[..., Any],
+    argv: Sequence[str] | None = None,
+    *,
+    prog: str | None = None,
+    version: str | None = None,
+) -> int:
+    """Run a single function as a whole CLI (no subcommands) and return the exit code.
+
+    Exit codes: a command returning ``None`` exits 0; an ``int`` is used as-is;
+    ``True``/``False`` map to 0/1; any other value is printed and exits 0.
+    :class:`~slick_cli.CliError` exits with its code, usage errors with 2.
+    """
+    command = Command(func)
+    parser = argparse.ArgumentParser(prog=prog, description=command.description, formatter_class=_HelpFormatter)
+    if version:
+        parser.add_argument("--version", action="version", version=f"%(prog)s {version}")
+    command.configure(parser)
+    return _dispatch(parser, argv)

slick_cli/docstrings.py

@@ -0,0 +1,81 @@
+"""Minimal Google-style docstring parsing for command and parameter help."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from dataclasses import dataclass, field
+
+__all__ = ["DocInfo", "parse_docstring"]
+
+_PARAM_SECTIONS = {"args", "arguments", "parameters", "params"}
+_DROPPED_SECTIONS = {"returns", "return", "raises", "yields", "yield"}
+_SECTION_RE = re.compile(r"^([A-Za-z][A-Za-z ]*):\s*$")
+_PARAM_RE = re.compile(r"^\*{0,2}(\w+)\s*(?:\([^)]*\))?\s*:\s*(.*)$")
+
+
+@dataclass
+class DocInfo:
+    """The parts of a docstring that matter for CLI help."""
+
+    summary: str = ""
+    description: str = ""
+    params: dict[str, str] = field(default_factory=dict)
+
+
+def _indent(line: str) -> int:
+    return len(line) - len(line.lstrip())
+
+
+def parse_docstring(doc: str | None) -> DocInfo:
+    """Split a docstring into summary, description and per-parameter help.
+
+    The summary is the first paragraph (joined onto one line). Entries in an
+    ``Args:``/``Arguments:``/``Parameters:`` section become parameter help;
+    ``Returns:``/``Raises:``/``Yields:`` sections are dropped; everything else
+    is kept verbatim as the description.
+    """
+    text = inspect.cleandoc(doc or "")
+    if not text:
+        return DocInfo()
+
+    body: list[str] = []
+    params: dict[str, str] = {}
+    section: str | None = None  # "params", "drop", or None for body text
+    entry_indent: int | None = None
+    current: str | None = None
+
+    for line in text.splitlines():
+        header = _SECTION_RE.match(line)
+        if header and _indent(line) == 0:
+            name = header.group(1).strip().lower()
+            if name in _PARAM_SECTIONS:
+                section, entry_indent, current = "params", None, None
+                continue
+            if name in _DROPPED_SECTIONS:
+                section = "drop"
+                continue
+        if section is not None:
+            if not line.strip():
+                continue
+            if _indent(line) == 0:  # dedent ends the section
+                section = None
+            elif section == "drop":
+                continue
+            else:
+                indent = _indent(line)
+                if entry_indent is None:
+                    entry_indent = indent
+                match = _PARAM_RE.match(line.strip())
+                if indent <= entry_indent and match:
+                    current = match.group(1)
+                    params[current] = match.group(2).strip()
+                elif current is not None:
+                    params[current] = (params[current] + " " + line.strip()).strip()
+                continue
+        body.append(line)
+
+    paragraphs = "\n".join(body).strip().split("\n\n", 1)
+    summary = " ".join(part.strip() for part in paragraphs[0].splitlines())
+    description = paragraphs[1].strip() if len(paragraphs) > 1 else ""
+    return DocInfo(summary=summary, description=description, params=params)

slick_cli/errors.py

@@ -0,0 +1,29 @@
+"""Exceptions used to stop a command cleanly with a message and exit code."""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+__all__ = ["CliError", "abort"]
+
+
+class CliError(Exception):
+    """An expected, user-facing failure.
+
+    Raising this from a command prints ``Error: <message>`` to stderr (in red when
+    the terminal supports it) and exits with :attr:`exit_code` instead of showing
+    a traceback.
+    """
+
+    def __init__(self, message: str, exit_code: int = 1) -> None:
+        super().__init__(message)
+        self.message = message
+        self.exit_code = exit_code
+
+
+def abort(message: str, exit_code: int = 1) -> NoReturn:
+    """Stop the current command with ``message`` and ``exit_code``.
+
+    Shorthand for ``raise CliError(message, exit_code)``.
+    """
+    raise CliError(message, exit_code)

slick_cli/params.py

@@ -0,0 +1,295 @@
+"""Turn a function signature into argparse arguments, driven by type hints.
+
+Mapping rules (see the README for the user-facing table):
+
+* parameter without a default          -> positional argument
+* parameter with a default             -> ``--option``
+* keyword-only parameter, no default   -> required ``--option``
+* ``bool``                             -> ``--flag/--no-flag``
+* ``list[T]`` / ``tuple[T, ...]``      -> positional taking 1+ values, or a
+  repeatable option (``--tag a --tag b``)
+* ``*args: T``                         -> positional taking 0+ values
+* ``Literal[...]`` / ``Enum``          -> choices
+* ``T | None``                         -> same as ``T``
+* any other callable type (``int``, ``float``, ``Path``, ...) converts the string
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections.abc
+import enum
+import inspect
+import os
+import types
+import typing
+from dataclasses import dataclass
+from typing import Annotated, Any, Callable, Literal, Union, get_args, get_origin
+
+from .errors import CliError
+
+__all__ = ["Arg", "Param", "params_from_function"]
+
+_EMPTY = inspect.Parameter.empty
+
+
+@dataclass(frozen=True)
+class Arg:
+    """Extra CLI metadata for one parameter, attached with ``typing.Annotated``.
+
+    Example::
+
+        def greet(name: str, count: Annotated[int, Arg(short="-c", help="Repeat")] = 1): ...
+
+    Attributes:
+        help: Help text (overrides the docstring entry).
+        short: A short flag such as ``"-c"`` (options and flags only).
+        name: Long option name to use instead of the parameter name.
+        metavar: Placeholder shown in usage, e.g. ``"FILE"``.
+        env: Environment variable read when the option is not given.
+    """
+
+    help: str | None = None
+    short: str | None = None
+    name: str | None = None
+    metavar: str | None = None
+    env: str | None = None
+
+
+_TRUE = {"1", "true", "yes", "y", "on"}
+_FALSE = {"0", "false", "no", "n", "off", ""}
+
+
+def parse_bool(value: str) -> bool:
+    """Parse common spellings of true/false (``yes``, ``0``, ``on``...)."""
+    lowered = value.strip().lower()
+    if lowered in _TRUE:
+        return True
+    if lowered in _FALSE:
+        return False
+    raise argparse.ArgumentTypeError(f"invalid boolean value: {value!r}")
+
+
+parse_bool.__name__ = "bool"
+
+
+def _unwrap_annotated(hint: Any) -> tuple[Any, Arg | None]:
+    if get_origin(hint) is Annotated:
+        base, *extras = get_args(hint)
+        arg = next((e for e in extras if isinstance(e, Arg)), None)
+        return base, arg
+    return hint, None
+
+
+def _unwrap_optional(hint: Any) -> Any:
+    if get_origin(hint) in (Union, types.UnionType):
+        members = [a for a in get_args(hint) if a is not type(None)]
+        if len(members) == 1:
+            return members[0]
+    return hint
+
+
+def _sequence_item(hint: Any) -> Any | None:
+    """Return the item type if ``hint`` is a list-like type, else ``None``."""
+    origin = get_origin(hint)
+    if hint in (list, tuple) or origin in (list, collections.abc.Sequence):
+        args = get_args(hint)
+        return args[0] if args else str
+    if origin is tuple:
+        args = get_args(hint)
+        if len(args) == 2 and args[1] is Ellipsis:
+            return args[0]
+    return None
+
+
+def _choice_converter(values: list[Any], labels: list[str]) -> Callable[[str], Any]:
+    def convert(raw: str) -> Any:
+        for value, label in zip(values, labels):
+            if raw == label or raw.lower() == label.lower():
+                return value
+        raise argparse.ArgumentTypeError(f"invalid choice: {raw!r} (choose from {', '.join(labels)})")
+
+    convert.__name__ = "choice"
+    return convert
+
+
+def _converter(hint: Any) -> tuple[Callable[[str], Any], str | None]:
+    """Return ``(convert, choices_metavar)`` for a scalar type hint."""
+    hint = _unwrap_optional(hint)
+    if hint in (_EMPTY, Any, str):
+        return str, None
+    if hint is bool:
+        return parse_bool, None
+    if get_origin(hint) is Literal:
+        values = list(get_args(hint))
+        labels = [str(v) for v in values]
+        return _choice_converter(values, labels), "{" + ",".join(labels) + "}"
+    if isinstance(hint, type) and issubclass(hint, enum.Enum):
+        members = list(hint)
+        labels = [str(m.value) if isinstance(m.value, (str, int)) else m.name.lower() for m in members]
+        convert = _choice_converter(members, labels)
+
+        def convert_enum(raw: str) -> Any:
+            # Accept member names too, e.g. RED for Color.RED = "red".
+            by_name = {m.name.lower(): m for m in members}
+            if raw.lower() in by_name and raw not in labels:
+                return by_name[raw.lower()]
+            return convert(raw)
+
+        convert_enum.__name__ = "choice"
+        return convert_enum, "{" + ",".join(labels) + "}"
+    if callable(hint):
+        return hint, None
+    raise TypeError(f"unsupported parameter type: {hint!r}")
+
+
+def _format_default(value: Any) -> str:
+    if isinstance(value, enum.Enum):
+        return str(value.value)
+    if isinstance(value, (list, tuple)):
+        return " ".join(str(v) for v in value) or "[]"
+    return str(value)
+
+
+@dataclass
+class Param:
+    """One function parameter and how it maps to the command line."""
+
+    name: str
+    kind: str  # "positional" | "option" | "flag" | "varargs"
+    convert: Callable[[str], Any]
+    default: Any = _EMPTY
+    multiple: bool = False
+    help: str | None = None
+    arg: Arg = Arg()
+    choices_metavar: str | None = None
+    call_kind: inspect._ParameterKind = inspect.Parameter.POSITIONAL_OR_KEYWORD
+
+    @property
+    def required(self) -> bool:
+        """True if the user must supply a value (no default, not a flag)."""
+        return self.default is _EMPTY and self.kind not in ("flag", "varargs")
+
+    @property
+    def flags(self) -> list[str]:
+        """Option strings, e.g. ``["-c", "--count"]`` (empty for positionals)."""
+        if self.kind in ("positional", "varargs"):
+            return []
+        long_name = (self.arg.name or self.name).lstrip("-").replace("_", "-")
+        return ([self.arg.short] if self.arg.short else []) + [f"--{long_name}"]
+
+    def _help_text(self) -> str:
+        parts = [self.help or ""]
+        if self.kind == "flag":
+            if self.default not in (_EMPTY, False):
+                parts.append(f"(default: {_format_default(self.default)})")
+        elif self.default not in (_EMPTY, None):
+            parts.append(f"(default: {_format_default(self.default)})")
+        if self.arg.env:
+            parts.append(f"[env: {self.arg.env}]")
+        return " ".join(p for p in parts if p).replace("%", "%%")
+
+    def add_to(self, parser: argparse.ArgumentParser) -> None:
+        """Register this parameter on ``parser``."""
+        kwargs: dict[str, Any] = {"help": self._help_text() or None}
+        metavar = self.arg.metavar or self.choices_metavar
+        if self.kind in ("positional", "varargs"):
+            kwargs["type"] = self.convert
+            kwargs["metavar"] = metavar or self.name.upper()
+            if self.kind == "varargs":
+                kwargs["nargs"] = "*"
+            elif self.multiple:
+                kwargs["nargs"] = "+"
+            parser.add_argument(self.name, **kwargs)
+            return
+
+        # Options are absent from the namespace unless given, so defaults and
+        # environment variables can be resolved after parsing (see `resolve`).
+        kwargs["dest"] = self.name
+        kwargs["default"] = argparse.SUPPRESS
+        if self.kind == "flag":
+            kwargs["action"] = argparse.BooleanOptionalAction
+        else:
+            kwargs["type"] = self.convert
+            kwargs["metavar"] = metavar or self.name.upper()
+            if self.multiple:
+                kwargs["action"] = "append"
+            if self.required and not self.arg.env:
+                kwargs["required"] = True
+        parser.add_argument(*self.flags, **kwargs)
+
+    def resolve(self, namespace: argparse.Namespace) -> Any:
+        """Return the final Python value for this parameter after parsing."""
+        if hasattr(namespace, self.name):
+            return getattr(namespace, self.name)
+        if self.arg.env and self.arg.env in os.environ:
+            raw = os.environ[self.arg.env]
+            try:
+                if self.kind == "flag":
+                    return parse_bool(raw)
+                if self.multiple:
+                    return [self.convert(item.strip()) for item in raw.split(",") if item.strip()]
+                return self.convert(raw)
+            except (ValueError, TypeError, argparse.ArgumentTypeError) as exc:
+                raise CliError(f"invalid value for {self.arg.env}: {exc}", exit_code=2) from None
+        if self.kind == "flag":
+            return False if self.default is _EMPTY else self.default
+        if self.kind == "varargs":
+            return []
+        if self.required:
+            flag = self.flags[-1] if self.flags else self.name
+            hint = f" (or set {self.arg.env})" if self.arg.env else ""
+            raise CliError(f"missing required option {flag}{hint}", exit_code=2)
+        return self.default
+
+
+def params_from_function(func: Callable[..., Any], doc_params: dict[str, str] | None = None) -> list[Param]:
+    """Build :class:`Param` objects for every parameter of ``func``.
+
+    Raises:
+        TypeError: For ``**kwargs`` or an annotation that cannot convert strings.
+    """
+    doc_params = doc_params or {}
+    try:
+        hints = typing.get_type_hints(func, include_extras=True)
+    except Exception:  # unresolved forward references: fall back to raw annotations
+        hints = getattr(func, "__annotations__", {})
+
+    result: list[Param] = []
+    for p in inspect.signature(func).parameters.values():
+        if p.kind is p.VAR_KEYWORD:
+            raise TypeError(f"{func.__name__}: **{p.name} is not supported by slick_cli commands")
+        hint, arg = _unwrap_annotated(hints.get(p.name, _EMPTY))
+        arg = arg or Arg()
+        hint = _unwrap_optional(hint)
+        help_text = arg.help or doc_params.get(p.name)
+
+        item = _sequence_item(hint)
+        multiple = item is not None and p.kind is not p.VAR_POSITIONAL
+        scalar = item if multiple else hint
+        if p.kind is p.VAR_POSITIONAL:
+            kind = "varargs"
+        elif scalar is bool and not multiple:
+            kind = "flag"
+        elif p.default is _EMPTY and p.kind is not p.KEYWORD_ONLY:
+            kind = "positional"
+        else:
+            kind = "option"
+        if kind in ("positional", "varargs") and arg.short:
+            raise TypeError(f"{func.__name__}: positional parameter {p.name!r} cannot have a short flag")
+
+        convert, choices_metavar = _converter(scalar)
+        result.append(
+            Param(
+                name=p.name,
+                kind=kind,
+                convert=convert,
+                default=p.default,
+                multiple=multiple,
+                help=help_text,
+                arg=arg,
+                choices_metavar=choices_metavar,
+                call_kind=p.kind,
+            )
+        )
+    return result

slick_cli/style.py

@@ -0,0 +1,166 @@
+"""ANSI styling and terminal output helpers.
+
+Color is emitted only when it will be understood: output streams that are not a
+TTY get plain text, ``NO_COLOR`` (https://no-color.org) disables color, and
+``FORCE_COLOR`` enables it even when piping.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from typing import IO, Any
+
+__all__ = ["COLORS", "style", "unstyle", "should_color", "echo", "secho", "confirm"]
+
+#: Supported color names mapped to their ANSI foreground codes.
+COLORS: dict[str, int] = {
+    "black": 30,
+    "red": 31,
+    "green": 32,
+    "yellow": 33,
+    "blue": 34,
+    "magenta": 35,
+    "cyan": 36,
+    "white": 37,
+    "bright_black": 90,
+    "bright_red": 91,
+    "bright_green": 92,
+    "bright_yellow": 93,
+    "bright_blue": 94,
+    "bright_magenta": 95,
+    "bright_cyan": 96,
+    "bright_white": 97,
+}
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+_RESET = "\x1b[0m"
+
+
+def _color_code(name: str, *, background: bool) -> int:
+    try:
+        code = COLORS[name]
+    except KeyError:
+        known = ", ".join(COLORS)
+        raise ValueError(f"unknown color {name!r}; expected one of: {known}") from None
+    return code + 10 if background else code
+
+
+def style(
+    text: object,
+    fg: str | None = None,
+    bg: str | None = None,
+    *,
+    bold: bool = False,
+    dim: bool = False,
+    italic: bool = False,
+    underline: bool = False,
+) -> str:
+    """Wrap ``text`` in ANSI escape codes.
+
+    Styling is always applied here; whether it reaches the terminal is decided by
+    :func:`echo`, which strips codes for streams that should not get color.
+
+    Raises:
+        ValueError: If ``fg`` or ``bg`` is not a name in :data:`COLORS`.
+    """
+    codes: list[int] = []
+    if bold:
+        codes.append(1)
+    if dim:
+        codes.append(2)
+    if italic:
+        codes.append(3)
+    if underline:
+        codes.append(4)
+    if fg is not None:
+        codes.append(_color_code(fg, background=False))
+    if bg is not None:
+        codes.append(_color_code(bg, background=True))
+    if not codes:
+        return str(text)
+    prefix = "\x1b[" + ";".join(str(c) for c in codes) + "m"
+    return f"{prefix}{text}{_RESET}"
+
+
+def unstyle(text: str) -> str:
+    """Remove all ANSI styling codes from ``text``."""
+    return _ANSI_RE.sub("", text)
+
+
+def should_color(stream: IO[str]) -> bool:
+    """Decide whether ``stream`` should receive ANSI color codes.
+
+    ``NO_COLOR`` wins over ``FORCE_COLOR``; otherwise color is used for TTYs only.
+    """
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    isatty = getattr(stream, "isatty", None)
+    try:
+        return bool(isatty and isatty())
+    except ValueError:  # closed stream
+        return False
+
+
+def echo(message: object = "", *, err: bool = False, nl: bool = True, color: bool | None = None) -> None:
+    """Print ``message`` to stdout (or stderr with ``err=True``).
+
+    Args:
+        message: Anything; converted with ``str()``.
+        err: Write to stderr instead of stdout.
+        nl: Append a newline.
+        color: Force styling on (True) or off (False); ``None`` auto-detects
+            with :func:`should_color`.
+    """
+    stream = sys.stderr if err else sys.stdout
+    text = str(message)
+    use_color = should_color(stream) if color is None else color
+    if not use_color:
+        text = unstyle(text)
+    stream.write(text + ("\n" if nl else ""))
+    stream.flush()
+
+
+def secho(
+    message: object = "",
+    *,
+    err: bool = False,
+    nl: bool = True,
+    color: bool | None = None,
+    **styles: Any,
+) -> None:
+    """Style ``message`` with :func:`style` and print it with :func:`echo`.
+
+    Example: ``secho("done", fg="green", bold=True)``.
+    """
+    echo(style(message, **styles), err=err, nl=nl, color=color)
+
+
+_YES = {"y", "yes", "true", "1"}
+_NO = {"n", "no", "false", "0"}
+
+
+def confirm(prompt: str, default: bool = False) -> bool:
+    """Ask a yes/no question on stdin and return the answer.
+
+    An empty answer (or end of input) returns ``default``. Invalid answers
+    re-ask the question.
+    """
+    suffix = " [Y/n]: " if default else " [y/N]: "
+    while True:
+        echo(prompt + suffix, nl=False)
+        try:
+            answer = input().strip().lower()
+        except EOFError:
+            echo()
+            return default
+        if not answer:
+            return default
+        if answer in _YES:
+            return True
+        if answer in _NO:
+            return False
+        echo("Please answer y or n.", err=True)

slick_cli/testing.py

@@ -0,0 +1,51 @@
+"""Helpers for testing CLIs built with slick_cli, without spawning processes."""
+
+from __future__ import annotations
+
+import io
+import os
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from contextlib import redirect_stderr, redirect_stdout
+from dataclasses import dataclass
+from typing import Any
+from unittest import mock
+
+from .app import App, run
+
+__all__ = ["Result", "invoke"]
+
+
+@dataclass(frozen=True)
+class Result:
+    """Captured outcome of :func:`invoke`."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+
+
+def invoke(
+    target: App | Callable[..., Any],
+    args: Sequence[str] = (),
+    *,
+    env: Mapping[str, str] | None = None,
+    input: str | None = None,
+) -> Result:
+    """Run an :class:`App` (or a plain function, via :func:`slick_cli.run`) in-process.
+
+    Args:
+        target: The app or function to run.
+        args: Command-line arguments, excluding the program name.
+        env: Extra environment variables set for the duration of the call.
+        input: Text fed to stdin (for :func:`slick_cli.confirm`).
+    """
+    out, err = io.StringIO(), io.StringIO()
+    stdin = io.StringIO(input) if input is not None else sys.stdin
+    with mock.patch.dict(os.environ, dict(env or {})), mock.patch.object(sys, "stdin", stdin):
+        with redirect_stdout(out), redirect_stderr(err):
+            if isinstance(target, App):
+                code = target.run(list(args))
+            else:
+                code = run(target, list(args), prog=getattr(target, "__name__", None))
+    return Result(code, out.getvalue(), err.getvalue())

slick_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: slick-cli
+Version: 0.1.0
+Summary: Slick, type-hint driven command-line apps built on the Python standard library.
+Author: nehz
+License-Expression: MIT
+Keywords: cli,command-line,argparse,decorator,type-hints,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# slick-cli
+
+**Write a function, get a command-line app.** `slick-cli` turns ordinary, type-hinted
+Python functions into polished CLIs: arguments, options, flags, choices, subcommands,
+help text and colored output, with **zero dependencies** (it is a thin, friendly layer
+over `argparse`).
+
+```python
+from slick_cli import App, echo
+
+app = App("greeter", "Friendly greetings.", version="1.0")
+
+@app.command
+def hello(name: str, count: int = 1, shout: bool = False) -> None:
+    """Greet someone.
+
+    Args:
+        name: Who to greet.
+        count: How many times.
+        shout: Use UPPERCASE.
+    """
+    for _ in range(count):
+        echo(name.upper() if shout else f"Hello, {name}!")
+
+if __name__ == "__main__":
+    app()
+```
+
+```console
+$ python greeter.py hello Ada --count 2
+Hello, Ada!
+Hello, Ada!
+$ python greeter.py hello --help
+usage: greeter hello [-h] [--count COUNT] [--shout | --no-shout] NAME
+...
+```
+
+## Features
+
+- **Decorator-based commands**: `@app.command` registers a function and returns it unchanged, so it stays directly callable and testable.
+- **Type hints drive parsing**: `int`, `float`, `Path`, `bool` flags, `list[T]`, `*args`, `Literal[...]` and `Enum` choices, and `T | None`.
+- **Help from docstrings**: the summary, description and Google-style `Args:` entries become `--help` output, with defaults and env vars listed.
+- **Subcommand groups**: nest apps with `app.group(...)` or mount an existing one with `app.add_app(...)`; command aliases are supported.
+- **Per-parameter tweaks** via `Annotated[T, Arg(...)]`: short flags, custom names, metavars and environment-variable fallbacks.
+- **Colored output that behaves**: `style`/`secho` emit ANSI color only to TTYs, and respect `NO_COLOR` and `FORCE_COLOR`.
+- **Clean errors and exit codes**: `abort("msg")` prints `Error: msg` and exits non-zero, with no traceback. Return values become exit codes.
+- **In-process testing**: `slick_cli.testing.invoke` captures exit code, stdout and stderr.
+- Standard library only, Python 3.10+, fully typed (`py.typed`).
+
+## Install
+
+```console
+pip install slick-cli
+```
+
+Or from a checkout: `pip install .`
+
+## Quickstart
+
+```python
+# todo.py
+from pathlib import Path
+from typing import Annotated, Literal
+
+from slick_cli import App, Arg, abort, secho
+
+app = App("todo", "A tiny todo manager.")
+FILE = Path("todo.txt")
+
+@app.command
+def add(text: list[str], *, priority: Literal["low", "high"] = "low") -> None:
+    """Add an item."""
+    with FILE.open("a") as f:
+        f.write(f"[{priority}] {' '.join(text)}\n")
+    secho("added", fg="green")
+
+@app.command(name="list", aliases=["ls"])
+def list_items(*, high_only: Annotated[bool, Arg(short="-H")] = False) -> None:
+    """Show items."""
+    if not FILE.exists():
+        abort("nothing to do yet")
+    for line in FILE.read_text().splitlines():
+        if not high_only or line.startswith("[high]"):
+            print(line)
+
+if __name__ == "__main__":
+    app()
+```
+
+```console
+$ python todo.py add buy milk --priority high
+added
+$ python todo.py ls -H
+[high] buy milk
+```
+
+A runnable tour lives in [`examples/demo.py`](examples/demo.py):
+
+```console
+python3 examples/demo.py --help
+python3 examples/demo.py hello Ada --count 2 --shout --color magenta
+python3 examples/demo.py sum 1.5 2 3.25 -p 1
+python3 examples/demo.py files ls --path . --ext .py
+DEMO_TOKEN=secret python3 examples/demo.py deploy prod -y
+```
+
+## How parameters map to the command line
+
+| Python parameter                       | Command line                                   |
+|----------------------------------------|------------------------------------------------|
+| `name: str` (no default)               | positional `NAME`                              |
+| `count: int = 1` (has a default)       | option `--count COUNT`                         |
+| `*, user: str` (keyword-only, no default) | required option `--user USER`               |
+| `verbose: bool = False`                | flag `--verbose / --no-verbose`                |
+| `files: list[Path]` (no default)       | positional taking one or more values           |
+| `*, tag: list[str] \| None = None`     | repeatable option `--tag a --tag b`            |
+| `*rest: int`                           | positional taking zero or more values          |
+| `mode: Literal["fast", "slow"]`        | choices `{fast,slow}`                          |
+| `color: Color` (an `Enum`)             | choices from member values (names also accepted, case-insensitive) |
+| `out: Path \| None = None`             | same as `Path`; `None` when omitted            |
+| `when: SomeType`                       | `SomeType(string)` is used as the converter    |
+
+Underscores in names become dashes (`dry_run` becomes `--dry-run`). Unannotated
+parameters are strings. A `bool` with no default is a flag defaulting to `False`.
+`**kwargs` is rejected with `TypeError`.
+
+## API overview
+
+Everything below is importable from `slick_cli` unless noted.
+
+### `App(name=None, help=None, *, version=None)`
+
+A collection of commands and nested groups.
+
+- `@app.command` / `@app.command(name=None, *, help=None, aliases=())`: register a function. The name defaults to the function name with `_` replaced by `-` (leading/trailing underscores stripped). `help` defaults to the docstring summary. Duplicate names or aliases raise `ValueError`.
+- `app.group(name, help=None) -> App`: create and mount a nested app for subcommands.
+- `app.add_app(other, name=None) -> App`: mount an existing app (uses `other.name` if `name` is omitted).
+- `app.run(argv=None) -> int`: parse `argv` (default `sys.argv[1:]`), run the command, return the exit code. Never raises `SystemExit`.
+- `app.main(argv=None)` and `app(argv=None)`: `run`, then `sys.exit` with the code.
+- `app.build_parser(prog=None) -> argparse.ArgumentParser`: the underlying parser, if you need it.
+- `app.commands`: dict of registered `Command` objects and nested `App`s, by name.
+
+Running an app (or a group) with no command prints its help and exits 0.
+`--version` is added when `version` is set.
+
+### `run(func, argv=None, *, prog=None, version=None) -> int`
+
+Run a single function as a whole CLI with no subcommands.
+
+### Exit codes
+
+| Outcome                                         | Exit code      |
+|-------------------------------------------------|----------------|
+| command returns `None`                          | `0`            |
+| command returns an `int`                        | that int       |
+| command returns `True` / `False`                | `0` / `1`      |
+| command returns anything else                   | printed, `0`   |
+| `CliError(msg, code)` / `abort(msg, code)`      | `code` (default `1`) |
+| usage error (bad value, missing argument)       | `2`            |
+| `Ctrl-C`                                        | `130`          |
+
+### `Arg(help=None, short=None, name=None, metavar=None, env=None)`
+
+Per-parameter metadata, attached with `typing.Annotated`:
+
+```python
+def login(*, user: Annotated[str, Arg(short="-u", env="APP_USER", help="Account name")]): ...
+```
+
+- `help` overrides the docstring entry.
+- `short` adds a short flag (options and flags only).
+- `name` replaces the long option name.
+- `metavar` sets the usage placeholder.
+- `env` names an environment variable used when the option is not given. Booleans accept `1/true/yes/on` and `0/false/no/off`. List options split the variable on commas. A bad value is a usage error (exit 2).
+
+### Errors
+
+- `CliError(message, exit_code=1)`: raise it for expected failures. It prints `Error: <message>` to stderr.
+- `abort(message, exit_code=1)`: shorthand that raises `CliError`.
+
+### Output
+
+- `style(text, fg=None, bg=None, *, bold=False, dim=False, italic=False, underline=False) -> str`: wrap text in ANSI codes. The colors are `black red green yellow blue magenta cyan white`, each also with a `bright_` prefix. An unknown color raises `ValueError`.
+- `unstyle(text) -> str`: strip ANSI codes.
+- `echo(message="", *, err=False, nl=True, color=None)`: print to stdout or stderr. Styling is stripped unless `should_color(stream)` is true or `color=True` is passed.
+- `secho(message="", *, err=False, nl=True, color=None, **styles)`: `style` and `echo` in one call.
+- `should_color(stream) -> bool`: returns `False` if `NO_COLOR` is set, otherwise `True` if `FORCE_COLOR` is set, otherwise whether `stream` is a TTY.
+- `confirm(prompt, default=False) -> bool`: a yes/no prompt on stdin. An empty answer or end of input returns `default`.
+
+### Lower-level pieces
+
+- `Command(func, name=None, *, help=None, aliases=())`: the object behind each registered command. It has `.name`, `.help`, `.description`, `.aliases` and `.params`.
+- `slick_cli.docstrings.parse_docstring(doc) -> DocInfo` returns `summary`, `description` and `params`.
+
+### Testing: `slick_cli.testing`
+
+```python
+from slick_cli.testing import invoke
+
+result = invoke(app, ["hello", "Ada"], env={"APP_USER": "me"}, input="y\n")
+assert result.exit_code == 0
+assert result.stdout == "Hello, Ada!\n"
+```
+
+`invoke(target, args=(), *, env=None, input=None) -> Result` accepts an `App` or a plain
+function. `Result` has `exit_code`, `stdout` and `stderr`.
+
+## Development
+
+```console
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+# or, if pytest is installed:
+python3 -m pytest
+```
+
+## License
+
+MIT

slick_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+slick_cli/__init__.py,sha256=kZ1TlW-UCGjuWO5DAV_AhyTCifv5ifokBIJCPHqnURA,800
+slick_cli/app.py,sha256=QxnaUSLWUJ4akfLGndzKqusGkdGBF5jE2IKUOyOZjVc,8977
+slick_cli/docstrings.py,sha256=N7KOo-y_1fRboLKJNRsOlECDmdBz3stDv3HSIKzEFCs,2904
+slick_cli/errors.py,sha256=knZq9uOaSAv8dCTOsXlFDVFDE6v_hCCvS3rdEuzd3-E,837
+slick_cli/params.py,sha256=Ya559blCfxizMGr9dN6DOM71vA5WKZtMel_HKOGErHw,11089
+slick_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+slick_cli/style.py,sha256=jvTppM8LbZkzFFOH_OfYU0CZeSN5-sbDTcaNm794a-M,4548
+slick_cli/testing.py,sha256=HbJR_0KUGrNHB1hwkvItt-vzQ9aJHI8YR098MtQDymw,1583
+slick_cli-0.1.0.dist-info/licenses/LICENSE,sha256=pAfYREEW9GAy7cnK20OXjDn7ofJahYny9GCuIZQTDAA,1061
+slick_cli-0.1.0.dist-info/METADATA,sha256=xRuJSrcDWq-creEnhWfk6BywXg6Sn2-uVWY8iD1fihw,10291
+slick_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+slick_cli-0.1.0.dist-info/top_level.txt,sha256=1k0vQfOCH81DDXbq1U38iGqEbrpIsSm_7aZibLGR_fg,10
+slick_cli-0.1.0.dist-info/RECORD,,

slick_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

slick_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nehz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

slick_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+slick_cli