osrf_pycommon.terminal_color.impl module

osrf_pycommon.terminal_color.impl.ansi(key)

Returns the escape sequence for a given ansi color key.

osrf_pycommon.terminal_color.impl.disable_ansi_color_substitution_globally()

Causes format_color() to replace color annotations with empty strings.

It also affects ansi().

This is not the case by default, so if you want to make all substitutions given to either function mentioned above return empty strings then call this function.

The default behavior can be restored by calling enable_ansi_color_substitution_globally().

osrf_pycommon.terminal_color.impl.enable_ansi_color_substitution_globally()

Causes format_color() to replace color annotations with ansi esacpe sequences.

It also affects ansi().

This is the case by default, so there is no need to call this everytime.

If you have previously caused all substitutions to evaluate to an empty string by calling disable_ansi_color_substitution_globally(), then you can restore the escape sequences for substitutions by calling this function.

osrf_pycommon.terminal_color.impl.format_color(msg)

Replaces color annotations with ansi escape sequences.

See this module’s documentation for the list of available substitutions.

If disable_ansi_color_substitution_globally() has been called then all color annotations will be replaced by empty strings.

Also, on Windows all color annotations will be replaced with empty strings. If you want colorization on Windows, you must pass annotated strings to print_color().

Parameters:

msg (str) – string message to be colorized

Returns:

colorized string

Return type:

str

osrf_pycommon.terminal_color.impl.get_ansi_dict()

Returns a copy of the dictionary of keys and ansi escape sequences.

osrf_pycommon.terminal_color.impl.print_ansi_color_win32(*args, **kwargs)

Prints color string containing ansi escape sequences to console in Windows.

If called on a non-Windows system, a NotImplementedError occurs.

Does not respect disable_ansi_color_substitution_globally().

Does not substitute color annotations like @{r} or @!, the string must already contain the \033[1m style ansi escape sequences.

Works by splitting each argument up by ansi escape sequence, printing the text between the sequences, and doing the corresponding win32 action for each ansi sequence encountered.

osrf_pycommon.terminal_color.impl.print_color(*args, **kwargs)

Colorizes and prints with an implicit ansi reset at the end

Calls format_color() on each positional argument and then sends all positional and keyword arguments to print.

If the end keyword argument is not present then the default end value ansi('reset') + '\n' is used and passed to print.

os.linesep is used to determine the actual value for \n.

Therefore, if you use the end keyword argument be sure to include an ansi reset escape sequence if necessary.

On Windows the substituted arguments and keyword arguments are passed to print_ansi_color_win32() instead of just print.

osrf_pycommon.terminal_color.impl.sanitize(msg)

Sanitizes the given string to prevent format_color() from substituting content.

For example, when the string 'Email: {user}@{org}' is passed to format_color() the @{org} will be incorrectly recognized as a colorization annotation and it will fail to substitute with a KeyError: org.

In order to prevent this, you can first “sanitize” the string, add color annotations, and then pass the whole string to format_color().

If you give this function the string 'Email: {user}@{org}', then it will return 'Email: {{user}}@@{{org}}'. Then if you pass that to format_color() it will return 'Email: {user}@{org}'. In this way format_color() is the reverse of this function and so it is safe to call this function on any incoming data if it will eventually be passed to format_color().

In addition to expanding { => {{, } => }}, and @ => @@, this function will also replace any instances of @!, @/, @_, and @| with @{atexclamation}, @{atfwdslash}, @{atunderscore}, and @{atbar} respectively. And then there are corresponding keys in the ansi dict to convert them back.

For example, if you pass the string '|@ Notice @|' to this function it will return '|@@ Notice @{atbar}'. And since ansi('atbar') always returns @|, even when disable_ansi_color_substitution_globally() has been called, the result of passing that string to format_color() will be '|@ Notice @|' again.

There are two main strategies for constructing strings which use both the Python str.format() function and the colorization annotations.

One way is to just build each piece and concatenate the result:

print_color("@{r}", "{error}".format(error=error_str))
# Or using print (remember to include an ansi reset)
print(format_color("@{r}" + "{error}".format(error=error_str) + "@|"))

Another way is to use this function on the format string, concatenate to the annotations, pass the whole string to format_color(), and then format the whole thing:

print(format_color("@{r}" + sanitize("{error}") + "@|")
      .format(error=error_str))

However, the most common use for this function is to sanitize incoming strings which may have unknown content:

def my_func(user_content):
    print_color("@{y}" + sanitize(user_content))

This function is not intended to be used on strings with color annotations.

Parameters:

msg (str) – string message to be sanitized

Returns:

sanitized string

Return type:

str

osrf_pycommon.terminal_color.impl.test_colors(file=None)

Prints a color testing block using print_color()