Description

ANSI escape character sequences have long been used to produce colored terminal
text and cursor positioning on Unix and Macs. Colorama makes this work on
Windows, too, by wrapping stdout, stripping ANSI sequences it finds (which
otherwise show up as gobbledygook in your output), and converting them into the
appropriate win32 calls to modify the state of the terminal. On other platforms,
Colorama does nothing.

Colorama also provides some shortcuts to help generate ANSI sequences
but works fine in conjunction with any other ANSI sequence generation library,
such as Termcolor (http://pypi.python.org/pypi/termcolor.)

This has the upshot of providing a simple cross-platform API for printing
colored terminal text from Python, and has the happy side-effect that existing
applications or libraries which use ANSI sequences to produce colored output on
Linux or Macs can now also work on Windows, simply by calling
colorama.init().

An alternative approach is to install ‘ansi.sys’ on Windows machines, which
provides the same behaviour for all applications running in terminals. Colorama
is intended for situations where that isn’t easy (e.g. maybe your app doesn’t
have an installer.)

Demo scripts in the source code repository prints some colored text using
ANSI sequences. Compare their output under Gnome-terminal’s built in ANSI
handling, versus on Windows Command-Prompt using Colorama:

These screengrabs show that Colorama on Windows does not support ANSI ‘dim
text’: it looks the same as ‘normal text’.

Dependencies

Usage

Initialisation

If you are on Windows, the call to init() will start filtering ANSI escape
sequences out of any text sent to stdout or stderr, and will replace them with
equivalent Win32 calls.

Calling init() has no effect on other platforms (unless you request other
optional functionality, see keyword args below.) The intention is that
applications can call init() unconditionally on all platforms, after which
ANSI output should just work.

To stop using colorama before your program exits, simply call deinit().
This will restore stdout and stderr to their original values, so that Colorama
is disabled. To start using Colorama again, call reinit(), which wraps
stdout and stderr again, but is cheaper to call than doing init() all over
again.

Colored Output

Cross-platform printing of colored text can then be done using Colorama’s
constant shorthand for ANSI escape sequences:

or Colorama can be used happily in conjunction with existing ANSI libraries
such as Termcolor:

from colorama import init
from termcolor import colored
# use Colorama to make Termcolor work on Windows too
init()
# then use Termcolor for all colored text output
print(colored('Hello, World!', 'green', 'on_red'))

Pass True or False to override whether ansi codes should be
stripped from the output. The default behaviour is to strip if on Windows.

init(convert=None):

Pass True or False to override whether to convert ansi codes in the
output into win32 calls. The default behaviour is to convert if on Windows
and output is to a tty (terminal).

init(wrap=True):

On Windows, colorama works by replacing sys.stdout and sys.stderr
with proxy objects, which override the .write() method to do their work. If
this wrapping causes you problems, then this can be disabled by passing
init(wrap=False). The default behaviour is to wrap if autoreset or
strip or convert are True.

When wrapping is disabled, colored printing on non-Windows platforms will
continue to work as normal. To do cross-platform colored output, you can
use Colorama’s AnsiToWin32 proxy directly:

If anything doesn’t work for you, or doesn’t do what you expected or hoped for,
I’d love to hear about it on that issues list, would be delighted by patches,
and would be happy to grant commit access to anyone who submits a working patch
or two.

Recognised ANSI Sequences

ANSI sequences generally take the form:

ESC [ <param> ; <param> … <command>

Where <param> is an integer, and <command> is a single letter. Zero or more
params are passed to a <command>. If no params are passed, it is generally
synonymous with passing a single zero. No spaces exist in the sequence, they
have just been inserted here to make it easy to read.

Multiple numeric params to the ‘m’ command can be combined into a single
sequence, eg:

ESC [ 36 ; 45 ; 1 m # bright cyan text on magenta background

All other ANSI sequences of the form ESC [ <param> ; <param> ... <command>
are silently stripped from the output on Windows.

Any other form of ANSI sequence, such as single-character codes or alternative
initial characters, are not recognised nor stripped. It would be cool to add
them though. Let me know if it would be useful for you, via the issues on
google code.

Development

Help and fixes welcome! Ask Jonathan for commit rights, you’ll get them.

Running tests requires:

Michael Foord’s ‘mock’ module to be installed.

Tests are written using the 2010 era updates to ‘unittest’, and require to
be run either using Python2.7 or greater, or else to have Michael Foord’s
‘unittest2’ module installed.

To run tests:

python -m unittest discover -p *_test.py

This, like a few other handy commands, is captured in a Makefile.

If using nose to run the tests, pass the -s flag required because ‘nosetests’
otherwise applies a proxy of its own to stdout, which confuses the unit tests.