cmd2.ansi¶
Support for ANSI escape sequences which are used for things like applying style to text, setting the window title, and asynchronous alerts.
- cmd2.ansi.STYLE_NEVER = 'Never'¶
Constant for
cmd2.ansi.allow_style
to indicate ANSI style sequences should be removed from all output.
- cmd2.ansi.STYLE_TERMINAL = 'Terminal'¶
Constant for
cmd2.ansi.allow_style
to indicate ANSI style sequences should be removed if the output is not going to the terminal.
- cmd2.ansi.STYLE_ALWAYS = 'Always'¶
Constant for
cmd2.ansi.allow_style
to indicate ANSI style sequences should always be output.
- cmd2.ansi.allow_style = 'Terminal'¶
When using outside of a cmd2 app, set this variable to one of:
STYLE_NEVER
- remove ANSI style sequences from all outputSTYLE_TERMINAL
- remove ANSI style sequences if the output is not going to the terminalSTYLE_ALWAYS
- always output ANSI style sequences
to control the output of ANSI style sequences by methods in this module.
The default is
STYLE_TERMINAL
.
- class cmd2.ansi.ColorBase(value)¶
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
- classmethod colors() → List[str]¶
Return a list of color names.
- class cmd2.ansi.fg(value)¶
Enum class for foreground colors
- class cmd2.ansi.bg(value)¶
Enum class for background colors
- cmd2.ansi.FG_RESET = '\x1b[39m'¶
ANSI sequence to reset the foreground attributes
- cmd2.ansi.BG_RESET = '\x1b[49m'¶
ANSI sequence to reset the terminal background attributes
- cmd2.ansi.RESET_ALL = '\x1b[0m'¶
ANSI sequence to reset all terminal attributes
- cmd2.ansi.INTENSITY_BRIGHT = '\x1b[1m'¶
ANSI sequence to make the text bright
- cmd2.ansi.INTENSITY_DIM = '\x1b[2m'¶
ANSI sequence to make the text dim
- cmd2.ansi.INTENSITY_NORMAL = '\x1b[22m'¶
ANSI sequence to make the text normal
- cmd2.ansi.UNDERLINE_ENABLE = '\x1b[4m'¶
ANSI sequence to turn on underline
- cmd2.ansi.UNDERLINE_DISABLE = '\x1b[24m'¶
ANSI sequence to turn off underline
- 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_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.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.
- 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.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.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
- 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 – text to format (anything convertible to a str)
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_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
- 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.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.
- 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