Colors - tmuxp._internal.colors

Warning

Be careful with these! Internal APIs are not covered by version policies. They can break or be removed between minor versions!

If you need an internal API stabilized please file an issue.

Color output utilities for tmuxp CLI.

This module provides semantic color utilities following patterns from vcspull and CPython’s _colorize module. It includes low-level ANSI styling functions and high-level semantic color utilities.

Examples

Basic usage with automatic TTY detection (AUTO mode is the default). In a TTY, colored text is returned; otherwise plain text:

>>> colors = Colors()

Force colors on or off:

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

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

Environment variables NO_COLOR and FORCE_COLOR are respected. NO_COLOR takes highest priority (disables even in ALWAYS mode):

>>> monkeypatch.setenv("NO_COLOR", "1")
>>> colors = Colors(ColorMode.ALWAYS)
>>> colors.success("loaded")
'loaded'

FORCE_COLOR enables colors in AUTO mode even without TTY:

>>> import sys
>>> monkeypatch.delenv("NO_COLOR", raising=False)
>>> monkeypatch.setenv("FORCE_COLOR", "1")
>>> monkeypatch.setattr(sys.stdout, "isatty", lambda: False)
>>> colors = Colors(ColorMode.AUTO)
>>> colors.success("loaded")
'...'

class tmuxp._internal.colors.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._internal.colors.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

SUCCESS = 'green'

attribute

WARNING = 'yellow'

attribute

ERROR = 'red'

attribute

INFO = 'cyan'

attribute

HEADING = 'bright_cyan'

attribute

HIGHLIGHT = 'magenta'

attribute

MUTED = 'blue'

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

_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

_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'

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'

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'

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'

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'

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)'

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:'

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_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'

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_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_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_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]"'

tmuxp._internal.colors.get_color_mode(color_arg=None)

function

Convert CLI argument string to ColorMode enum.

Parameters:

color_arg (str | None) – Color mode argument from CLI (auto, always, never). None defaults to AUTO.

Returns:

The determined color mode. Invalid values return AUTO.

Return type:

ColorMode

Examples

>>> get_color_mode(None)
<ColorMode.AUTO: 'auto'>
>>> get_color_mode("always")
<ColorMode.ALWAYS: 'always'>
>>> get_color_mode("NEVER")
<ColorMode.NEVER: 'never'>
>>> get_color_mode("invalid")
<ColorMode.AUTO: 'auto'>

tmuxp._internal.colors.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._internal.colors._interpret_color(color, offset=0)

function

Convert color specification to ANSI escape code number.

Parameters:

• color (int | tuple[int, int, int] | str) – Color as 256-color index, RGB tuple, or color name.

• offset (int) – Offset for background colors (10 for bg).

Returns:

ANSI escape code parameters.

Return type:

str

Examples

Color name returns base ANSI code:

>>> _interpret_color("red")
'31'

256-color index returns extended format:

>>> _interpret_color(196)
'38;5;196'

RGB tuple returns 24-bit format:

>>> _interpret_color((255, 128, 0))
'38;2;255;128;0'

exception tmuxp._internal.colors.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._internal.colors.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._internal.colors.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'

tmuxp._internal.colors.build_description(intro, example_blocks)

function

Assemble help text with optional example sections.

Parameters:

• intro (str) – The introductory description text.

• example_blocks (sequence of (heading, commands) tuples) – Each tuple contains an optional heading and a sequence of example commands. If heading is None, the section is titled “examples:”. If heading is provided, it becomes the section title (without “examples:”).

Returns:

Formatted description with examples.

Return type:

str

Examples

>>> from tmuxp._internal.colors import build_description
>>> build_description("My tool.", [(None, ["mytool run"])])
'My tool.\n\nexamples:\n  mytool run'

>>> build_description("My tool.", [("sync", ["mytool sync repo"])])
'My tool.\n\nsync examples:\n  mytool sync repo'

>>> build_description("", [(None, ["cmd"])])
'examples:\n  cmd'