cape.tui.tuiutils: Render helpers for the CAPE TUI

This module provides the presentation helpers for cape.tui, the Textual-based interactive terminal user interface to CAPE. These functions build Rich renderables (tables, panels) which the app writes to its scroll log or prints to the terminal on exit.

cape.tui.tuiutils.banner_panel(histfile: str | None = None) → Panel

Build the CAPE TUI startup banner

Call:

>>> panel = banner_panel(histfile=None)

Inputs:

histfile: {None} | str

Name of command history file

Outputs:

panel: rich.panel.Panel

Startup banner with host info and key hints

cape.tui.tuiutils.cmd_help_panel(cmdname: str, subcls: type, cls: type) → Panel

Build a Rich help panel for a single CAPE sub-command

Call:

>>> panel = cmd_help_panel(cmdname, subcls, cls)

Inputs:

cmdname: str

Name of command

subcls: type

cape.argread.ArgReader for cmdname

cls: type

cape.argread.ArgReader for front desk

Outputs:

panel: rich.panel.Panel

Panel with description, aliases, and options table

cape.tui.tuiutils.cmd_table(cls: type) → Table

Build a Rich table of all CAPE sub-commands

Call:

>>> table = cmd_table(cls)

Inputs:

cls: type

cape.argread.ArgReader subtype

Outputs:

table: rich.table.Table

Table of CAPE commands, descriptions, and aliases

cape.tui.tuiutils.get_dirname(path: str | None = None) → str

Get the last two folders of a path, as in cape.ui

Call:

>>> dirname = get_dirname(path=None)

Inputs:

path: {None} | str

Folder to summarize; default is current working folder

Outputs:

dirname: str

Last two folders of path

cape.tui.tuiutils.get_tui_histfile() → str

Get the name of the CAPE TUI history file

The file is controlled by the TUIHistoryFile option from the user’s ~/.capeconfig.json (or the $CAPE_TUI_HISTORY_FILE environment variable). Relative paths are joined with the CAPE CacheDir.

Call:

>>> histfile = get_tui_histfile()

Outputs:

histfile: str

Name of TUI command history file

cape.tui.tuiutils.history_table(history: list, n: int = 25) → Table

Build a table of recently-run commands

Call:

>>> table = history_table(history, n=25)

Inputs:

history: list[str]

Full session history (oldest first)

n: {25} | int

Number of recent commands to show

Outputs:

table: rich.table.Table

Table with 1-based history numbers and command text

cape.tui.tuiutils.meta_help_table() → Table

Build table of TUI meta-commands

Call:

>>> table = meta_help_table()

Outputs:

table: rich.table.Table

Table of TUI meta-commands and their descriptions

cape.tui.tuiutils.session_stats_panel(stats: dict, histfile: str | None = None, title: str = 'CAPE TUI session') → Panel

Build a panel summarizing the TUI session

Call:

>>> panel = session_stats_panel(stats, histfile=None)
>>> panel = session_stats_panel(stats, histfile, title="Bye")

Inputs:

stats: dict

Session statistics (commands, failures, etc.); json_files and last_json_file add JSON context

histfile: {None} | str

Name of command history file

title: {"CAPE TUI session"} | str

Title for statistics panel

Outputs:

panel: rich.panel.Panel

Session summary panel

cape.tui.tuiutils.sprintf_duration(dt: float) → str

Format a duration in seconds as a compact string

Call:

>>> txt = sprintf_duration(dt)

Inputs:

dt: float

Duration in seconds

Outputs:

txt: str

Compact string, e.g. "0.42 s" or "1 min 5 s"