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
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.