cli-error 0.1.0__py3-none-any.whl

cli_error/__init__.py

@@ -0,0 +1,21 @@
+"""Error handling and reporting utilities for CLI applications."""
+
+__all__ = [
+    "CliError",
+    "CliExit",
+    "CliReporter",
+    "DEFAULT_STYLES",
+    "escape",
+    "make_console",
+    "make_theme",
+    "print_error",
+    "render_error",
+    "render_template",
+]
+
+from rich.markup import escape
+
+from ._console import DEFAULT_STYLES, make_console, make_theme
+from ._errors import CliError, CliExit, print_error
+from ._render import render_error, render_template
+from ._reporter import CliReporter

cli_error/_console.py

@@ -0,0 +1,40 @@
+from collections.abc import Mapping
+
+from rich.console import Console
+from rich.style import Style
+from rich.theme import Theme
+
+DEFAULT_STYLES: Mapping[str, str] = {
+    "id": "green",
+    "data": "cyan",
+    "path": "dim",
+    "cmd": "blue",
+    "misc": "dim",
+    "warn": "yellow",
+    "err": "red",
+}
+
+
+def make_theme(*, styles: Mapping[str, str | Style] | None = None) -> Theme:
+    """Return a Rich theme built from the default roles plus ``styles``"""
+    return Theme({**DEFAULT_STYLES, **(styles or {})})
+
+
+def make_console(
+    *,
+    styles: Mapping[str, str | Style] | None = None,
+    no_color: bool = False,
+    stderr: bool = False,
+) -> Console:
+    """Return a Rich console themed with the default style roles.
+
+    ``styles`` overrides or extends :data:`DEFAULT_STYLES` for this console.
+    Set ``no_color`` to render styled markup as plain text (no ANSI escapes).
+    Set ``stderr`` to route output to ``sys.stderr`` instead of ``sys.stdout``.
+    """
+    return Console(
+        theme=make_theme(styles=styles),
+        highlight=False,
+        stderr=stderr,
+        no_color=no_color,
+    )

cli_error/_errors.py

@@ -0,0 +1,92 @@
+from typing import Any, Self
+
+from rich.console import Console
+from rich.markup import escape
+
+from ._render import (
+    ErrorDesc,
+    render_error,
+    render_template,
+    strip_markup,
+)
+
+
+class CliError(Exception):
+    """An application error carrying a Rich-markup message."""
+
+    def __init__(self, template: str, /, **args: Any) -> None:
+        self.desc = ErrorDesc(render_template(template, **args))
+        super().__init__(self.desc.message)
+
+    def hint(self, template: str, /, **args: Any) -> Self:
+        self.desc.hint = render_template(template, **args)
+        return self
+
+    def detail(self, text: str) -> Self:
+        self.desc.detail = render_template("[misc]{detail}[/misc]", detail=text)
+        return self
+
+    def prop(self, key: str, template: str, /, **args: Any) -> Self:
+        self.desc.props[key] = render_template(template, **args)
+        return self
+
+    def prop_id(self, key: str, value: Any) -> Self:
+        return self.prop(key, "[id]{value}[/id]", value=value)
+
+    def prop_path(self, key: str, value: Any) -> Self:
+        return self.prop(key, "[path]{value}[/path]", value=value)
+
+    def prop_data(self, key: str, value: Any) -> Self:
+        return self.prop(key, "[data]{value}[/data]", value=value)
+
+    def prop_cmd(self, key: str, value: Any) -> Self:
+        return self.prop(key, "[cmd]{value}[/cmd]", value=value)
+
+    def prop_misc(self, key: str, value: Any) -> Self:
+        return self.prop(key, "[misc]{value}[/misc]", value=value)
+
+    def __str__(self) -> str:
+        return strip_markup(self.desc.message)
+
+
+class CliExit(Exception):
+    """A clean-exit signal carrying a message."""
+
+    def __init__(self, template: str, /, **args: Any) -> None:
+        self.message = render_template(template, **args)
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        return strip_markup(self.message)
+
+
+def print_error(ex: Exception, console: Console) -> None:
+    if isinstance(ex, CliError):
+        console.print(f"[err]Error:[/err] {render_error(ex.desc)}")
+    else:
+        console.print(
+            render_template("[err]Error:[/err] {ex}", ex=_message_or_type(ex))
+        )
+
+    seen = {id(ex)}
+    cause = _next_link(ex)
+    while cause is not None and id(cause) not in seen:
+        # note: markup-stripped for CliError via its __str__,
+        # not the full props/detail/hint layout
+        console.print(f"  caused by: {escape(_message_or_type(cause))}")
+        seen.add(id(cause))
+        cause = _next_link(cause)
+
+
+def _message_or_type(exc: BaseException) -> str:
+    text = str(exc)
+    if text.strip():
+        return text
+    return type(exc).__name__
+
+
+def _next_link(exc: BaseException) -> BaseException | None:
+    if exc.__cause__ is not None:
+        return exc.__cause__
+
+    return None if exc.__suppress_context__ else exc.__context__

cli_error/_render.py

@@ -0,0 +1,41 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from rich.markup import escape
+from rich.text import Text
+
+
+@dataclass
+class ErrorDesc:
+    message: str
+    props: dict[str, str] = field(default_factory=dict)
+    detail: str = ""
+    hint: str = ""
+
+
+def render_error(desc: ErrorDesc) -> str:
+    r = []
+    r.append(desc.message)
+
+    for key, value in desc.props.items():
+        r.append(f"  {escape(key)}: {value}")
+
+    if desc.detail:
+        r.append(desc.detail)
+
+    if desc.hint:
+        r.append("")
+        r.append(desc.hint)
+
+    return "\n".join(r)
+
+
+def render_template(template: str, /, **args: Any) -> str:
+    if not args:
+        return template
+
+    return template.format(**{key: escape(str(value)) for key, value in args.items()})
+
+
+def strip_markup(text: str) -> str:
+    return Text.from_markup(text).plain

cli_error/_reporter.py

@@ -0,0 +1,108 @@
+import shlex
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+
+from ._console import make_console
+from ._errors import CliExit, print_error
+from ._render import render_template
+
+
+class CliReporter:
+    """Single integration point for a CLI's terminal output."""
+
+    debug: bool = False
+
+    def __init__(
+        self,
+        console: Console,
+        *,
+        debug: bool = False,
+        console_err: Console | None = None,
+    ) -> None:
+        self.debug = debug
+        self.console = console
+        self.console_err = console_err or make_console(stderr=True)
+
+    def print(self, template: str, /, *, end: str = "\n", **args: Any) -> None:
+        """Render a trusted template with escaped args to the stdout console."""
+        _emit(self.console, template, end, **args)
+
+    def debug_print(self, template: str, /, *, end: str = "\n", **args: Any) -> None:
+        """Render a trusted template with escaped args to the stderr console.
+
+        Silent no-op unless ``debug`` is set. The template is emitted unchanged
+        (no forced styling), so a consumer can emit e.g. a ``[warn]`` line.
+        """
+        if self.debug:
+            _emit(self.console_err, template, end, **args)
+
+    def debug_traceback(self) -> None:
+        """Emit the currently-handled traceback to the stderr console.
+
+        No-op unless ``debug`` is set. Safely no-ops outside an ``except``
+        block: ``print_exception`` reads ``sys.exc_info()``.
+        """
+        if not self.debug:
+            return
+
+        if sys.exc_info()[0] is None:
+            return
+
+        self.console_err.print_exception()
+
+    def debug_cmd(self, cmd: list[str], cwd: Path | None = None) -> None:
+        """Emit a subprocess command (and optional cwd) as a debug diagnostic."""
+        if not self.debug:
+            return
+
+        self.debug_print("[misc]COMMAND: {cmd}[/misc]", cmd=shlex.join(cmd))
+        if cwd is not None:
+            self.debug_print("[misc]  cwd: {cwd}[/misc]", cwd=cwd)
+
+    def debug_output(self, stdout: str, stderr: str) -> None:
+        """Emit captured subprocess output as debug diagnostics.
+
+        Each non-empty stream is emitted as a header line followed by the
+        captured text as one escaped ``misc`` block; empty streams are skipped.
+        """
+        if not self.debug:
+            return
+
+        for label, text in (("stdout", stdout), ("stderr", stderr)):
+            trimmed = text.rstrip()
+            if not trimmed:
+                continue
+
+            # TODO: this layout is ugly, lets prepend each line 'stdout: ' prefix
+            self.debug_print("[misc]  {label}:[/misc]", label=label)
+            self.debug_print("[misc]{text}[/misc]", text=trimmed)
+
+    @contextmanager
+    def handler(self) -> Generator[None]:
+        """Report errors and translate them into process exit codes.
+
+        * ``CliExit`` prints its message and exits 0;
+        * any other ``Exception`` is rendered via ``print_error`` and exits 1,
+          additionally emitting a full traceback to the ``stderr`` console when
+          ``debug`` is set.
+        * ``KeyboardInterrupt``, ``SystemExit`` and any other ``BaseException``
+        propagate untouched.
+        """
+        try:
+            yield
+        except CliExit as ex:
+            self.print(ex.message)
+            raise SystemExit(0) from None
+        except Exception as ex:
+            self.debug_traceback()
+            print_error(ex, self.console)
+            raise SystemExit(1) from None
+
+
+def _emit(console: Console, template: str, end: str, /, **args: Any) -> None:
+    console.print(render_template(template, **args), end=end)

cli_error-0.1.0.dist-info/METADATA

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: cli-error
+Version: 0.1.0
+Summary: Error handling and reporting utilities for CLI applications.
+Requires-Python: >=3.12
+Requires-Dist: rich

cli_error-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+cli_error/__init__.py,sha256=bTz2QGYBmn9yIZ7flKU_a2oulilKaCV5b4CKnOBuiLs,502
+cli_error/_console.py,sha256=7mVYKI-6kUhuFi8I8bIX_Mw9LxX5yXs3i3HMSpSGZ_s,1114
+cli_error/_errors.py,sha256=FTdUC1WhaDwbirPWfwXmwjql4v6GpH-0Um5H5zwUe8I,2853
+cli_error/_render.py,sha256=v6pSrU8EPhTSZCbbR9ZuXCxPYA3NZX-xFkySUsTiFIU,849
+cli_error/_reporter.py,sha256=0b2C8oJ5yd5GNTZrOVnuHOaD4m2XgxV8eZqcL_NLOUc,3748
+cli_error/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cli_error-0.1.0.dist-info/METADATA,sha256=m3RKE4Xske0gGjsvA7vjzga_mJxnylBBMfKZPfL7k5U,167
+cli_error-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cli_error-0.1.0.dist-info/RECORD,,

cli_error-0.1.0.dist-info/WHEEL

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