pyfect-dev 0.1.0__py3-none-any.whl

pyfect/cli/cli_error.py

@@ -0,0 +1,242 @@
+"""The errors a command line can fail with (Effect's ``CliError``).
+
+Parsing collects ``UnrecognizedOption``, ``MissingOption``,
+``InvalidValue`` and the rest; ``Command.run`` shows them with the help in
+a ``ShowHelp``. A handler fails with ``UserError`` (or any error with a
+``__cli_user_message__``) to have the runner print a message for the user
+instead of a stack trace.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import ClassVar, Literal, Protocol, runtime_checkable
+
+from pyfect._json_text import stringify
+from pyfect.errors import TaggedError
+
+
+@runtime_checkable
+class HasUserMessage(Protocol):
+    """An error the CLI runner reports with this text (Effect's
+    ``CliError.userMessage`` symbol)."""
+
+    @property
+    def __cli_user_message__(self) -> str: ...
+
+
+def get_user_message(error: object) -> str | None:
+    """The error's ``__cli_user_message__``, if it has a string one."""
+    message = getattr(error, "__cli_user_message__", None)
+    return message if isinstance(message, str) else None
+
+
+def _suggestion_text(suggestions: tuple[str, ...]) -> str:
+    if not suggestions:
+        return ""
+    return "\n\n  Did you mean this?\n    " + "\n    ".join(suggestions)
+
+
+class CliError(TaggedError):
+    """Every CLI error; each class's ``tag`` is Effect's ``_tag``."""
+
+    @property
+    def message(self) -> str:
+        raise NotImplementedError
+
+    @property
+    def tag_name(self) -> str:
+        """Effect's ``_tag``: the class's ``tag``."""
+        return getattr(self, "tag", type(self).__name__)
+
+
+@dataclass(eq=False)
+class UnrecognizedOption(CliError):
+    option: str
+    suggestions: tuple[str, ...] = ()
+    command: tuple[str, ...] | None = None
+    tag: ClassVar[Literal["UnrecognizedOption"]] = "UnrecognizedOption"
+
+    @property
+    def message(self) -> str:
+        base = (
+            f"Unrecognized flag: {self.option} in command {' '.join(self.command)}"
+            if self.command
+            else f"Unrecognized flag: {self.option}"
+        )
+        return base + _suggestion_text(self.suggestions)
+
+
+@dataclass(eq=False)
+class DuplicateOption(CliError):
+    option: str
+    parent_command: str
+    child_command: str
+    tag: ClassVar[Literal["DuplicateOption"]] = "DuplicateOption"
+
+    @property
+    def message(self) -> str:
+        return (
+            f'Duplicate flag name "{self.option}" in parent command "{self.parent_command}" '
+            f'and subcommand "{self.child_command}". '
+            "Parent will always claim this flag (Mode A semantics). "
+            "Consider renaming one of them to avoid confusion."
+        )
+
+
+@dataclass(eq=False)
+class MissingOption(CliError):
+    option: str
+    tag: ClassVar[Literal["MissingOption"]] = "MissingOption"
+
+    @property
+    def message(self) -> str:
+        return f"Missing required flag: --{self.option}"
+
+
+@dataclass(eq=False)
+class MissingArgument(CliError):
+    argument: str
+    tag: ClassVar[Literal["MissingArgument"]] = "MissingArgument"
+
+    @property
+    def message(self) -> str:
+        return f"Missing required argument: {self.argument}"
+
+
+@dataclass(eq=False)
+class UnexpectedArgument(CliError):
+    arguments: tuple[str, ...]
+    tag: ClassVar[Literal["UnexpectedArgument"]] = "UnexpectedArgument"
+
+    @property
+    def message(self) -> str:
+        label = "argument" if len(self.arguments) == 1 else "arguments"
+        return f"Unexpected positional {label}: {', '.join(stringify(a) for a in self.arguments)}"
+
+
+@dataclass(eq=False)
+class InvalidValue(CliError):
+    option: str
+    value: str
+    expected: str
+    kind: Literal["flag", "argument"]
+    tag: ClassVar[Literal["InvalidValue"]] = "InvalidValue"
+
+    @property
+    def message(self) -> str:
+        expectation = (
+            self.expected
+            if self.expected.startswith(("Expected ", "Expected:"))
+            else f"Expected: {self.expected}"
+        )
+        if self.kind == "argument":
+            return f'Invalid value for argument <{self.option}>: "{self.value}". {expectation}'
+        if not self.value:
+            return f"Missing value for flag --{self.option}. {expectation}"
+        return f'Invalid value for flag --{self.option}: "{self.value}". {expectation}'
+
+
+@dataclass(eq=False)
+class UnknownSubcommand(CliError):
+    subcommand: str
+    suggestions: tuple[str, ...] = ()
+    parent: tuple[str, ...] | None = None
+    tag: ClassVar[Literal["UnknownSubcommand"]] = "UnknownSubcommand"
+
+    @property
+    def message(self) -> str:
+        base = (
+            f'Unknown subcommand "{self.subcommand}" for "{" ".join(self.parent)}"'
+            if self.parent
+            else f'Unknown subcommand "{self.subcommand}"'
+        )
+        return base + _suggestion_text(self.suggestions)
+
+
+@dataclass(eq=False)
+class ValidationError(CliError):
+    detail: str
+    tag: ClassVar[Literal["ValidationError"]] = "ValidationError"
+
+    @property
+    def message(self) -> str:
+        return self.detail
+
+
+@dataclass(eq=False)
+class UserError(CliError):
+    """A handler's failure with a message for the user: ``user_message``,
+    else a non-empty string ``cause``, else the cause exception's message,
+    else ``"An error occurred"``. ``run_main`` still reports it."""
+
+    cause: object
+    user_message: str | None = None
+    tag: ClassVar[Literal["UserError"]] = "UserError"
+
+    @property
+    def message(self) -> str:
+        if self.user_message:
+            return self.user_message
+        if isinstance(self.cause, str) and self.cause:
+            return self.cause
+        if isinstance(self.cause, BaseException) and str(self.cause):
+            return str(self.cause)
+        return "An error occurred"
+
+    @property
+    def __cli_user_message__(self) -> str:
+        return self.message
+
+
+type ParseError = (
+    UnrecognizedOption
+    | DuplicateOption
+    | MissingOption
+    | MissingArgument
+    | UnexpectedArgument
+    | InvalidValue
+    | UnknownSubcommand
+    | ValidationError
+    | UserError
+)
+"""Every CLI error but ``ShowHelp`` (Effect's ``NonShowHelpErrors``)."""
+
+
+@dataclass(eq=False)
+class ShowHelp(CliError):
+    """Show the help of ``command_path``, with ``errors`` when parsing
+    failed. Exits with 1 when there are errors, else 0; never reported by
+    ``run_main``."""
+
+    command_path: tuple[str, ...]
+    errors: tuple[ParseError, ...] = field(default=())
+    tag: ClassVar[Literal["ShowHelp"]] = "ShowHelp"
+    error_reported: bool = field(default=False, init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        # ``exit_code`` is per class on ``TaggedError``; this one depends on
+        # the errors, as Effect's ``errorExitCode`` does.
+        object.__setattr__(self, "exit_code", 1 if self.errors else 0)
+
+    @property
+    def message(self) -> str:
+        return "Help requested"
+
+
+__all__ = [
+    "CliError",
+    "DuplicateOption",
+    "HasUserMessage",
+    "InvalidValue",
+    "MissingArgument",
+    "MissingOption",
+    "ParseError",
+    "ShowHelp",
+    "UnexpectedArgument",
+    "UnknownSubcommand",
+    "UnrecognizedOption",
+    "UserError",
+    "ValidationError",
+    "get_user_message",
+]

pyfect/cli/cli_output.py

@@ -0,0 +1,305 @@
+"""How a CLI shows help, errors and its version (Effect's ``CliOutput``).
+
+A ``Formatter`` turns a ``HelpDoc`` or errors into text; a ``Presenter``
+writes the runner's events (help, an invalid invocation, the version) to
+the console. Both have defaults; replace them with ``layer`` and
+``layer_presenter``. Without a formatter provided, the default one colors
+its output when ``TerminalCapabilities`` says the terminal can.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+from pyfect import console
+from pyfect.cli import _ansi as ansi
+from pyfect.cli._width import display_width
+from pyfect.cli.cli_error import CliError, ParseError
+from pyfect.cli.help_doc import FlagDoc, HelpDoc, SubcommandDoc
+from pyfect.cli.terminal_capabilities import TerminalCapabilities
+from pyfect.context import Reference, Tag
+from pyfect.effect import Effect, gen, service_option
+from pyfect.layer import Layer
+from pyfect.layer import succeed as layer_succeed
+from pyfect.option import Some
+
+
+class Formatter(Protocol):
+    def format_help_doc(self, doc: HelpDoc) -> str: ...
+    def format_cli_error(self, error: CliError) -> str: ...
+    def format_error(self, error: CliError) -> str: ...
+    def format_version(self, name: str, version: str) -> str: ...
+    def format_errors(self, errors: Sequence[CliError]) -> str: ...
+
+
+@dataclass(frozen=True, slots=True)
+class Help:
+    reason: Literal["Requested", "Implicit"]
+    command_path: tuple[str, ...]
+    help_doc: HelpDoc
+
+
+@dataclass(frozen=True, slots=True)
+class InvalidInvocation:
+    command_path: tuple[str, ...]
+    help_doc: HelpDoc
+    errors: tuple[ParseError, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class Version:
+    name: str
+    version: str
+
+
+type Event = Help | InvalidInvocation | Version
+
+
+class Presenter(Protocol):
+    def present(self, event: Event) -> Effect[None]: ...
+
+
+class CurrentFormatter(Tag[Formatter]):
+    """The formatter, when one is provided (Effect's ``CliOutput.Formatter``);
+    otherwise output uses ``default_formatter``."""
+
+
+_CONTROL = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+
+
+def _escape(text: str) -> str:
+    return _CONTROL.sub(lambda match: f"\\x{ord(match.group()):02x}", text)
+
+
+@dataclass(frozen=True, slots=True)
+class _Colors:
+    enabled: bool
+
+    def _wrap(self, code: str, text: str) -> str:
+        return f"\x1b[{code}m{text}\x1b[0m" if self.enabled else text
+
+    def bold(self, text: str) -> str:
+        return self._wrap("1", text)
+
+    def dim(self, text: str) -> str:
+        return self._wrap("2", text)
+
+    def cyan(self, text: str) -> str:
+        return self._wrap("36", text)
+
+    def green(self, text: str) -> str:
+        return self._wrap("32", text)
+
+
+@dataclass(frozen=True, slots=True)
+class _DefaultFormatter:
+    colors: _Colors
+
+    def _title(self, text: str) -> str:
+        if not self.colors.enabled:
+            return f"\n{text}"
+        return f"\n{ansi.bold}{ansi.red}{text}{ansi.reset}"
+
+    def _reset(self) -> str:
+        return ansi.reset if self.colors.enabled else ""
+
+    def format_help_doc(self, doc: HelpDoc) -> str:
+        return _format_help_doc(doc, self.colors)
+
+    def format_cli_error(self, error: CliError) -> str:
+        return _escape(error.message)
+
+    def format_error(self, error: CliError) -> str:
+        return f"{self._title('ERROR')}\n  {_escape(error.message)}{self._reset()}"
+
+    def format_errors(self, errors: Sequence[CliError]) -> str:
+        if not errors:
+            return ""
+        if len(errors) == 1:
+            return self.format_error(errors[0])
+        grouped: dict[str, list[CliError]] = {}
+        for error in errors:
+            grouped.setdefault(error.tag_name, []).append(error)
+        lines = [self._title("ERRORS")] + [
+            f"  {_escape(error.message)}{self._reset()}"
+            for group in grouped.values()
+            for error in group
+        ]
+        return "\n".join(lines)
+
+    def format_version(self, name: str, version: str) -> str:
+        colors = self.colors
+        return f"{colors.bold(name)} {colors.dim('v')}{colors.bold(version)}"
+
+
+def default_formatter(*, colors: bool | None = None) -> Formatter:
+    """The built-in formatter; ``colors`` defaults to whether stdout is a
+    terminal and ``NO_COLOR`` is unset."""
+    return _DefaultFormatter(_Colors(ansi.detect_colors() if colors is None else colors))
+
+
+def resolve_formatter() -> Effect[Formatter]:
+    """The provided formatter, else the default one colored as the
+    terminal's capabilities allow."""
+
+    def body():
+        provided = yield from service_option(CurrentFormatter)
+        if isinstance(provided, Some):
+            return provided.value
+        capabilities = yield from TerminalCapabilities()
+        return default_formatter(colors=capabilities.can_color)
+
+    return gen(body)
+
+
+class _DefaultPresenter:
+    def present(self, event: Event) -> Effect[None]:
+        def body():
+            formatter = yield from resolve_formatter()
+            match event:
+                case Help():
+                    yield from console.log(formatter.format_help_doc(event.help_doc))
+                case InvalidInvocation():
+                    yield from console.log(formatter.format_help_doc(event.help_doc))
+                    yield from console.error(formatter.format_errors(event.errors))
+                case Version():
+                    yield from console.log(formatter.format_version(event.name, event.version))
+
+        return gen(body)
+
+
+default_presenter: Presenter = _DefaultPresenter()
+
+
+class CurrentPresenter(Reference[Presenter]):
+    """The presenter the runner uses; defaults to ``default_presenter``."""
+
+    @classmethod
+    def default(cls) -> Presenter:
+        return default_presenter
+
+
+def layer(formatter: Formatter) -> Layer[CurrentFormatter]:
+    return layer_succeed(CurrentFormatter, formatter)
+
+
+def layer_presenter(presenter: Presenter) -> Layer[CurrentPresenter]:
+    return layer_succeed(CurrentPresenter, presenter)
+
+
+# --- help text -------------------------------------------------------------------
+
+
+def _pad(text: str, width: int) -> str:
+    return text + " " * max(0, width - display_width(text))
+
+
+def _render_table(rows: Sequence[tuple[str, str]], width_cap: int | None = None) -> str:
+    max_column = max(display_width(left) for left, _ in rows) + 4
+    column = max_column if width_cap is None else min(max_column, width_cap)
+    return "\n".join(
+        f"  {_pad(left, max(column, display_width(left) + 1))}{right}" for left, right in rows
+    )
+
+
+def _subcommand_name(command: SubcommandDoc) -> str:
+    return f"{command.name}, {command.alias}" if command.alias else command.name
+
+
+def _flag_rows(flags: Sequence[FlagDoc], colors: _Colors) -> list[tuple[str, str]]:
+    rows: list[tuple[str, str]] = []
+    for flag in flags:
+        names = ", ".join(colors.green(name) for name in (f"--{flag.name}", *flag.aliases))
+        type_part = f" {colors.dim(flag.type)}" if flag.type != "boolean" else ""
+        rows.append((names + type_part, flag.description or ""))
+    return rows
+
+
+def _subcommand_rows(commands: Sequence[SubcommandDoc], colors: _Colors) -> list[tuple[str, str]]:
+    return [
+        (colors.cyan(_subcommand_name(sub)), sub.short_description or sub.description)
+        for sub in commands
+    ]
+
+
+def _section(sections: list[str], title: str, body: str, *, blank: bool = True) -> None:
+    sections.append(title)
+    sections.append(body)
+    if blank:
+        sections.append("")
+
+
+def _format_help_doc(doc: HelpDoc, colors: _Colors) -> str:  # noqa: PLR0912 - one branch per section
+    sections: list[str] = []
+    if doc.description:
+        sections += [colors.bold("DESCRIPTION"), f"  {doc.description}", ""]
+    sections += [colors.bold("USAGE"), f"  {colors.cyan(doc.usage)}", ""]
+    if doc.args:
+        rows: list[tuple[str, str]] = []
+        for arg in doc.args:
+            name = arg.name + ("..." if arg.variadic else "")
+            optional = "" if arg.required else colors.dim(" (optional)")
+            rows.append(
+                (f"{colors.green(name)} {colors.dim(arg.type)}", (arg.description or "") + optional)
+            )
+        _section(sections, colors.bold("ARGUMENTS"), _render_table(rows, 25))
+    if doc.flags:
+        flag_rows = _flag_rows(doc.flags, colors)
+        _section(sections, colors.bold("FLAGS"), _render_table(flag_rows))
+    if doc.global_flags:
+        global_rows = _flag_rows(doc.global_flags, colors)
+        _section(sections, colors.bold("GLOBAL FLAGS"), _render_table(global_rows))
+    if doc.subcommands:
+        ungrouped = next((g for g in doc.subcommands if g.group is None), None)
+        if ungrouped is not None:
+            sub_rows = _subcommand_rows(ungrouped.commands, colors)
+            _section(
+                sections,
+                colors.bold("SUBCOMMANDS"),
+                _render_table(sub_rows, 20),
+                blank=len(doc.subcommands) > 1,
+            )
+        for group in doc.subcommands:
+            if group.group is None:
+                continue
+            group_rows = _subcommand_rows(group.commands, colors)
+            _section(sections, colors.bold(f"{group.group}:"), _render_table(group_rows, 20))
+    if doc.examples:
+        sections.append(colors.bold("EXAMPLES"))
+        first = True
+        previous_had_description = False
+        for example in doc.examples:
+            if example.description:
+                if not first:
+                    sections.append("")
+                sections.append(f"  {colors.dim(f'# {example.description}')}")
+            elif previous_had_description:
+                sections.append("")
+            sections.append(f"  {colors.cyan(example.command)}")
+            first = False
+            previous_had_description = bool(example.description)
+        sections.append("")
+    if sections and sections[-1] == "":
+        sections.pop()
+    return "\n".join(sections)
+
+
+__all__ = [
+    "CurrentFormatter",
+    "CurrentPresenter",
+    "Event",
+    "Formatter",
+    "Help",
+    "InvalidInvocation",
+    "Presenter",
+    "Version",
+    "default_formatter",
+    "default_presenter",
+    "display_width",
+    "layer",
+    "layer_presenter",
+    "resolve_formatter",
+]