topmark.cli.errors¶

Exceptions for TopMark CLI.

Usage

Raise these exceptions in CLI commands or processing to signal errors with standardized messages and exit codes.

Styling

Exceptions prefer the console stored on the shared typed CLI state (see show()). If no CLI state is available, they fall back to Click's default styling.

TopmarkCliError ¶

Bases: ClickException

Base class for all TopMark CLI errors.

format_message ¶

format_message()

Return the plain error message text.

Notes

Unlike Click's default, this method does not add color.
Colorization is applied in show() when a project console is present.

Source code in src/topmark/cli/errors.py

def format_message(self) -> str:  # pragma: no cover - trivial
    """Return the plain error message text.

    Notes:
        - Unlike Click's default, this method does not add color.
        - Colorization is applied in `show()` when a project console is present.
    """
    # ``self.message`` is set by ClickException; ensure it's a string.
    msg = str(getattr(self, "message", ""))
    return msg

show ¶

show(file=None)

Display the error using the project console if available.

Falls back to Click's default error display when no typed CLI state is available.

Parameters:

Name	Type	Description	Default
`file`	`IO[Any] \| None`	Ignored when a CLI console is available; used only by Click fallback.	`None`

Source code in src/topmark/cli/errors.py

def show(self, file: IO[Any] | None = None) -> None:  # pragma: no cover - Click prints errors
    # Click defines `ClickException.show()` with `IO[Any] | None`; keep the
    # same signature to satisfy override compatibility with third-party stubs.
    """Display the error using the project console if available.

    Falls back to Click's default error display when no typed CLI state is available.

    Args:
        file: Ignored when a CLI console is available; used only by Click fallback.
    """
    try:
        ctx: click.Context | None = click.get_current_context(silent=True)
        if ctx is not None:
            state: TopmarkCliState = get_cli_state(ctx)
            # Use console for user-facing error output with bright red style.
            error_styler: TextStyler = style_for_role(
                StyleRole.ERROR,
                styled=state.color_enabled,
            )
            state.console.error(error_styler(self.format_message()))
            return
    except Exception:  # noqa: BLE001 - never let error rendering crash the CLI
        # Never let error rendering crash the CLI; fall back to Click behavior.
        logger.debug("Failed to render TopMark error via console", exc_info=True)
    # Fallback to Click's default behavior (includes its own styling)
    super().show(file)