Tutorial

In addition to this tutorial, you can find examples in the examples folder.

Table of Contents:

1. Basic Usage
2. colorise.cprint
3. colorise.fprint
4. colorise.highlight
5. Attributes
6. Disabling Colors
7. More Colors!
8. Redefining Colors

Basic Usage

You may be interested to know how many colors your terminal can represent, which you can check using colorise.num_colors() which tries its best to guess the number of colors supported.

>>> import colorise
>>> colorise.num_colors()
256

Returned values may be 8, 16, 88, 256 and 16,777,216 (or 256^3 i.e. 24-bit true-color). You can also run the color_test.py script which prints all the capabilities of your console. To set the current color, you can use the colorise.set_color() function. For example,

>>> colorise.set_color(fg='red')
>>> print('Hello')
Hello

would set the current foreground color to red while

>>> colorise.set_color(fg='red', bg='green')
>>> print('Hello')
Hello

would set the current foreground color to red and the background color to green. Supported color names can be queried via colorise.color_names().

>>> colorise.color_names()
['black', 'red', 'green', 'yellow', 'blue', 'purple', 'magenta', 'cyan', 'gray', 'grey', 'lightgrey', 'lightgray', 'lightred', 'lightgreen', 'lightyellow', 'lightblue', 'lightpurple', 'lightcyan', 'white']

Use colorise.reset_color() to reset colors to their defaults.

>>> colorise.set_color(fg='red')
>>> print('Hello')
Hello
>>> colorise.reset_color()
>>> print('Hello')
Hello

colorise.cprint()

To print colored text, you can use the colorise.cprint() function.

>>> colorise.cprint('This has blue text and a green background', fg='blue', bg='green')
This has blue text and a green background

colorise.fprint()

The colorise.fprint() function provides more control than colorise.cprint() by letting you specify colors akin to Python 3’s string formatting.

>>> colorise.fprint('{fg=blue,bg=green}This has blue text and a green background')
This has blue text and a green background
>>> colorise.fprint('{fg=blue,bg=green}This has a green background and blue foreground but{fg=red} changes to red')
This has a green background and blue foreground but changes to red

The colorise.fprint() function provides the autoreset keyword argument to control if colors should be reset when a new color format is encountered. It is True by default.

>>> colorise.fprint('{fg=blue,bg=green}This has a green background and blue foreground but {fg=red}changes to red', autoreset=False)
This has a green background and blue foreground but changes to red
>>> colorise.fprint('{fg=blue,bg=green}This has a green background and blue foreground but {fg=red}changes to red', autoreset=True)
This has a green background and blue foreground but changes to red

Notice in the second example that both fore- and background colors are reset. It would correspond to the following example where we explicitly reset all colors and attributes with {reset} before setting the foreground color to red.

>>> colorise.fprint('{fg=blue,bg=green}This has a green background and blue foreground but{reset} {fg=red}changes to red', autoreset=False)
This has a green background and blue foreground but changes to red

colorise.highlight()

The colorise.highlight() function can be used to highlight ranges of characters within a string.

>>> colorise.highlight('This is a highlighted string', fg='red', indices=[0, 3, 5, 10, 13, 15, 16, 17, 22, 26, 27])
This is a highlighted string

Attributes

Text attributes are supported via the colorise.attributes.Attr class.

>>> from colorise import Attr
>>> colorise.cprint('Hello', fg='yellow', bg='purple', attributes=[Attr.Italic])
Hello
>>> colorise.cprint('Hello', fg='yellow', bg='purple', attributes=[Attr.Underline])
Hello

As for colorise.fprint(), you can specify the attributes directly in the format string.

>>> colorise.fprint('{fg=red,bg=green,italic}Hello')
Hello
>>> colorise.fprint('Hello {bold}Hello')
Hello Hello

Disabling Colors

It is sometimes useful to disable colors, for example in an application where colored output is controlled by a configuration file. The colorise.cprint(), colorise.fprint() and colorise.highlight() functions all support the enabled keyword argument for this purpose. Colors are enabled by default.

>>> colorise.cprint('Enabled!', fg='red', enabled=True)
Enabled!
>>> colorise.cprint('Disabled!', fg='red', enabled=False)
Disabled!

More Colors!

Besides named colors, you can also specify colors via color table index, RGB, hex, HLS and HSV. Color indices index into color tables commonly supported by different platforms.

>>> colorise.cprint('Via color indices', fg=198)
Via color indices
>>> colorise.cprint('Via hex', fg='#43fff3', bg='0xd60c74')
Via hex
>>> colorise.fprint('{fg=rgb(255;0;135)}Via RGB')
Via hex
>>> colorise.cprint('Via HSV', bg='hsv(250;84;82)')
Via HSV
>>> colorise.fprint('{bg=hls(0.11;0.412;0.762)}Via HLS')
Via HLS

Note

Even if your terminal does not support 88/256 index color tables or true-color, colorise will attempt to approximate the color by finding the closest one (via linear distance) and use that. For example, Windows usually supports only 16 colors but using colorise.cprint('Hello', fg='rgb(240;240;0)') on such a system will still give you a yellow color (assuming standard Windows console colors). Also see the mario sprites in the Screenshots section.

Redefining Colors

Some platforms allow you to redefine the standard colors but currently you can only redefine colors on Windows. As an example, let us redefine ‘green’ (color index 2).

>>> colorise.cprint('This should be green', fg='green')
This should be green
>>> colorise.redefine_colors({2: (255, 0, 255)})
>>> colorise.cprint('This should be green', fg='green')
This should be green

colorise.redefine_colors() takes a dictionary of colortable indices as keys and RGB tuples as values. Here, we redefine the entry in the colortable at the color index for green (2) to be magenta instead. This change persists until the color is redefined again or colorise is quit.

Note

Redefining colors does not currently work with ConEmu or on Mac and Linux systems.

Screenshots

Using colorise.cprint on Ubuntu

Using colorise.highlight on Windows

From left to right: True-color, 256 color and 16 color

FAQ

Q: Why do I get different results on different platforms?

Different platforms and terminals have support for different numbers of colors, attributes and colortables, and colorise tries it best to provide uniform results although platform differences makes this hard to do is 100%.

For example, depending on your console/terminal color support, you may have anything from 8-, 16-, 88-, 256-color support or even full-blown 24-bit colors available. If you request a 24-bit color but only have 256 colors, colorise will try its best to approximate the requested color according to the colortable of 256 colors available.

Q: I have custom colors set up in Windows, why are they not reflected in colorise?

You can set up custom console colors in Windows but in order to detect them you need at least [Windows Vista or Windows Server 2008](https://docs.microsoft.com/en-us/windows/console/getconsolescreenbufferinfoex). If you are working on a Windows version before that, your custom colors will not be properly reflected.

Q: How come I can use more than 16 colors in Windows?

Some versions of Windows 10 have 24-bit color support and can interpret ANSI escape codes, the latter which is commonly how colors are emitted on Mac and Linux systems.

Q: Why are the named colors on Windows incorrect?

On Windows, named colors are actually indices into a color table and not actual colors. Typing

>>> colorise.cprint('This should be yellow', fg='yellow')

will give you the color in the table correspoding to the ‘yellow’ index, not necessarily the color yellow. You can see the current colors by right-clicking the top bar of the console and selecting ‘Properties’ then selecting the ‘Colors’ tab. You can also set these programatically using colorise.redefine_colors().

Q: The blink and italic attributes do not appear to work in iTerm.app?

This has to be enabled manually in the settings in iTerm.app. Go into Preferences ­→ Profiles → Text and check the boxes for “Blinking text” and “Italic text”.

Q: Can I use colorise in different threads?

colorise is not thread-safe.

On nix systems, colorise emits ANSI escape codes to print colored output. Internally, this happens in a way where multiple threads would interfere although it should be possible to perform this in a thread-safe manner.

On Windows systems that do not support ANSI escape codes, multiple threads would also interfere with each other. On Windows systems that do support ANSI escape codes, it should still be possible to output colored text in a thread-safe manner.

Q: Why do the tests fail with ‘The handle is invalid.’ on Windows?

tox and pytest capture stdout and stderr which does not play well with Windows handle creation hence the error. You can tell pytest not to capture stdout and stderr and the tests should run but also show the output of all tests.

$ pytest -s tests

or

$ pytest --capture=no tests

Q: Was the colorise logo generated using colorise?

Yes :)

Changelog

Version numbers follow Semantic Versioning (i.e. <major>.<minor>.<patch>).

1.0.0

2019-12-17

Warning

Major update with breaking changes.

• [new] Support for 88/256 colortable indices, and RGB, HSV/HLS and hexadecimal color formats.
• [new] Support for virtual terminal processing on Windows.
• [new] Changed parser to use Python 3’s str.format syntax, e.g. <fg=red> becomes {fg=red}. Removed ColorManager classes since no state needs to be stored, replaced by a ColorFormatter class.
• [new] Better detection of terminal color capabilities.
• [new] If an unsupported color format is specified which the terminal does not support it (e.g. an RGB color in a 16 color terminal), colorise will automatically find color on your system that matches the desired color (via linear distance).
• [new] More thorough testing.
• [refactor] Reworked entire library.
• [refactor] Removed formatcolor and formatbyindex functions.
• [docs] Online documentation and updated comments.
• Changed license from MIT to BSD 3-clause.

0.1.4 (pre-release)

2014-06-11

• [Fix] Fixed a bug on nix platforms that caused background colors to break.

0.1.3 (pre-release)

2014-06-02

• [Fix] Fixed a bug where passing a string without any color formatting would print the empty string.

0.1.2 (pre-release)

2014-05-31

• [Fix] Fixed a bug in nix/ColorManager.py which caused set_color to malfunction.

0.1.1 (pre-release)

2014-05-24

• [Fix] Fixed a bug where putting a : or escaped > or < just before or after some color formatted text would raise a ColorSyntaxError.

0.1.0 (pre-release)

2014-05-14

• Initial version.

Tested Systems

This is a maintained list of systems that colorise has been tested on.

Something not working as expected with your terminal? Please report an issue or submit a pull request using the contribution guidelines.

Mac

Terminal	OS	Python version
iTerm 3.2.9	macOS Catalina v10.15.1	Python 3.7.4
Terminal.app 2.9.4 (421.1.1)	macOS Catalina v10.15.1	Python 3.7.4

Windows

Terminal	OS	Python version
Default Windows console	Windows 8.1 Pro, version 6.3, build 9600	Python 3.7.3
ConEmu	Windows 8.1 Pro, version 6.3, build 9600	Python 3.7.3

Linux

None yet.

colorise is a Python module for printing colored text in terminals.

You can install it via pip.

$ pip install colorise

Features

• Supports 8, 16, 88, 256 colors and true-color.
• Colors can be specified by name, index, hexadecimal, HLS, HSV or RGB formats.
• Custom color format akin to Python 3.0 string formatting.
• Automatically find the closest color based on the terminal’s capabilities.

Indices and tables

• Index
• Module Index
• Search Page