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.

The formatter uses a _theme attribute (set externally) to apply colors. If no theme is set, the formatter falls back to plain text output.

Examples

>>> formatter = TmuxpHelpFormatter("tmuxp")
>>> formatter
<...TmuxpHelpFormatter object at ...>
_theme: HelpTheme | None = None
attribute
attribute
_theme: HelpTheme | None = None
_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

static __new__(_cls, text, expect_value)
staticmethod method
staticmethod method
static __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.

_field_defaults = {}
attribute
attribute
_field_defaults = {}
_fields = ('text', 'expect_value')
attribute
attribute
_fields = ('text', 'expect_value')
classmethod _make(iterable)
classmethod method[source]
classmethod method[source]
classmethod _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.

Examples

>>> from tmuxp.cli._formatter import HelpTheme
>>> theme = HelpTheme.from_colors(None)
>>> theme.reset
''
prog: str
attribute
attribute
prog: str

Alias for field number 0

action: str
attribute
attribute
action: str

Alias for field number 1

long_option: str
attribute
attribute
long_option: str

Alias for field number 2

short_option: str
attribute
attribute
short_option: str

Alias for field number 3

label: str
attribute
attribute
label: str

Alias for field number 4

heading: str
attribute
attribute
heading: str

Alias for field number 5

reset: str
attribute
attribute
reset: str

Alias for field number 6

classmethod from_colors(colors)
classmethod method[source]
classmethod method[source]
classmethod from_colors(colors)

Create theme from 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
''
static __new__(_cls, prog, action, long_option, short_option, label, heading, reset)
staticmethod method
staticmethod method
static __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.

_field_defaults = {}
attribute
attribute
_field_defaults = {}
_fields = ('prog', 'action', 'long_option', 'short_option', 'label', 'heading', 'reset')
attribute
attribute
_fields = ('prog', 'action', 'long_option', 'short_option', 'label', 'heading', 'reset')
classmethod _make(iterable)
classmethod method[source]
classmethod method[source]
classmethod _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.

Parameters:

colors (Colors | None) – Colors instance for styling. If None, uses ColorMode.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 = formatter_cls("test")
>>> formatter._theme is not None
True

With colors disabled:

>>> colors = Colors(ColorMode.NEVER)
>>> formatter_cls = create_themed_formatter(colors)
>>> formatter = formatter_cls("test")
>>> formatter._theme is None
True