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(*values)[source]¶

Bases: Enum

Color output modes for CLI.

Examples

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

AUTO = 'auto'¶

ALWAYS = 'always'¶

NEVER = 'never'¶

class tmuxp._internal.colors.Colors(mode=ColorMode.AUTO)[source]¶

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¶

Color name for success messages (green)

Type:: str

WARNING¶

Color name for warning messages (yellow)

Type:: str

ERROR¶

Color name for error messages (red)

Type:: str

INFO¶

Color name for informational messages (cyan)

Type:: str

HEADING¶

Color name for section headers (bright_cyan)

Type:: str

HIGHLIGHT¶

Color name for highlighted/important text (magenta)

Type:: str

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

SUCCESS = 'green'¶

WARNING = 'yellow'¶

ERROR = 'red'¶

INFO = 'cyan'¶

HEADING = 'bright_cyan'¶

HIGHLIGHT = 'magenta'¶

MUTED = 'blue'¶

_should_enable()[source]¶

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

Return type:: bool
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)[source]¶

Apply color using style() function.

Return type:

str

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

Format text as success (green).

Return type:

str

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

Format text as warning (yellow).

Return type:

str

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

Format text as error (red).

Return type:

str

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

Format text as info (cyan).

Return type:

str

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

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

Return type:

str

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

Format text as muted (blue).

Return type:: str
Parameters:: text (str) – Text to format.
Returns:: Formatted text.
Return type:: str

Examples

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

heading(text)[source]¶

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.

Return type:: str
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)[source]¶

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

Return type:: str
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)[source]¶

Format a file path with info color.

Return type:: str
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)[source]¶

Format a version string.

Return type:: str
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)[source]¶

Format a visual separator line.

Return type:: str
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_kv(key, value)[source]¶

Format key: value pair with syntax highlighting.

Return type:

str

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

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)

Return type:: str
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)[source]¶

Convert CLI argument string to ColorMode enum.

Return type:: ColorMode
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)[source]¶

Clear ANSI escape codes from a string value.

Return type:: str
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)[source]¶

Convert color specification to ANSI escape code number.

Return type:

str

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(color, *args, **kwargs)[source]¶

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

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

Apply ANSI styling to text.

Credit: click.

Return type:

str

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

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.

Return type:: str
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)[source]¶

Assemble help text with optional example sections.

Return type:

str

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'

Colors - tmuxp._internal.colors¶

Colors - `tmuxp._internal.colors`¶