tcolors

Simple and easily-disableable library to make your life easier when working with ANSI colors in the terminal.

Without dozens of options, methods and combinations. Coloring the terminal should be a simple task.

Supports basic colors, bright colors, 256 ANSI colors, true colors and most of the ANSI text modifiers.

Installation

Install tcolors by using pip:

$ pip install tcolors

Motivation

There are dozens, if not hundreds, of libraries that color the terminal with ANSI escape sequences, why develop another one?

Mainly because I always miss a feature in almost all existing libraries: the option to enable or disable the colored automacally.

This is especially useful when developing command line applications whose output may be piped into another. In such cases it is quite practical to have a flag to globally disable coloring (--no-colors for example) and make it easier for downstream applications that don't have to deal with data polluted by escape sequences.

Usage

Colors

tcolors can color text with different color palettes. Take into account that not all terminal emulators support all of them.

Basic 3-bit colors

Bright colors

Modifiers

256 colors

Where {N} can be any number from 0 to 255.

True colors

There are no built-in colors for the more than 16M of colors of the true color palette, but you can create your own colors just by creating a new instance of TrueColor or BgTrueColor

from tcolors import TrueColor, BgTrueColor

# Define colors either as hex strings (normal or short) or as rgb values
BLUE = TrueColor('#1F2041')
PURPLE = TrueColor('#437')
GREEN = TrueColor(65, 123, 90)
BG_COLOR = BgTrueColor(r=63, g=123, b=90)

Colorize text

You can add color in two ways:

• colorize: given a string it return a new string with the color escape sequences.
• cprint: print applying colors to the printed text.

cprint has the same signature as the built-in print function with an extra keyword argument style to define the style to apply.

from tcolors import Color, Mod, colorize, cprint

colorize('Text with colors', Color.RED)
cprint('Print with color', style=Mod.BOLD)

Both methods adds the reset modifier at the end automatically.

In fact you can concatenate styles (all colors and modifiers are instances of the Style class) to any string directly. Just remember that in these cases it is necessary to put the reset modifier manually.

print(Color.RED + 'Colored text' + Mod.RESET)
print(Color.RED, 'Colored text', Mod.RESET, sep='')

str1 = 'This is a {}blue{} text'.format(Color.BLUE, Mod.RESET)
str2 = 'This is a %syellow%s text' % (Color.YELLOW + Mod.BOLD, Mod.RESET)
str3 = f'{Color.RED}{Mod.BOLD}This is a text in bold red{Mod.RESET}'

Mix styles together

It is possible to combine styles using the addition operator.

cprint('This is a warning', style=Color.RED + BgColor.YELLOW + Mod.BOLD + Mod.Italic)

If you plan to use the same combination frequently you can assign it to a variable:

title_style = Color.BLUE + Mod.UNDERLINE
cprint('Title 1', style=title_style)
colorize('Another title', style=title_style)

Configuration

You can configure tcolors to enable or disable the colored globally.

If it is disabled all calls to colorize or cprint won't color the text.

from tcolors import configure_colors

configure_colors(enable_colors=False)

You can also define a default style that will be added automatically in all calls to colorize or cprint

from tcolors import configure_colors, Mod

# Put everything in bold
configure_colors(default_style, Mod.BOLD)

cprint('Just an example...', style=Color.GREEN)  # It will be printed in green and bold
cprint('Only bold')

Colorizer class

If you need to colorize several things in a different way use custom instances of the Colorizer class.

from tcolors import Colorizer, Mod

colorizer1 = Colorizer(default_style=Mod.BOLD)
colorizer2 = Colorizer(default_style=Mod.ITALIC)

colorizer1.colorize('The colorizer1 instance always prints text in bold', style=Color.BLUE)
colorizer2.colorize('While colorizer2 always prints in italic', style=Color.YELLOW)

As you can see the behaviour is the same as in the colorize and cprint functions. That is because tcolors uses an instance of the Colorizer class internally and exports those methods. Combine custom instances with the internal instance as you will.

If you want to use some default style only in a certain piece of code you can use Colorizer as a context manager:

from tcolors import Colorizer

with Colorizer(default_style=Color.GREEN) as c:
    c.cprint('Inside the context manager')

Examples

You can find more practical examples in the examples directoty.