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.AllowStyle¶: Values for cmd2.ansi.allow_style

class cmd2.ansi.AnsiSequence¶: Base class to create ANSI sequence strings

class cmd2.ansi.Bg¶: Create ANSI sequences for the 16 standard terminal background text colors. A terminal’s color settings affect how these colors appear. To reset any background color, use Bg.RESET.

class cmd2.ansi.BgColor¶: Base class for ANSI Sequences which set background text color

class cmd2.ansi.Cursor¶

Create ANSI sequences to alter the cursor position

static BACK(count: int = 1) → str¶: Move the cursor back a specified amount of lines (Defaults to 1)

static DOWN(count: int = 1) → str¶: Move the cursor down a specified amount of lines (Defaults to 1)

static FORWARD(count: int = 1) → str¶: Move the cursor forward a specified amount of lines (Defaults to 1)

static SET_POS(x: int, y: int) → str¶: Set the cursor position to coordinates which are 1-based

static UP(count: int = 1) → str¶: Move the cursor up a specified amount of lines (Defaults to 1)

class cmd2.ansi.EightBitBg¶: Create ANSI sequences for 8-bit terminal background text colors. Most terminals support 8-bit/256-color mode. The first 16 colors correspond to the 16 colors from Bg and behave the same way. To reset any background color, including 8-bit, use Bg.RESET.

class cmd2.ansi.EightBitFg¶: Create ANSI sequences for 8-bit terminal foreground text colors. Most terminals support 8-bit/256-color mode. The first 16 colors correspond to the 16 colors from Fg and behave the same way. To reset any foreground color, including 8-bit, use Fg.RESET.

class cmd2.ansi.Fg¶: Create ANSI sequences for the 16 standard terminal foreground text colors. A terminal’s color settings affect how these colors appear. To reset any foreground color, use Fg.RESET.

class cmd2.ansi.FgColor¶: Base class for ANSI Sequences which set foreground text color

class cmd2.ansi.RgbBg(r: int, g: int, b: int)¶: Create ANSI sequences for 24-bit (RGB) terminal background text colors. The terminal must support 24-bit/true-color mode. To reset any background color, including 24-bit, use Bg.RESET.

class cmd2.ansi.RgbFg(r: int, g: int, b: int)¶: Create ANSI sequences for 24-bit (RGB) terminal foreground text colors. The terminal must support 24-bit/true-color mode. To reset any foreground color, including 24-bit, use Fg.RESET.

class cmd2.ansi.TextStyle¶: Create text style ANSI sequences

cmd2.ansi.allow_style = 'Terminal'¶

When using outside of a cmd2 app, set this variable to one of:

AllowStyle.ALWAYS - always output ANSI style sequences
AllowStyle.NEVER - remove ANSI style sequences from all output
AllowStyle.TERMINAL - remove ANSI style sequences if the output is not going to the terminal

to control how ANSI style sequences are handled by style_aware_write().

style_aware_write() is called by cmd2 methods like poutput(), perror(), pwarning(), etc.

The default is AllowStyle.TERMINAL.

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¶: Deprecated Enum class for background colors. Use Bg instead.

cmd2.ansi.clear_line(clear_type: int = 2) → str¶

Generate a string that, when printed, clears a line based on value of clear_type.

Parameters:	clear_type – integer which specifies how to clear the line (Defaults to 2) Possible values: 0 - clear from cursor to the end of the line 1 - clear from cursor to beginning of the line 2 - clear entire line
Returns:	the clear line string
Raises:	ValueError if clear_type is not a valid value

cmd2.ansi.clear_screen(clear_type: int = 2) → str¶

Generate a string that, when printed, clears a terminal screen based on value of clear_type.

Parameters:	clear_type – integer which specifies how to clear the screen (Defaults to 2) Possible values: 0 - clear from cursor to end of screen 1 - clear from cursor to beginning of the screen 2 - clear entire screen 3 - clear entire screen and delete all lines saved in the scrollback buffer
Returns:	the clear screen string
Raises:	ValueError if clear_type is not a valid value

class cmd2.ansi.fg¶: Deprecated Enum class for foreground colors. Use Fg instead.

cmd2.ansi.set_title(title: str) → str¶

Generate a string that, when printed, sets a terminal’s window title.

Parameters:	title – new title for the window
Returns:	the set title string

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(value: Any, *, fg: Optional[cmd2.ansi.FgColor] = None, bg: Optional[cmd2.ansi.BgColor] = None, bold: Optional[bool] = None, dim: Optional[bool] = None, italic: Optional[bool] = None, overline: Optional[bool] = None, strikethrough: Optional[bool] = None, underline: Optional[bool] = None) → 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:	value – object whose text is to be styled fg – foreground color provided as any subclass of FgColor (e.g. Fg, EightBitFg, RgbFg) Defaults to no color. bg – foreground color provided as any subclass of BgColor (e.g. Bg, EightBitBg, RgbBg) Defaults to no color. bold – apply the bold style if True. Defaults to False. dim – apply the dim style if True. Defaults to False. italic – apply the italic style if True. Defaults to False. overline – apply the overline style if True. Defaults to False. strikethrough – apply the strikethrough style if True. Defaults to False. underline – apply the underline style if True. Defaults to False.
Raises:	TypeError if fg isn’t None or a subclass of FgColor
Raises:	TypeError if bg isn’t None or a subclass of BgColor
Returns:	the stylized string

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

Wrap wcswidth to make it compatible with strings that contain ANSI style sequences. This is intended for single line strings. If text contains a newline, this function will return -1. For multiline strings, call widest_line() instead.

Parameters:	text – the string being measured
Returns:	The width of the string when printed to the terminal if no errors occur. If text contains characters with no absolute width (i.e. tabs), then this function returns -1. Replace tabs with spaces before calling this.

cmd2.ansi.style_aware_write(fileobj: IO[str], 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(value: Any, *, fg: Optional[cmd2.ansi.FgColor] = <Fg.LIGHT_RED: 91>, bg: Optional[cmd2.ansi.BgColor] = None, bold: Optional[bool] = None, dim: Optional[bool] = None, italic: Optional[bool] = None, overline: Optional[bool] = None, strikethrough: Optional[bool] = None, underline: Optional[bool] = None) → str¶: Partial function supplying arguments to cmd2.ansi.style() which colors text to signify an error

cmd2.ansi.style_success(value: Any, *, fg: Optional[cmd2.ansi.FgColor] = <Fg.GREEN: 32>, bg: Optional[cmd2.ansi.BgColor] = None, bold: Optional[bool] = None, dim: Optional[bool] = None, italic: Optional[bool] = None, overline: Optional[bool] = None, strikethrough: Optional[bool] = None, underline: Optional[bool] = None) → str¶: Partial function supplying arguments to cmd2.ansi.style() which colors text to signify success

cmd2.ansi.style_warning(value: Any, *, fg: Optional[cmd2.ansi.FgColor] = <Fg.LIGHT_YELLOW: 93>, bg: Optional[cmd2.ansi.BgColor] = None, bold: Optional[bool] = None, dim: Optional[bool] = None, italic: Optional[bool] = None, overline: Optional[bool] = None, strikethrough: Optional[bool] = None, underline: Optional[bool] = None) → str¶: Partial function supplying arguments to cmd2.ansi.style() which colors text to signify a warning

cmd2.ansi.widest_line(text: str) → int¶

Return the width of the widest line in a multiline string. This wraps style_aware_wcswidth() so it handles ANSI style sequences and has the same restrictions on non-printable characters.

Parameters:	text – the string being measured
Returns:	The width of the string when printed to the terminal if no errors occur. If text contains characters with no absolute width (i.e. tabs), then this function returns -1. Replace tabs with spaces before calling this.