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.
dump_predefined_color_styles()	Dump all predefined Colors in every Styles to the console.
log_stage(stage, *[, fill_char, pad, l_pad, …])	Print a terminal width block with stage message in the middle.

class Ansi

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

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.

classmethod all_colors()

Return a tuple of all string colors available (used in tests).

class Styles

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.

classmethod all_styles()

Return a tuple of all style strings available (used in tests).

colorize(message, *, color, style='')

Return message colorized with specified style.

Warning

For both the color and style parameters, these are not supposed to have the m after. For example, a color="32m" is invalid, it should just be "32". Similarly, a style="1m" is invalid, it should just be "1".

Parameters

• message (str) – The message to insert an Ansi.Escape sequence with the specified color before, and Ansi.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 example Styles.BoldUnderline. Semicolons should be on the interior separating each style.

Returns

The original message with the specified color escape sequence.

Return type

str

dump_predefined_color_styles()

Dump all predefined Colors in every Styles to the console.

log_stage(stage, *, fill_char='=', pad=' ', l_pad=None, r_pad=None, color='32', style='1', width=None, **kwargs)

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. Specify width if fixed width is desired.

Note

If the length of the stage parameter is too long (cannot pad with at least one fill_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 be None. 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 and r_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 from pad parameter). See examples in r_pad below.

• r_pad (str or None) –

  A padding to insert after the stage (on the right). Default: None (implies use value from pad 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 with color=None to disable.

• style (str) – The ANSI style specification to use with colorize(). If no coloring is desired, leave this parameter as is and specify color=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 the print(). E.g., to specify file=some_log_file_object or file=sys.stderr rather than printing to sys.stdout.

Tests

Tests for the ci_exec.colorize module.

test_all_colors()

Validate Colors.all_colors returns all available colors.

test_all_styles()

Validate Styles.all_styles returns all available styles.

test_colorize(color, style)

Test colorize() colors as expected for each platform.

test_dump_predefined_color_styles(capsys)

Validate dump_predefined_color_styles() dumps all.

test_log_stage(capsys, stage, fill_char_, pad_, l_pad_, r_pad_, color_, style_, width_)

Test log_stage() prints the expected messages.