Colorize Terminal Output in Python

Advertisement

Advertisement

Submitted by nanodano on Sun, 10/28/2018 - 22:31

Overview

Introduction

This tutorial covers how to use standard ANSI escape codes to colorize and style terminal output. We'll cover the basics of escape characters, using them to clear the screen and set foreground and background colors, and how to get them working in Windows using the colorama package.

If you write an application that supports color, keep in mind that not every terminal supports the color characters. Consider adding an option with your program to toggle color output on or off, otherwise people who have no color will see all the escape characters and the output will be ugly and hard to read.

In Windows 10, some color escape codes are supported without any special configuration. Read more at MSDN Console Virtual Terminal Sequences. It is not full curses support but some colors and cursor control abilities work.

Color text with ANSI escape characters

You can manually colorizing output by using escape characters. This is quite tedious and ugly, but possible. The big catch here is that these ANSI escape characters don't work in Windows. Don't worry though, we'll cover how to get them working in Windows below!. This will work on ANSI consoles like Linux shells, but not in Windows. Windows has their own escape characters. Here are some simple examples to show how the escape characters can be used with the print() function in Python.

# In Python, print red text using ANSI escape codes
# Doesn't work well in Windows though
print('\033[2J')  # Clear screen
print('\033[31m' + 'Hello' + '\033[0m')  # Red text

The \033 is how the escape character is represented in Python, which is then followed by a special code. The 033 is the octal value of the escape character code, 27. Sometimes it is represented as \x1b which is the hexadecimal equivalent for 27. In the bash shell, you might see the escape character represented by \e in codes that look like \e[31m. You may have seen these codes if you have ever tried to customize your PS1 prompt shell in bash. The \033 just designated that the values coming directly after it are special characters meant to be interpeted by the terminal. We typically pass color codes right after the escape character to change the color text being output, but there are also special characters to clear the screen or move the cursor.

The [31m part of \033[31m means "red foreground mode". All escape codes start with a an open bracket [ but not all of them end with an m. For example, [2J is the code to clear the screen and [3D will move the cursor back 3 characters. The m in [31m is because we are toggling graphics mode 31 (red foreground).

You can try these yourself and see how they works. Your results may vary. Since this is unreliable, we'll look at the colorama Python package which has a bunch of shortcuts for these hard-to-remember codes, and also enables these ANSI codes on Windows, making colorized code more portable.

Install colorama package

The colorama package will abstract away the Windows specific stuff and let you use regular ANSI color codes. It also provides convenient Python utilities for coloring text in an easy way that works across all platforms.

pyhon -m pip install colorama

Clear the screen

Once you initialize colorama you can start passing ANSI codes. You can manually print out the escape character \033 followed by the code for clear screen which is [2J and it will clear the screen. Colorama also provides a convenience function that will return the value you need to print to clear the screen. The example below shows both options.

import colorama

colorama.init()

# Print the clear screen code '\033[2J'
print('\033[2J')

# Or use the colorama provided function which
# returns an equivalent value '\x1b[2J'
print(colorama.ansi.clear_screen())

Change text style

After installing the colorama package, you can use it inside your Python programs like this:

import colorama

# If using Windows, init() will cause anything sent to stdout or stderr
# will have ANSI color codes converted to the Windows versions. Hooray!
# If you are already using an ANSI compliant shell, it won't do anything
colorama.init()

# Now regular ANSI codes should work, even in Windows
CLEAR_SCREEN = '\033[2J'
RED = '\033[31m'   # mode 31 = red forground
RESET = '\033[0m'  # mode 0  = reset
print(CLEAR_SCREEN + RED + 'Welcome!' + RESET)

The example above shows how to import colorama and initialize it. Initializing it will add a filter on stdout and stderr which causes any ANSI escape characters be converted to the Windows equivalent. This is neat because it will also work if you have aother packages or code that outputs typical ANSI color characters. The author of colorama mentions termcolor as an option that you can use in tandem with colorama.

Colorama does provide a better way to output colors though. You don't need to use the ugly escape characters manually. It has some named values for the colors and styles. The example below shows how to use the friendly shortcuts provided by colorama to change text style.

import colorama
from colorama import Fore, Back, Style
colorama.init()

# Set the color semi-permanently
print(Fore.CYAN)
print("Text will continue to be cyan")
print("until it is reset or changed")
print(Style.RESET_ALL)

# Colorize a single line and then reset
print(Fore.RED + 'You can colorize a single line.' + Style.RESET_ALL)

# Colorize a single word in the output
print('Or a single ' + Back.GREEN + 'words' + Style.RESET_ALL + ' can be highlighted')

# Combine foreground and background color
print(Fore.BLUE + Back.WHITE)
print('Foreground, background, and styles can be combined')
print("==========            ")

print(Style.RESET_ALL)
print('If unsure, reset everything back to normal.')

For a full list of foreground, background, and style options, refer to the official colorama GitHub page. Here's a quick list:

Fore: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET.
Back: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET.
Style: DIM, NORMAL, BRIGHT, RESET_ALL

Note that not all of them may be supported by all terminals. For example Windows does not support dim. For a full list of the codes, check out ANSI escape code list. On that Wikipedia page it is the "SGR (Select Graphic Rendition) parameters" section that I linked to. Code 0 should look familiar, it is the reset value. 30-37 will set a foreground color, 40-47 will set background color. Not every code is supported by every terminal, and note every code is handled by colorama's Windows converter.

Turn on auto-reset

If you don't want to print Style.RESET_ALL all the time, you can have it reset automatically after each print statement. 

import colorama
from colorama import Fore, Back

colorama.init(autoreset=True)

# Automatically adds a Style.RESET_ALL after each print statement
print(Fore.RED + 'Red foreground text')
print(Back.RED + 'Red background text')
print("Some plain text")

Colorama alternatives

Since colorama just takes advantage of ANSI standard escape characters, any other library that makes use of this standard can be used. These are not strictly replacements or alternatives because many of them can be used in tandem with colorama since colorama's main purpose is to convert the ANSI codes in to proper Window's equivalents enabling all the typical terminal control utilities. Here are some links to other resources you might find useful:

Conclusion

After reading this you should understand how basic ANSI escape codes are used to change the color of text in the terminal. You should also know how to get it working in Windows. You should be able to clear the screen, change forground and background color, and reset the styles of text. To take it further, you can look in to the curses library which will allow you to control the screen even more. If you want to learn more about how the terminal works, you can check out this good PyCon talk: Thomas Ballinger - Terminal whispering - PyCon 2015.

Reference links

Advertisement

Advertisement