Tutorial¶
In addition to this tutorial, you can find examples in the examples folder.
Table of Contents:
- Basic Usage
- colorise.cprint
- colorise.fprint
- colorise.highlight
- Attributes
- Disabling Colors
- More Colors!
- 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
sets the current foreground color to red while
>>> colorise.set_color(fg='red', bg='green'); print('Hello')
Hello
sets 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', 'lightmagenta', '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 yellow text and a green background', fg='yellow', bg='green')
This has yellow 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=yellow,bg=green}This has yellow text and a green background')
This has yellow text and a green background
>>> colorise.fprint('{fg=yellow,bg=green}This has a green background and yellow foreground but{fg=red} changes to red')
This has a green background and yellow 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=yellow,bg=green}This has a green background and yellow foreground but{fg=red} changes to red', autoreset=False)
This has a green background and yellow foreground but changes to red
>>> colorise.fprint('{fg=yellow,bg=green}This has a green background and yellow foreground but{fg=red} changes to red', autoreset=True)
This has a green background and yellow 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=yellow,bg=green}This has a green background and yellow foreground but{reset}{fg=red} changes to red', autoreset=False)
This has a green background and yellow foreground but changes to red
Note
It is not currently possible to mix color formats and Python’s string
formatting such as colorise.fprint('{fg=red}{0}', 'test'). See this
issue if you want
to know more or help.
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=cyan,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!
Disabling colors means that no ANSI escape sequences are emitted and no Windows Console API calls are made so if a color has been set previously, outputting disabled colors are still affected.
>>> colorise.set_color(fg='red')
>>> 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.cprint('Via short-hand hex', fg='#09c', bg='0xfd9')
Via short-hand hex
>>> colorise.fprint('{fg=rgb(255;0;135)}Via RGB')
Via RGB
>>> colorise.cprint('Via HSV', bg='hsv(0.7;41.1;82)')
Via HSV
>>> colorise.fprint('{bg=hls(0.21;0.48;0.98)}Via HLS')
Via HLS
HSV values are hue ([0; 360]), saturation ([0; 100]), and value ([0; 100]). HLS values are hue ([0; 360]), lightness ([0; 100]), and saturation ([0; 100]).
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 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 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 in the logical color table).
>>> 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 and automatically restores the
original color table.
Note
Redefining colors does not currently work with ConEmu or on Mac and Linux systems.
