Welcome to ansicolortags’s documentation!

Welcome to the documentation for ansicolortags, a Python 2 or 3 module to use ANSI colors in a terminal application from Python.

The ansicolortags module provides an efficient and useful function (printc()) to print colored text in a terminal application with Python 2 and 3, with a HTML-tag like style:

>>> from ansicolortags import printc  # Import the function
>>> printc("I like my sky to be <blue>blue<reset>, not <black>dark<reset> !")
I like my sky to be blue, not dark !

Installation

TL;DR: install this module and script in one command with pip:

pip install ansicolortags

Dependencies

The project is entirely written in pure Python, supporting both version 2 (2.7+) and version 3 (3.1+). It has no dependencies except a Python interpreter! For more details about the Python language, see its official website.

How to install it ?

There is three different ways:

1. Directly, with pip

The preferred way is to install ansicolortags directly with pip (what is pip?):

$ pip install ansicolortags

On GNU/Linux, it might be necessary to give it sudo rights:

$ sudo pip install ansicolortags

If you have both Python 2 and 3, and if you want to use the module from both, be sure to install it with both pip2 and pip3 :

$ sudo pip2 install ansicolortags  # For Python 2 (v2.7+)
$ sudo pip3 install ansicolortags  # For Pythoh 3 (v3.1+)

2. Download, extract, and use setup.py

Or you can also follow these 4 steps:

  1. download the file ansicolortags.tar.gz from Bitbucket, or from PyPi (if needed, it is signed numerically with my PGP key);

  2. extract it (with tar xzfv, or a graphical solution, like File Roller);

  3. then go in the subdirectory (cd ansicolortags-0.4/);

  4. and finally install it with Python distutils setup.py tool:

    $ python setup.py install

    Or maybe with sudo rights, if the first try did not work :

    $ sudo python setup.py install
For more information, run python setup.py help or python setup.py install help.

3. Without installing it

Note that installation is not mandatory : a third solution is to simply include JUST the file ansicolortags.py, and embed it in your own projects. The project can be used without installing anything elsewhere.

Examples

The function ansicolortags.printc()

The main function of this module is printc (ansicolortags.printc()), for example use it like printc("my string with color tags"). This function works exactly like print("my string with color tags").

For instance, a quick description of super hero’s costumes can be done like this:

>>> printc("<reset><white>Batman's costume is <black>black<white>, Aquaman's costume is <blue>blue<white> and <green>green<white>, and Superman's costume is <red>red<white> and <blue>blue<white> ...")
Batman's costume is black, Aquaman's costume is blue and green, and Superman's costume is red and blue ...

(Sorry, but it is hard to embed colors in the output of a Python command in a Sphinx generated web-pages.)

Another example, it will print the text “France flag is blue, white and red !” with appropriate colors:

>>> from ansicolortags import printc  # Import the function
>>> printc("France flag is <blue>blue<reset>, <white>white<reset>, and <red>red<reset> !")
France flag is blue, white and red !

The function printc() should be imported from ansicolortags (ansicolortags.printc()).

Note that other useful functions are defined: ansicolortags.writec() to write to a file, ansicolortags.xtitle() to change the title of the terminal, ansicolortags.sprint() to convert all the tags (e.g., <red>) in a string to their ANSI Code value (e.g., \033[01;31m), etc.

The script ansicolortags.py

But the project also installs a script, ansicolortags.py, which can be executed directly, or called with python -m ansicolortags after installation.

The script itself does not have a useful purpose, except for testing and demonstrating the capabilities of this project. If needed: ansicolortags.py.

python -m ansicolortags --help

This command shows the help of the script, colored with the tools defined in the script:

The help message of the script.

python -m ansicolortags --test

This command shows a complete test of all tags defined in the module:

The canonical test of the script (1/2). The canonical test of the script (2/2).

--ANSI or --noANSI option

You can force to use ANSI codes (even if they appear to not be supported be the output, e.g. a pipe) with the --ANSI flag option, or force to disable them with the --noANSI flag option:

Test of the --ANSI flag option. Test of the --noANSI flag option.

python -m ansicolortags --generate

This command can be used to generate a .color.sh file, to be used in any GNU Bash script:

The --generate option of the script.

Complete documentation

And, a detailed description of every functions and every constants of the ansicolortags module is available on the documentation of the module ansicolortags (automatically generated from the docstrings in the file).

Contact the author if needed?

Hi, I am Lilian Besson, a French student at ÉNS de Cachan, in Mathematics and computer science (CS).

If needed, feel free to contact me :

  1. either with this web page;
  2. or via my bitbucket account lbesson;
  3. or via email here (remove the [] and change DOT to . and AT to @.

You can use this form to inform me of a bug on ansicolortags.py: https://bitbucket.org/lbesson/ansicolortags.py/issues?status=new&status=open !

Index and tables

The MIT License (MIT)

The MIT License (MIT) Copyright © 2016 Lilian Besson (Naereen), https://bitbucket.org/lbesson/ <naereen at crans dot org>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Cloud of words

_images/cloudwords.png