cmd2.ansi
cmd2.ansi
Support for ANSI escape sequences which are used for things like applying style to text, setting the window title, and asynchronous alerts.
allow_style
module-attribute
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 like poutput()
, perror()
,
pwarning()
, etc.
The default is AllowStyle.TERMINAL
.
EIGHT_BIT_FG_RE
module-attribute
EIGHT_BIT_FG_RE = compile(f'{ESC}\[38;5;(?:1?[0-9]?[0-9]?|2[0-4][0-9]|25[0-5])m')
EIGHT_BIT_BG_RE
module-attribute
EIGHT_BIT_BG_RE = compile(f'{ESC}\[48;5;(?:1?[0-9]?[0-9]?|2[0-4][0-9]|25[0-5])m')
RGB_FG_RE
module-attribute
RGB_FG_RE = compile(f'{ESC}\[38;2(?:;(?:1?[0-9]?[0-9]?|2[0-4][0-9]|25[0-5])){3}m')
RGB_BG_RE
module-attribute
RGB_BG_RE = compile(f'{ESC}\[48;2(?:;(?:1?[0-9]?[0-9]?|2[0-4][0-9]|25[0-5])){3}m')
style_success
module-attribute
Partial function supplying arguments to cmd2.ansi.style which colors text to signify success
style_warning
module-attribute
style_warning = partial(style, fg=LIGHT_YELLOW)
Partial function supplying arguments to cmd2.ansi.style which colors text to signify a warning
style_error
module-attribute
Partial function supplying arguments to cmd2.ansi.style which colors text to signify an error
AllowStyle
AnsiSequence
Base class to create ANSI sequence strings
FgColor
BgColor
Cursor
Create ANSI sequences to alter the cursor position
UP
staticmethod
DOWN
staticmethod
FORWARD
staticmethod
BACK
staticmethod
TextStyle
Fg
Bases: FgColor
, Enum
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.
Bg
Bases: BgColor
, Enum
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.
EightBitFg
Bases: FgColor
, Enum
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.
EightBitBg
Bases: BgColor
, Enum
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.
RgbFg
Bases: FgColor
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.
RgbFg initializer
PARAMETER | DESCRIPTION |
---|---|
r
|
integer from 0-255 for the red component of the color
TYPE:
|
g
|
integer from 0-255 for the green component of the color
TYPE:
|
b
|
integer from 0-255 for the blue component of the color
TYPE:
|
RAISES | DESCRIPTION |
---|---|
ValueError
|
if r, g, or b is not in the range 0-255 |
Source code in cmd2/ansi.py
RgbBg
Bases: BgColor
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.
RgbBg initializer
PARAMETER | DESCRIPTION |
---|---|
r
|
integer from 0-255 for the red component of the color
TYPE:
|
g
|
integer from 0-255 for the green component of the color
TYPE:
|
b
|
integer from 0-255 for the blue component of the color
TYPE:
|
RAISES | DESCRIPTION |
---|---|
ValueError
|
if r, g, or b is not in the range 0-255 |
Source code in cmd2/ansi.py
strip_style
Strip ANSI style sequences from a string.
PARAMETER | DESCRIPTION |
---|---|
text
|
string which may contain ANSI style sequences
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
the same string with any ANSI style sequences removed |
style_aware_wcswidth
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.
PARAMETER | DESCRIPTION |
---|---|
text
|
the string being measured
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
int
|
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. |
Source code in cmd2/ansi.py
widest_line
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.
PARAMETER | DESCRIPTION |
---|---|
text
|
the string being measured
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
int
|
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. |
Source code in cmd2/ansi.py
style_aware_write
Write a string to a fileobject and strip its ANSI style sequences if required by allow_style setting
PARAMETER | DESCRIPTION |
---|---|
fileobj
|
the file object being written to
TYPE:
|
msg
|
the string being written
TYPE:
|
Source code in cmd2/ansi.py
set_title
Generate a string that, when printed, sets a terminal's window title.
PARAMETER | DESCRIPTION |
---|---|
title
|
new title for the window
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
the set title string |
clear_screen
Generate a string that, when printed, clears a terminal screen based on value of clear_type.
PARAMETER | DESCRIPTION |
---|---|
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
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
the clear screen string |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if clear_type is not a valid value |
Source code in cmd2/ansi.py
clear_line
Generate a string that, when printed, clears a line based on value of clear_type.
PARAMETER | DESCRIPTION |
---|---|
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
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
the clear line string |
RAISES | DESCRIPTION |
---|---|
ValueError
|
if clear_type is not a valid value |
Source code in cmd2/ansi.py
style
style(value, *, fg=None, bg=None, bold=None, dim=None, italic=None, overline=None, strikethrough=None, underline=None)
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.
PARAMETER | DESCRIPTION |
---|---|
value
|
object whose text is to be styled
TYPE:
|
fg
|
foreground color provided as any subclass of FgColor (e.g. Fg, EightBitFg, RgbFg) Defaults to no color.
TYPE:
|
bg
|
foreground color provided as any subclass of BgColor (e.g. Bg, EightBitBg, RgbBg) Defaults to no color.
TYPE:
|
bold
|
apply the bold style if True. Defaults to False.
TYPE:
|
dim
|
apply the dim style if True. Defaults to False.
TYPE:
|
italic
|
apply the italic style if True. Defaults to False.
TYPE:
|
overline
|
apply the overline style if True. Defaults to False.
TYPE:
|
strikethrough
|
apply the strikethrough style if True. Defaults to False.
TYPE:
|
underline
|
apply the underline style if True. Defaults to False.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
the stylized string |
RAISES | DESCRIPTION |
---|---|
TypeError
|
if fg isn't None or a subclass of FgColor |
TypeError
|
if bg isn't None or a subclass of BgColor |
Source code in cmd2/ansi.py
963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 |
|
async_alert_str
Calculate the desired string, including ANSI escape codes, for displaying an asynchronous alert message.
PARAMETER | DESCRIPTION |
---|---|
terminal_columns
|
terminal width (number of columns)
TYPE:
|
prompt
|
current onscreen prompt
TYPE:
|
line
|
current contents of the Readline line buffer
TYPE:
|
cursor_offset
|
the offset of the current cursor position within line
TYPE:
|
alert_msg
|
the message to display to the user
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
the correct string so that the alert message appears to the user to be printed above the current line. |