CLI utilities - tmuxp.cli.utils

CLI utility helpers for tmuxp.

class tmuxp.cli.utils.ColorMode
class[source]
class[source]
class tmuxp.cli.utils.ColorMode

Bases: Enum

Color output modes for CLI.

Examples

>>> ColorMode.AUTO.value
'auto'
>>> ColorMode.ALWAYS.value
'always'
>>> ColorMode.NEVER.value
'never'
AUTO = 'auto'
attribute
attribute
AUTO = 'auto'
ALWAYS = 'always'
attribute
attribute
ALWAYS = 'always'
NEVER = 'never'
attribute
attribute
NEVER = 'never'
class tmuxp.cli.utils.Colors
class[source]
class[source]
class tmuxp.cli.utils.Colors

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
attribute
SUCCESS

Color name for success messages (green)

Type:

str

WARNING
attribute
attribute
WARNING

Color name for warning messages (yellow)

Type:

str

ERROR
attribute
attribute
ERROR

Color name for error messages (red)

Type:

str

INFO
attribute
attribute
INFO

Color name for informational messages (cyan)

Type:

str

HEADING
attribute
attribute
HEADING

Color name for section headers (bright_cyan)

Type:

str

HIGHLIGHT
attribute
attribute
HIGHLIGHT

Color name for highlighted/important text (magenta)

Type:

str

MUTED
attribute
attribute
MUTED

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
attribute
ERROR = 'red'
HEADING = 'bright_cyan'
attribute
attribute
HEADING = 'bright_cyan'
HIGHLIGHT = 'magenta'
attribute
attribute
HIGHLIGHT = 'magenta'
INFO = 'cyan'
attribute
attribute
INFO = 'cyan'
MUTED = 'blue'
attribute
attribute
MUTED = 'blue'
SUCCESS = 'green'
attribute
attribute
SUCCESS = 'green'
WARNING = 'yellow'
attribute
attribute
WARNING = 'yellow'
__init__(mode=ColorMode.AUTO)
method[source]
method[source]
__init__(mode=ColorMode.AUTO)

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[source]
method[source]
_colorize(text, fg, bold=False, dim=False)

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[source]
method[source]
_should_enable()

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[source]
method[source]
error(text, bold=False)

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[source]
method[source]
format_kv(key, value)

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[source]
method[source]
format_label(label)

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[source]
method[source]
format_path(path)

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[source]
method[source]
format_rule(width=40, char="─"))

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[source]
method[source]
format_separator(length=25)

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[source]
method[source]
format_tmux_option(line)

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[source]
method[source]
format_version(version)

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[source]
method[source]
heading(text)

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[source]
method[source]
highlight(text, bold=True)

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[source]
method[source]
info(text, bold=False)

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[source]
method[source]
muted(text)

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[source]
method[source]
success(text, bold=False)

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[source]
method[source]
warning(text, bold=False)

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[source]
exception[source]
exception tmuxp.cli.utils.UnknownStyleColor

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[source]
method[source]
__init__(color, *args, **kwargs)
Parameters:
Return type:

None

tmuxp.cli.utils.prompt(name, default=None, value_proc=None, *, color_mode=None)
function[source]
function[source]
tmuxp.cli.utils.prompt(name, default=None, value_proc=None, *, color_mode=None)

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[source]
function[source]
tmuxp.cli.utils.prompt_bool(name, default=False, yes_choices=None, no_choices=None, *, color_mode=None)

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[source]
function[source]
tmuxp.cli.utils.prompt_choices(name, choices, default=None, no_choice=('none',), *, color_mode=None)

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[source]
function[source]
tmuxp.cli.utils.prompt_yes_no(name, default=True, *, color_mode=None)

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[source]
function[source]
tmuxp.cli.utils.strip_ansi(value)

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[source]
function[source]
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)

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[source]
function[source]
tmuxp.cli.utils.tmuxp_echo(message=None, file=None)

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[source]
function[source]
tmuxp.cli.utils.unstyle(text)

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'