CLI utilities - tmuxp.cli.utils

CLI utility helpers for tmuxp.

class tmuxp.cli.utils.ColorMode

class

Bases: Enum

Color output modes for CLI.

Examples

>>> ColorMode.AUTO.value
'auto'
>>> ColorMode.ALWAYS.value
'always'
>>> ColorMode.NEVER.value
'never'

AUTO = 'auto'

attribute

ALWAYS = 'always'

attribute

NEVER = 'never'

attribute

class tmuxp.cli.utils.Colors

class

Bases: object

Semantic color utilities for CLI output.

Provides semantic color methods (success, warning, error, etc.) that conditionally apply ANSI colors based on the color mode and environment.

Parameters:

mode (ColorMode) – Color mode to use. Default is AUTO which detects TTY.

SUCCESS

attribute

Color name for success messages (green)

Type:

str

WARNING

attribute

Color name for warning messages (yellow)

Type:

str

ERROR

attribute

Color name for error messages (red)

Type:

str

INFO

attribute

Color name for informational messages (cyan)

Type:

str

HEADING

attribute

Color name for section headers (bright_cyan)

Type:

str

HIGHLIGHT

attribute

Color name for highlighted/important text (magenta)

Type:

str

MUTED

attribute

Color name for subdued/secondary text (blue)

Type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.success("session loaded")
'session loaded'
>>> colors.error("failed to load")
'failed to load'

>>> colors = Colors(ColorMode.ALWAYS)
>>> result = colors.success("ok")

Check that result contains ANSI escape codes:

>>> "\033[" in result
True

ERROR = 'red'

attribute

HEADING = 'bright_cyan'

attribute

HIGHLIGHT = 'magenta'

attribute

INFO = 'cyan'

attribute

MUTED = 'blue'

attribute

SUCCESS = 'green'

attribute

WARNING = 'yellow'

attribute

__init__(mode=ColorMode.AUTO)

method

Initialize color manager.

Parameters:

mode (ColorMode) – Color mode to use (auto, always, never). Default is AUTO.

Return type:

None

Examples

>>> colors = Colors()
>>> colors.mode
<ColorMode.AUTO: 'auto'>

>>> colors = Colors(ColorMode.NEVER)
>>> colors._enabled
False

_colorize(text, fg, bold=False, dim=False)

method

Apply color using style() function.

Parameters:

• text (str) – Text to colorize.

• fg (str) – Foreground color name (e.g., “green”, “red”).

• bold (bool) – Whether to apply bold style. Default is False.

• dim (bool) – Whether to apply dim/faint style. Default is False.

Returns:

Colorized text if enabled, plain text otherwise.

Return type:

str

Examples

When colors are enabled, applies ANSI escape codes:

>>> colors = Colors(ColorMode.ALWAYS)
>>> colors._colorize("test", "green")
'...'

When colors are disabled, returns plain text:

>>> colors = Colors(ColorMode.NEVER)
>>> colors._colorize("test", "green")
'test'

_should_enable()

method

Determine if color should be enabled.

Follows CPython-style precedence: 1. NO_COLOR env var (any value) -> disable 2. ColorMode.NEVER -> disable 3. ColorMode.ALWAYS -> enable 4. FORCE_COLOR env var (any value) -> enable 5. TTY check -> enable if stdout is a terminal

Returns:

True if colors should be enabled.

Return type:

bool

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors._should_enable()
False

error(text, bold=False)

method

Format text as error (red).

Parameters:

• text (str) – Text to format.

• bold (bool) – Whether to apply bold style. Default is False.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.error("failed")
'failed'

format_kv(key, value)

method

Format key: value pair with syntax highlighting.

Parameters:

• key (str) – Key/label to highlight.

• value (str) – Value to display (not colorized, allows caller to format).

Returns:

Formatted “key: value” string with highlighted key.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_kv("tmux version", "3.2a")
'tmux version: 3.2a'

format_label(label)

method

Format a label (key in key:value pair).

Parameters:

label (str) – Label text to format.

Returns:

Highlighted label text (bold magenta when colors enabled).

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_label("tmux path")
'tmux path'

format_path(path)

method

Format a file path with info color.

Parameters:

path (str) – Path string to format.

Returns:

Cyan-colored path when colors enabled.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_path("/usr/bin/tmux")
'/usr/bin/tmux'

format_rule(width=40, char='─')

method

Format a horizontal rule using Unicode box-drawing characters.

A richer alternative to format_separator() which uses plain hyphens.

Parameters:

• width (int) – Number of characters. Default is 40.

• char (str) – Character to repeat. Default is "─" (U+2500).

Returns:

Muted (blue) rule when colors enabled, plain rule otherwise.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_rule(10)
'──────────'
>>> colors.format_rule(5, char="=")
'====='

format_separator(length=25)

method

Format a visual separator line.

Parameters:

length (int) – Length of the separator line. Default is 25.

Returns:

Muted (blue) separator line when colors enabled.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_separator()
'-------------------------'
>>> colors.format_separator(10)
'----------'

format_tmux_option(line)

method

Format tmux option line with syntax highlighting.

Handles tmux show-options output formats: - “key value” (space-separated) - “key=value” (equals-separated) - “key[index] value” (array-indexed options) - “key” (empty array options with no value)

Parameters:

line (str) – Option line to format.

Returns:

Formatted line with highlighted key and info-colored value.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_tmux_option("status on")
'status on'
>>> colors.format_tmux_option("base-index=1")
'base-index=1'
>>> colors.format_tmux_option("pane-colours")
'pane-colours'
>>> colors.format_tmux_option('status-format[0] "#[align=left]"')
'status-format[0] "#[align=left]"'

format_version(version)

method

Format a version string.

Parameters:

version (str) – Version string to format.

Returns:

Cyan-colored version when colors enabled.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.format_version("3.2a")
'3.2a'

heading(text)

method

Format text as a section heading (bright cyan, bold).

Used for section headers like ‘Local workspaces:’ or ‘Global workspaces:’. Uses bright_cyan to visually distinguish from info() which uses cyan.

Parameters:

text (str) – Text to format.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.heading("Local workspaces:")
'Local workspaces:'

highlight(text, bold=True)

method

Format text as highlighted (magenta, bold by default).

Parameters:

• text (str) – Text to format.

• bold (bool) – Whether to apply bold style. Default is True.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.highlight("my-session")
'my-session'

info(text, bold=False)

method

Format text as info (cyan).

Parameters:

• text (str) – Text to format.

• bold (bool) – Whether to apply bold style. Default is False.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.info("/path/to/config.yaml")
'/path/to/config.yaml'

muted(text)

method

Format text as muted (blue).

Parameters:

text (str) – Text to format.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.muted("(optional)")
'(optional)'

success(text, bold=False)

method

Format text as success (green).

Parameters:

• text (str) – Text to format.

• bold (bool) – Whether to apply bold style. Default is False.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.success("loaded")
'loaded'

warning(text, bold=False)

method

Format text as warning (yellow).

Parameters:

• text (str) – Text to format.

• bold (bool) – Whether to apply bold style. Default is False.

Returns:

Formatted text.

Return type:

str

Examples

>>> colors = Colors(ColorMode.NEVER)
>>> colors.warning("check config")
'check config'

exception tmuxp.cli.utils.UnknownStyleColor

exception

Bases: Exception

Raised when encountering an unknown terminal style color.

Examples

>>> try:
...     raise UnknownStyleColor("invalid_color")
... except UnknownStyleColor as e:
...     "invalid_color" in str(e)
True

__init__(color, *args, **kwargs)

method

Parameters:

• color (CLIColour)

• args (object)

• kwargs (object)

Return type:

None

tmuxp.cli.utils.prompt(name, default=None, value_proc=None, *, color_mode=None)

function

Return user input from command line.

Parameters:

• name (str) – prompt text

• default (str | None) – default value if no input provided.

• color_mode (ColorMode | None) – color mode for prompt styling. Defaults to AUTO if not specified.

• value_proc (Callable[[str], str] | None)

Return type:

str

See also

prompt(), prompt_bool(), :py:obj:``flask-script`, :py:obj:``flask-script`

tmuxp.cli.utils.prompt_bool(name, default=False, yes_choices=None, no_choices=None, *, color_mode=None)

function

Return True / False by prompting user input from command line.

Parameters:

• name (str) – prompt text

• default (bool) – default value if no input provided.

• yes_choices (Sequence[Any] | None) – default ‘y’, ‘yes’, ‘1’, ‘on’, ‘true’, ‘t’

• no_choices (Sequence[Any] | None) – default ‘n’, ‘no’, ‘0’, ‘off’, ‘false’, ‘f’

• color_mode (ColorMode | None) – color mode for prompt styling. Defaults to AUTO if not specified.

Return type:

bool

tmuxp.cli.utils.prompt_choices(name, choices, default=None, no_choice=('none',), *, color_mode=None)

function

Return user input from command line from set of provided choices.

Parameters:

• name (str) – prompt text

• choices (Sequence[str | tuple[str, str]]) – Sequence of available choices. Each choice may be a single string or a (key, value) tuple where key is used for matching.

• default (str | None) – default value if no input provided.

• no_choice (Sequence[str]) – acceptable list of strings for “null choice”

• color_mode (ColorMode | None) – color mode for prompt styling. Defaults to AUTO if not specified.

Return type:

str

tmuxp.cli.utils.prompt_yes_no(name, default=True, *, color_mode=None)

function

prompt_bool() returning yes by default.

Parameters:

• name (str) – prompt text

• default (bool) – default value if no input provided.

• color_mode (ColorMode | None) – color mode for prompt styling. Defaults to AUTO if not specified.

Return type:

bool

tmuxp.cli.utils.strip_ansi(value)

function

Clear ANSI escape codes from a string value.

Parameters:

value (str) – String potentially containing ANSI escape codes.

Returns:

String with ANSI codes removed.

Return type:

str

Examples

>>> strip_ansi("\033[32mgreen\033[0m")
'green'
>>> strip_ansi("plain text")
'plain text'

tmuxp.cli.utils.style(text, fg=None, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, reset=True)

function

Apply ANSI styling to text.

Credit: click.

Parameters:

• text (Any) – Text to style (will be converted to str).

• fg (CLIColour | None) – Foreground color (name, 256-index, or RGB tuple).

• bg (CLIColour | None) – Background color.

• bold (bool | None) – Apply bold style.

• dim (bool | None) – Apply dim style.

• underline (bool | None) – Apply underline style.

• overline (bool | None) – Apply overline style.

• italic (bool | None) – Apply italic style.

• blink (bool | None) – Apply blink style.

• reverse (bool | None) – Apply reverse video style.

• strikethrough (bool | None) – Apply strikethrough style.

• reset (bool) – Append reset code at end. Default True.

Returns:

Styled text with ANSI escape codes.

Return type:

str

Examples

>>> style("hello", fg="green")
'\x1b[32m...'
>>> "hello" in style("hello", fg="green")
True

tmuxp.cli.utils.tmuxp_echo(message=None, file=None)

function

Print user-facing CLI output.

Parameters:

• message (str | None) – Message to print. If None, does nothing.

• file (t.TextIO | None) – Output stream. Defaults to sys.stdout.

Return type:

None

Examples

>>> tmuxp_echo("Session loaded")
Session loaded

>>> tmuxp_echo("Warning message")
Warning message

tmuxp.cli.utils.unstyle(text)

function

Remove ANSI styling information from a string.

Usually it’s not necessary to use this function as tmuxp_echo function will automatically remove styling if necessary.

Credit: click.

Parameters:

text (str) – Text to remove style information from.

Returns:

Text with ANSI codes removed.

Return type:

str

Examples

>>> unstyle("\033[32mgreen\033[0m")
'green'