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