tmuxp formatter - tmuxp.cli._formatter

Custom help formatter for tmuxp CLI with colorized examples.

This module provides a custom argparse formatter that colorizes example sections in help output, similar to vcspull’s formatter.

Examples

>>> from tmuxp.cli._formatter import TmuxpHelpFormatter
>>> TmuxpHelpFormatter
<class '...TmuxpHelpFormatter'>
class tmuxp.cli._formatter.TmuxpHelpFormatter
class[source]
class[source]
class tmuxp.cli._formatter.TmuxpHelpFormatter

Bases: RawDescriptionHelpFormatter

Help formatter with colorized examples for tmuxp CLI.

This formatter extends RawDescriptionHelpFormatter to preserve formatting of description text while adding syntax highlighting to example sections.

Example colors come from _example_theme(): argparse’s own theme on Python 3.14+, where argparse colors help itself, and the bound _help_theme on older Pythons. With neither, the formatter falls back to plain text output.

Examples

>>> formatter = TmuxpHelpFormatter("tmuxp")
>>> formatter
<...TmuxpHelpFormatter object at ...>
_help_theme: HelpTheme | None = None
attribute
attribute
_help_theme: HelpTheme | None = None
_example_theme()
method[source]
method[source]
_example_theme()

Return the theme that colors example sections.

On Python 3.14+ argparse decides whether help is colored (NO_COLOR, FORCE_COLOR, the output stream) and supplies the palette as _theme; examples follow it so they match the usage line. Older argparse has no _theme, so tmuxp’s bound theme is used.

Returns:

Theme for example sections, or None for plain text.

Return type:

HelpTheme | None

Examples

>>> import sys
>>> formatter = TmuxpHelpFormatter("tmuxp")
>>> theme = formatter._example_theme()
>>> (theme is None) == (sys.version_info < (3, 14))
True
_fill_text(text, width, indent)
method[source]
method[source]
_fill_text(text, width, indent)

Fill text, colorizing examples sections if theme is available.

Parameters:

  • text (str) – Text to format.

  • width (int) – Maximum line width.

  • indent (str) – Indentation prefix.

Returns:

Formatted text, with colorized examples if theme is set.

Return type:

str

Examples

Without theme, returns text via parent formatter:

>>> formatter = TmuxpHelpFormatter("test")
>>> formatter._fill_text("hello", 80, "")
'hello'
class _ColorizedLine
class[source]
class[source]
class _ColorizedLine

Bases: NamedTuple

Result of colorizing an example line.

text: str
attribute
attribute
text: str

Alias for field number 0

expect_value: bool
attribute
attribute
expect_value: bool

Alias for field number 1

__new__(_cls, text, expect_value)
staticmethod method
staticmethod method
__new__(_cls, text, expect_value)

Create new instance of _ColorizedLine(text, expect_value)

Parameters:
_asdict()
method[source]
method[source]
_asdict()

Return a new dict which maps field names to their values.

_make(iterable)
classmethod method[source]
classmethod method[source]
_make(iterable)

Make a new _ColorizedLine object from a sequence or iterable

_replace(**kwds)
method[source]
method[source]
_replace(**kwds)

Return a new _ColorizedLine object replacing specified fields with new values

_colorize_example_line(content, *, theme, expect_value)
method[source]
method[source]
_colorize_example_line(content, *, theme, expect_value)

Colorize a single example command line.

Parameters:

  • content (str) – The line content to colorize.

  • theme (Any) – Theme object with color attributes (prog, action, etc.).

  • expect_value (bool) – Whether the previous token expects a value.

Returns:

Named tuple with colorized text and updated expect_value state.

Return type:

_ColorizedLine

Examples

With an empty theme (no colors), returns text unchanged:

>>> formatter = TmuxpHelpFormatter("test")
>>> theme = HelpTheme.from_colors(None)
>>> result = formatter._colorize_example_line(
...     "tmuxp load", theme=theme, expect_value=False
... )
>>> result.text
'tmuxp load'
>>> result.expect_value
False
class tmuxp.cli._formatter.HelpTheme
class[source]
class[source]
class tmuxp.cli._formatter.HelpTheme

Bases: NamedTuple

Theme colors for help output.

Each field is the ANSI escape prefix written before a token; reset closes it. from_colors() sets every field to "" when color is disabled, so the same formatting code emits plain text.

prog: str
attribute
attribute
prog: str

Escape prefix for the program name leading an example command.

action: str
attribute
attribute
action: str

Escape prefix for the subcommand following the program name.

long_option: str
attribute
attribute
long_option: str

Escape prefix for -- options.

short_option: str
attribute
attribute
short_option: str

Escape prefix for single-dash options.

label: str
attribute
attribute
label: str

Escape prefix for the value that follows an option expecting one.

heading: str
attribute
attribute
heading: str

Escape prefix for example section headings such as Examples:.

reset: str
attribute
attribute
reset: str

Escape sequence that ends styling, "" when color is disabled.

Examples

>>> from tmuxp.cli._formatter import HelpTheme
>>> theme = HelpTheme.from_colors(None)
>>> theme.reset
''
from_colors(colors)
classmethod method[source]
classmethod method[source]
from_colors(colors)

Create theme from a Colors instance.

Parameters:

colors (Colors | None) – Colors instance, or None for no colors.

Returns:

Theme with ANSI codes if colors enabled, empty strings otherwise.

Return type:

HelpTheme

Examples

>>> from tmuxp.cli._colors import Colors, ColorMode
>>> from tmuxp.cli._formatter import HelpTheme
>>> colors = Colors(ColorMode.NEVER)
>>> theme = HelpTheme.from_colors(colors)
>>> theme.reset
''
__new__(_cls, prog, action, long_option, short_option, label, heading, reset)
staticmethod method
staticmethod method
__new__(_cls, prog, action, long_option, short_option, label, heading, reset)

Create new instance of HelpTheme(prog, action, long_option, short_option, label, heading, reset)

Parameters:
_asdict()
method[source]
method[source]
_asdict()

Return a new dict which maps field names to their values.

_make(iterable)
classmethod method[source]
classmethod method[source]
_make(iterable)

Make a new HelpTheme object from a sequence or iterable

_replace(**kwds)
method[source]
method[source]
_replace(**kwds)

Return a new HelpTheme object replacing specified fields with new values

tmuxp.cli._formatter.create_themed_formatter(colors=None)
function[source]
function[source]
tmuxp.cli._formatter.create_themed_formatter(colors=None)

Create a help formatter class with theme bound.

This factory creates a formatter subclass with the theme injected, allowing colorized help output without modifying argparse internals.

When no colors argument is provided, uses AUTO mode which respects NO_COLOR, FORCE_COLOR environment variables and TTY detection. The bound theme colors examples below Python 3.14; from 3.14 argparse’s own theme does (see TmuxpHelpFormatter._example_theme()).

Parameters:

colors (Colors | None) – Colors instance for styling. If None, uses AUTO.

Returns:

Formatter class with theme bound.

Return type:

type[TmuxpHelpFormatter]

Examples

>>> from tmuxp.cli._colors import ColorMode, Colors
>>> from tmuxp.cli._formatter import create_themed_formatter, HelpTheme

With explicit colors enabled:

>>> colors = Colors(ColorMode.ALWAYS)
>>> formatter_cls = create_themed_formatter(colors)
>>> formatter_cls._help_theme is not None
True

With colors disabled:

>>> colors = Colors(ColorMode.NEVER)
>>> formatter_cls = create_themed_formatter(colors)
>>> formatter_cls._help_theme is None
True