cmd2.ansi

Support for ANSI escape sequences which are used for things like applying style to text, setting the window title, and asynchronous alerts.

class cmd2.ansi.ColorBase

Base class used for defining color enums. See fg and bg classes for examples.

Child classes should define enums in the follow structure:
key: color name (e.g. black) value: anything that when cast to a string returns an ANSI sequence
cmd2.ansi.async_alert_str(*, terminal_columns: int, prompt: str, line: str, cursor_offset: int, alert_msg: str) → str

Calculate the desired string, including ANSI escape codes, for displaying an asynchronous alert message.

Parameters:
  • terminal_columns – terminal width (number of columns)
  • prompt – prompt that is displayed on the current line
  • line – current contents of the Readline line buffer
  • cursor_offset – the offset of the current cursor position within line
  • alert_msg – the message to display to the user
Returns:

the correct string so that the alert message appears to the user to be printed above the current line.

class cmd2.ansi.bg

Enum class for background colors

cmd2.ansi.bg_lookup(bg_name: Union[str, cmd2.ansi.bg]) → str

Look up ANSI escape codes based on background color name.

Parameters:bg_name – background color name or enum to look up ANSI escape code(s) for
Returns:ANSI escape code(s) associated with this color
Raises:ValueError – if the color cannot be found
class cmd2.ansi.fg

Enum class for foreground colors

cmd2.ansi.fg_lookup(fg_name: Union[str, cmd2.ansi.fg]) → str

Look up ANSI escape codes based on foreground color name.

Parameters:fg_name – foreground color name or enum to look up ANSI escape code(s) for
Returns:ANSI escape code(s) associated with this color
Raises:ValueError – if the color cannot be found
cmd2.ansi.set_title_str(title: str) → str

Get the required string, including ANSI escape codes, for setting window title for the terminal.

Parameters:title – new title for the window
Returns:string to write to sys.stderr in order to set the window title to the desired test
cmd2.ansi.strip_style(text: str) → str

Strip ANSI style sequences from a string.

Parameters:text – string which may contain ANSI style sequences
Returns:the same string with any ANSI style sequences removed
cmd2.ansi.style(text: Any, *, fg: Union[str, cmd2.ansi.fg] = '', bg: Union[str, cmd2.ansi.bg] = '', bold: bool = False, dim: bool = False, underline: bool = False) → str

Apply ANSI colors and/or styles to a string and return it. The styling is self contained which means that at the end of the string reset code(s) are issued to undo whatever styling was done at the beginning.

Parameters:
  • text – Any object compatible with str.format()
  • fg – foreground color. Relies on fg_lookup() to retrieve ANSI escape based on name or enum. Defaults to no color.
  • bg – background color. Relies on bg_lookup() to retrieve ANSI escape based on name or enum. Defaults to no color.
  • bold – apply the bold style if True. Can be combined with dim. Defaults to False.
  • dim – apply the dim style if True. Can be combined with bold. Defaults to False.
  • underline – apply the underline style if True. Defaults to False.
Returns:

the stylized string

cmd2.ansi.style_aware_wcswidth(text: str) → int

Wrap wcswidth to make it compatible with strings that contains ANSI style sequences

Parameters:text – the string being measured
Returns:the width of the string when printed to the terminal
cmd2.ansi.style_aware_write(fileobj: IO, msg: str) → None

Write a string to a fileobject and strip its ANSI style sequences if required by allow_style setting

Parameters:
  • fileobj – the file object being written to
  • msg – the string being written
cmd2.ansi.style_error(text: Any, *, fg: Union[str, cmd2.ansi.fg] = <fg.bright_red: '\x1b[91m'>, bg: Union[str, cmd2.ansi.bg] = '', bold: bool = False, dim: bool = False, underline: bool = False) → str

Partial function supplying arguments to cmd2.ansi.style() which colors text to signify an error

cmd2.ansi.style_success(text: Any, *, fg: Union[str, cmd2.ansi.fg] = <fg.green: '\x1b[32m'>, bg: Union[str, cmd2.ansi.bg] = '', bold: bool = False, dim: bool = False, underline: bool = False) → str

Partial function supplying arguments to cmd2.ansi.style() which colors text to signify success

cmd2.ansi.style_warning(text: Any, *, fg: Union[str, cmd2.ansi.fg] = <fg.bright_yellow: '\x1b[93m'>, bg: Union[str, cmd2.ansi.bg] = '', bold: bool = False, dim: bool = False, underline: bool = False) → str

Partial function supplying arguments to cmd2.ansi.style() which colors text to signify a warning