ci_exec.colorize¶
Various utilities for colorizing terminal output.
Ansi
()Wrapper class for defining the escape character and clear sequence.
Colors
()The core ANSI color codes.
Styles
()A non-exhaustive list of ANSI style formats.
colorize
(message, *, color[, style])Return
message
colorized with specified style.
log_stage
(stage, *[, fill_char, pad, l_pad, …])Print a terminal width block with
stage
message in the middle.
- class Ansi[source]¶
Wrapper class for defining the escape character and clear sequence.
- Escape = '\x1b['¶
The opening escape sequence to use before inserting color / style.
- Clear = '\x1b[0m'¶
Convenience definition used to clear ANSI formatting.
- class Colors[source]¶
The core ANSI color codes.
- Black = '30'¶
The black ANSI color.
- Red = '31'¶
The red ANSI color.
- Green = '32'¶
The green ANSI color.
- Yellow = '33'¶
The yellow ANSI color.
- Blue = '34'¶
The blue ANSI color.
- Magenta = '35'¶
The magenta ANSI color.
- Cyan = '36'¶
The cyan ANSI color.
- White = '37'¶
The white ANSI color.
- class Styles[source]¶
A non-exhaustive list of ANSI style formats.
The styles included here are reliable across many terminals, more exotic styles such as ‘Blinking’ are not included as they often are not supported.
- Regular = ''¶
The regular ANSI format.
- Bold = '1'¶
The bold ANSI format.
- Dim = '2'¶
The dim ANSI format.
- Underline = '4'¶
The underline ANSI format.
- Inverted = '7'¶
The inverted ANSI format.
- BoldUnderline = '1;4'¶
Bold and underlined ANSI format.
- BoldInverted = '1;7'¶
Bold and inverted ANSI format.
- BoldUnderlineInverted = '1;4;7'¶
Bold, underlined, and inverted ANSI format.
- DimUnderline = '2;4'¶
Dim and underlined ANSI format.
- DimInverted = '2;7'¶
Dim and inverted ANSI format.
- DimUnderlineInverted = '2;4;7'¶
Dim, underlined, and inverted ANSI format.
- colorize(message, *, color, style='')[source]¶
Return
message
colorized with specified style.Warning
For both the
color
andstyle
parameters, these are not supposed to have them
after. For example, acolor="32m"
is invalid, it should just be"32"
. Similarly, astyle="1m"
is invalid, it should just be"1"
.- Parameters
message (str) – The message to insert an
Ansi.Escape
sequence with the specified color before, andAnsi.Clear
sequence after.color (str) – A string describing the ANSI color code to use, e.g.,
Colors.Red
.style (str) – The ANSI style to use. Default:
Styles.Regular
. Note that any number of ANSI style specifiers may be used, but it is assumed that the user has already formed the semicolon delineated list. For multiple ANSI specifiers, see for exampleStyles.BoldUnderline
. Semicolons should be on the interior separating each style.
- Returns
The original message with the specified color escape sequence.
- Return type
- log_stage(stage, *, fill_char='=', pad=' ', l_pad=None, r_pad=None, color='32', style='1', width=None, **kwargs)[source]¶
Print a terminal width block with
stage
message in the middle.Similar to the output of
tox
, a bar of=== {stage} ===
will be printed, adjusted to the width of the terminal. For example:>>> log_stage("CMake.Configure") ======================== CMake.Configure ========================
By default, this will be printed using ANSI bold green to make it stick out. If the terminal size cannot be obtained, a width of
80
is assumed. Specifywidth
if fixed width is desired.Note
If the length of the
stage
parameter is too long (cannot pad with at least onefill_char
and the specified padding both sides), the message with any coloring is printed as is. Prefer shorter stage messages when possible.- Parameters
stage (str) – The description of the build stage to print to the console. This is the only required argument.
fill_char (str) –
A length 1 string to use as the fill character. Default:
"="
.Warning
No checks on the input are performed, but any non-length-1 string will produce unattractive results.
pad (str) –
A padding to insert both before and after
stage
. Default:" "
. This value can be any length, but may not beNone
. If no padding is desired, use the empty string""
. Some examples:>>> log_stage("CMake.Configure") ============================= CMake.Configure ============================== >>> log_stage("CMake.Configure", fill_char="_", pad="") ______________________________CMake.Configure_______________________________
See also:
l_pad
andr_pad
if asymmetrical patterns are desired.l_pad (str or None) – A padding to insert before the
stage
(on the left). Default:None
(implies use value frompad
parameter). See examples inr_pad
below.A padding to insert after the
stage
(on the right). Default:None
(implies use value frompad
parameter). Some examples:>>> log_stage("CMake.Configure", fill_char="-", l_pad="+ ", r_pad=" +") ----------------------------+ CMake.Configure +----------------------------- # Without specifying r_pad, pad is used (default: " ") >>> log_stage("CMake.Configure", fill_char="-", l_pad="+ ") -----------------------------+ CMake.Configure -----------------------------
color (str or None) – The ANSI color code to use with
colorize()
. If no coloring is desired, call this function withcolor=None
to disable.style (str) – The ANSI style specification to use with
colorize()
. If no coloring is desired, leave this parameter as is and specifycolor=None
.width (int) –
If specified, the terminal size will be ignored and a message formatted to this positive valued parameter will be used instead. If the value is less than the length of the
stage
message, this parameter is ignored.Note
The specified width here does not necessarily equal the length of the string printed. The ANSI escape sequences added / trailing newline character will make the printed string longer than
width
, but the perceived width printed to the terminal will be correct.That is, if logging to a file, you may also desire to set
color=None
to remove the ANSI escape sequences / achieve the actual desired width.**kwargs – If provided,
**kwargs
is forwarded to theprint()
. E.g., to specifyfile=some_log_file_object
orfile=sys.stderr
rather than printing tosys.stdout
.
Tests¶
Tests for the ci_exec.colorize
module.
- test_all_colors()[source]¶
Validate
Colors.all_colors
returns all available colors.
- test_all_styles()[source]¶
Validate
Styles.all_styles
returns all available styles.
- test_colorize(color, style)[source]¶
Test
colorize()
colors as expected for each platform.
- test_dump_predefined_color_styles(capsys)[source]¶
Validate
dump_predefined_color_styles()
dumps all.
- test_log_stage(capsys, stage, fill_char_, pad_, l_pad_, r_pad_, color_, style_, width_)[source]¶
Test
log_stage()
prints the expected messages.