A python module for using terminal colors in linux. It contains a simple
color function that accepts style and color names, and outputs a string
with escape codes, but also has all colors and styles as chainable methods
- Python 3.5+ -
This library uses
yield fromand the
typingmodule. Python 2 support is not planned.
There are no dependencies required for importing this library on Linux, however:
- Docopt - Only required for the command line tool and the colr.docopt wrapper, not the library itself.
- Colorama - Windows only. This is not required on linux. It provides a helper for basic color support for Windows.
pip install colr
Or you can clone the repo on GitHub and install it from the command line:
git clone https://github.com/welbornprod/colr.git cd colr python3 setup.py install
from colr import color print(color('Hello world.', fore='red', style='bright'))
from colr import Colr as C print( C() .bright().red('Hello ') .normal().blue('World') ) # Background colors start with 'bg', and AttributeError will be raised on # invalid method names. print(C('Hello ', fore='red').bgwhite().blue('World'))
Examples (256 Colors):
from colr import color # Invalid color names/numbers raise a ValueError. print(color('Hello world', fore=125, back=80))
from colr import Colr as C # Foreground colors start with 'f_' # Background colors start with 'b_' print(C().f_125().b_80('Hello World'))
Examples (True Color):
from colr import color print(color('Hello there.', fore=(255, 0, 0), back=(0, 0, 0)))
from colr import Colr as C # Foreground colors are set with the `rgb()` method. # Background colors are set with the `b_rgb()` method. # Text for the chained methods should be chained after or during # the call to the methods. print(C().b_rgb(0, 0, 0).rgb(255, 0, 0, 'Hello there.'))
from colr import color # When not using the Colr.hex method, the closest matching extended code # is used. For true color, just use: # fore=hex2rgb('ff0000') # or # Colr.hex('ff0000', rgb_mode=True) print(color('Hello there.', fore='ff0000', back='000'))
from colr import Colr as C # Foreground colors are set with the `hex()` method. # Background colors are set with the `b_hex()` method. # Text for the chained methods should be chained after or during # the call to the methods. print(C().b_hex('#000').hex('ff0000', 'Hello there.')) # With rgb_mode set, these are the same: print(C().hex('ff0000', 'test', rgb_mode=True)) print(C().rgb(255, 0, 0, 'test'))
Documentation for the
colr API can be found in the GitHub repo
|colr.Colr||Methods for the
|colr.Control||Functions, classes, and methods for the
|colr.progress||Progress updates, bars, or spinners.|
|colr.trans||Color code translation/detection.|
colr package can be used as a command line tool. An entry point script
colr is created when installed with pip. Otherwise it can be executed
python -m colr method.
Basic usage involves passing text, or piping stdin data and setting the colors by position or flag.
# These all do the same thing: colr "Test" "red" "white" "bright" colr "Test" -f "red" -b "white" -s "bright" printf "Test" | colr -f "red" -b "white" -s "bright"
Using the positional arguments is faster for just setting fore colors, but the flag method is needed for stdin data, or for picking just the background color or style:
colr "Test" -s "bright"
Extended and True colors are supported:
colr "Test" 124 255 colr "Test" "255, 0, 0" "255, 255, 255" # Use true color (rgb) escape codes to generate a gradient, and then # center it in the terminal (0 means use terminal width). colr "Test" -G "255,0,0" -G "0,0,255" -c 0
It will do fore, back, style, gradients, rainbows, justification, and translation. It can strip codes from text (as an argument or stdin), or explain the codes found in the text.
fortune | colr --rainbow
The colr tool does not read files, but it's not a problem:
cat myfile.txt | colr --gradient red
Also see ccat.
A small command-runner is included, called
program will run another program, printing an animated message instead of the
It is used to turn "noisy" commands into a nice single-line animation.
To run a program with the default settings,
-- is still required:
colr-run -- bash -c 'x=0; while ((x<1000000)); do let x+=1; done'
Any stderr output from the program will ruin the animation, which may be fine if you are only looking for errors.
You can silence stderr output with
-e if you don't need it:
colr-run -e -- some-long-running-command
The exit status of
colr-run is the exit status of the command being
colr-run errors, the exit status is
1 for basic errors,
2 for cancelled commands.
Colr provides a wrapper for docopt that will automatically colorize usage strings. If you provide it a script name it will add a little more color by colorizing the script name too.
from colr import docopt argd = docopt(USAGE, script='mycommand')
In the past, I used a simple
color() function because I'm not fond of the
to make it available to Python also, at least as an option.
The reset code is appended only if some kind of text was given, and
colr/style args were used. The only values that are considered 'no text'
'' (empty string).
str(val) is called on all other
Colr(0, 'red') and
Colr(False, 'blue') will work, and the reset
code will be appended.
This makes it possible to build background colors and styles, but also have separate styles for separate pieces of text.
I don't really have the desire to back-port this to Python 2.
It wouldn't need too many changes, but I like the Python 3 features
Basic colors are supported on Windows through the
It is only imported if
platform.system() == 'Windows'.
It provides a wrapper around
stderr to make basic ansi codes
work. If the import fails, then all color codes are disabled
colr.disable() was called).
I booted into Windows 8 for the first time in months to make this little
feature happen, only to discover that the color situation for CMD and
PowerShell really sucks. If you think you can help improve the
for windows, please see the contributing section.
This library may be a little too flexible:
from colr import Colr as C warnmsg = lambda s: C('warning', 'red').join('[', ']')(' ').green(s) print(warnmsg('The roof is on fire again.'))