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)
-
static
-
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 sequencesAllowStyle.NEVER
- remove ANSI style sequences from all outputAllowStyle.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 likepoutput()
,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.
-
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
-
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.