ANSIColors (version 1.9.9.public, mar. 19/03/2013 at 12h:25m:49s)
index
ANSIColors.py
ANSIColors.py.html

An efficient and simple ANSI colours module (and also a powerfull script), with functions to print text using colours.
 
About the convention for the names of the colours :
 * for the eight colours black, red, green, yellow, blue, magenta, cyan, white:
  * the name in minuscule is for colour **with bold** (example 'yellow'),
  * the name starting with 'B' is for colour **without bold** (example 'Byellow'),
  * the name starting with a capital letter is for the background colour (example 'Yellow').
 * for the special effects (blink, italic, bold, underline, negative), **not always supported** :
  * the name in minuscule is for **activate** the effect,
  * the name starting in capital letter is for **desactivate** the effect.
 * for the other special effects (nocolours, default, Default, clear, el), the effect is **immediate** (and seems to be well supported).
 
List of functions:
==================
 
To print a string
-----------------
 
 * sprint: give a string,
 * printc: like __builtin__.print, but with interpreting balises to put colours,
 * writec: like printc, but using any file object (and no new line added at the end of the string),
 
To clean the terminal or the line
---------------------------------
 
 * erase: erase all ANSI colours balises in the string (like sprint, but erasing and not interpreting colour balises)
 * clearLine, clearScreen: to clear the current line or screen,
 * Reset: to return to default foreground and background, and stopping all *fancy* effects (like blinking or reverse video).
 
Others functions
----------------
 
 * notify: try to display a *system* notification. **Only on *linux*.**
 * xtitle: try to set the *title* of the terminal. **Not always supported**.
 
Example of use (module) :
=========================
 
 To store a string, use *sprint* (*i.e.* print to a string, sprint), like here ::
 
   >>> example=sprint("France flag is <blue>blue<white>white<red>red<white>, Italy flag have <green>green on it<white>.")
 The string *example* can then be printed, with colours, with ::
 
   >>> print example # Sorry, but in the documentation it is hard to show colours :)
   France flag is bluewhitered, Italy flag have green on it.
 
 
 To directly print a string colored by balises, use *printc* ::
 
   >>> printc("Batman's costum is <black>black<white>, Aquaman's costum is <blue>blue<white> and <green>green<white>.")
 
 .. seealso::
    This is the most usefull function. To do the same, but on any file, use *writec*
 
 Moreover, the function *erase* can also be usefull to simply delete all *valid* colour balises ::
 
   >>> print erase("Batman's costum is <black>black<white>, Aquaman's costum is <blue>blue<white> and <green>green<white>, and this is a non-valid <balise>, so it is kept like this.")
   Batman's costum is black, Aquaman's costum is blue and green, and this is a non-valid <balise>, so it is kept like this
 
 
 In this last example, *<el>* balise is used to erase the current content of the line, usefull to make a *dynamical* print ::
 
   >>> writec("<red>Computing <u>2**(2**(2**4))<reset>...."); tmp=2**(2**(2**4)); writec("<el><green> Done !<reset>")
   Done !
 The first 'Computing 2**(2**(2**4))....' have disappeared after the computation !
 
Example of use (script):
========================
 
 * To show the help :code:`$ ANSIColors.py --help`;
 
 * To run a test :code:`$ ANSIColors.py --test`;
 
 * To produce a GNU Bash colour aliases file 
   :code:`$ ANSIColors.py --generate --file ~/.colour_aliases.sh`
 
Auto detection
==============
 
Now, this script can detect if ANSI codes are supported :
  1. ``$ ANSIColors.py --help`` : will print with colours if colours seems to be supported;
  2. ``$ ANSIColors.py --help --noANSI`` : will print without any colours, even if it is possible;
  3. ``$ ANSIColors.py --help --ANSI`` : will force the use of colours, even they seems to be not supported.
 
And, the module part behaves exactly like the script part.
 
**This functionality is still experimental**, and work only on Ubuntu 11.10,
as far as I know.
 
------------------------------------------------------------------------------
 
About:
======
 
This module is **still in development**.
Last version of this project can be found on-line :
 
 * `here on BitBucket <https://bitbucket.org/lbesson/ansi-colors>`_;
 * `here on PyPi <https://pypi.python.org/pypi/ANSIColors-balises>`_.
 
 
The reference page for ANSI code is : `here on Wikipedia <http://en.wikipedia.org/wiki/ANSI_escape_code>`_.
The reference page for XTitle escape code is : `here <http://www.faqs.org/docs/Linux-mini/Xterm-Title.html>`_.
 
Documentation
=============
 
The doc is available on-line :
 
 * on `pythonhosted.org/ANSIColors-balises/ <http://pythonhosted.org/ANSIColors-balises/index.html>`_;
 * on one of my own pages :
 
   * on the cr@ns network `besson/publis/ansi-colors/ <http://perso.crans.org/besson/publis/ansi-colors/index.html>`_,
   * on the CS department at ENS de Cachan `~lbesson/publis/ansi-colors/ <http://www.dptinfo.ens-cachan.fr/~lbesson/publis/ansi-colors/index.html>`_,
 
Or some explanations (and an OCaml version of this module) 
are available on my Google Site `tools/ansi-colors <https://sites.google.com/site/naereencorp/tools/ansicolors>`_.
 
Copyrigths:
===========
 
 (c) October 2012 - Mars 2013
 By Lilian BESSON,
 ENS de Cachan (M1 Mathematics & M1 Computer Science MPRI)
 mailto:lbesson[AT]ens-cachan.fr
    
 For Naereen Corp.
 mailto:naereen-corporation[AT]laposte.net
 https://sites.google.com/site/naereencorp/tools/ansicolors

 
Modules
       
os
subprocess
sys

 
Functions
       
Reset()
Reset() -> unit
Try to reset the current ANSI codes buffer, using [reset].
clearLine()
clearLine() -> unit
Try to clear the current line using ANSI code [el].
clearScreen()
clearScreen() -> unit
Try to clear the screen using ANSI code [clear].
erase(chainWithBalises, left='<', right='>', verbose=False)
erase(chainWithBalises, left='<', right='>', verbose=False) -> string
Parse a string containing colour balises, when colour is one of the previous define name,
and then return it, with colour balises **erased**.
 
Example:
 This example seems exactly the same that the previous in the documentation, but it's not (**again**: it is hard and painful (and maybe impossible) to put colour in Sphinx RST files, so there is **no colour in output** in the examples... but be sure there is the real output !).
  >>> print erase("<blue>This is blue.<white>And <this> is white.<red>Now this is red because I am <angry> !<reset>")
  This is blue.And <this> is white.Now this is red because I am <angry> !
notify(msg='', obj='.: Notification sent by ANSIColors.notify :.', icon=None, verb=False)
notify(msg='', obj='.: Notification sent by ANSIColors.notify :.', icon=None, verb=False) -> bool
 
Notification using subprocess and notify-send.
Also print the informations directly to the screen (only if verb=True).
 
 
.. warning::
 
   This doesn't use any *ANSI escape* codes, but the common *notify-send* **linux** program.
   It shall fails (but not durty) on Windows or Mac OS X.
 
 
Return True iff the title have been correctly changed.
Fails simply if *notify-send* is not found.
printc(chainWithBalises, left='<', right='>')
printc(chainWithBalises, left='<', right='>') -> unit
A shortcut to print sprint(chainWithBalises) : analyse all balises, and print the result.
sprint(chainWithBalises, left='<', right='>', verbose=False)
sprint(chainWithBalises, left='<', right='>', verbose=False) -> string
Parse a string containing colour balises, when colour is one of the previous define name,
and then return it, with colour balises changed to concrete ANSI colour codes.
 
**Balises are delimited** by [left] and [right].
By default, it's Pango style whit '<' and '>', but you can change them.
For example, a HTML style like : left='<span colour=' and right='>' is also possible. (But, without closing '</span', this is a stupid example. Sorry I didn't find anything else...)
 
.. warning::
 
   It is more prudent to put nothing else than ANSI Colors (*i.e.* values in colorList) between '<' and '>' in [chainWithBalises].
   The comportement of the function in case of false balises **is not perfect**.
   Moreover, a good idea could be to don't try to use '<' or '>' for anything else than balises.
   I know, it's not perfect. But, the syntax of color balises is so simple and se beautiful with this limitation that you will surely forgive me this, *won't you* ;) ?
        
Example: ::
 
    >>> print sprint("<blue>this is blue.<white>And <this> is white.<red>Now this is red because I am <angry> !<green><white>")
    this is blue.And <this> is white.Now this is red because I am <angry> !
 
*About:*
 This function is used in all the following, so all other function can also used *left* and *right* arguments.
tocolor(string)
tocolor(string) -> string
Convert a string to a colour.
[string] **have** to be in [colorList] to be recognized (and interpreted).
Default value if [string] is not one of the colour name is "" the empty string.
writec(chainWithBalises='', file=<open file '<stdout>', mode 'w'>, left='<', right='>', flush=True)
writec(chainWithBalises="", file=sys.stdout, left='<', right='>', flush=True) -> unit
Usefud to print colored text **to a file**, represented by the object *file*.
Also usefull to print colored text, but without an ending '\n' caracter.
        
Example:
        
In this example, before the long calcul begin, it print 'Computing 2**(2**(2**4)).....',
and when the computation is done, erase the current line (with <el> balise),
and print ' Done !' in green, and the result of the computation: ::
 
     >>> writec("<red>Computing<reset> 2**(2**(2**4))....."); tmp=2**(2**(2**4)); writec("<el><green>Done !<reset>")
         
This example show how to use ANSIColors module to put colored data in a file.
Be aware that this file now contains ANSI escape sequences.
For example, *$ cat /tmp/colored-text.txt * will well print the colours, but editing the file will show *hard values* of escape code (*you know, the stuff that you typically don't want to know anything, the **dirty stuff** !*): ::
 
    >>> my_file = open('/tmp/colored-text.txt', mode='w') # Open an adhoc file.
    >>> write("<blue>this is blue.<white>And <this> is white.<red>Now this is red because I am <angry> !<green><white>", file=my_file)
        
 
Remark:
 Can also be used to simply reinitialize the ANSI colors buffer, but the function *Reset* is here for this: ::
 
    >>> writec("<reset>")
 
 
.. warning::
   
   The file *file* **will be flushed** by this function if *flush* is set to True (this is default comportement).
   If you prefer no to, use flush=False option: ::
 
       >>> writec(chainWithBalises_1), file=my_file, flush=False)
       >>> # many things.
       >>> writec(chainWithBalises_n), file=my_file, flush=False)
       >>> my_file.flush()      # only flush *here*.
xtitle(new_title='', verb=False)
xtitle(new_title="", verb=False) -> 0|1
**Modify the current terminal title**.
Returns 0 if one of the two solutions worked, 1 otherwise.
 
An experimental try is with **ANSI escape code**,
if the simple way by *invoking* the **xtitle** program doesn't work (or if it is not installed).
 
.. note::
 
   The second solution used the two *ANSI* Balises <title> and <bell>.
   So, you can also do it with : ::
   
       >>> ANSIColors.writec("<title>.: This is the new title of the terminal :.<bell>")
 
   
But this function *xtitle* is better : it tries two ways, and returns a signal to inform about his success.

 
Data
        ANSISupported = False
B = ''
Bblack = ''
Bblue = ''
Bcyan = ''
Bgreen = ''
Black = ''
Blink = ''
Blue = ''
Bmagenta = ''
Bred = ''
Bwhite = ''
Byellow = ''
Cyan = ''
Default = ''
ERROR = ''
Green = ''
INFO = ''
Italic = ''
Magenta = ''
Neg = ''
Red = ''
U = ''
WARNING = ''
White = ''
Yellow = ''
__author__ = 'Lilian BESSON (mailto:lilian.besson[AT]normale.fr)'
__date__ = 'mar. 19/03/2013 at 12h:25m:49s'
__version__ = '1.9.9.public'
b = ''
bell = ''
black = ''
blink = ''
blue = ''
clear = ''
colorList = ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white', 'Bblack', 'Bred', 'Bgreen', 'Byellow', 'Bblue', 'Bmagenta', 'Bcyan', 'Bwhite', 'Black', 'Red', 'Green', 'Yellow', ...]
cyan = ''
default = ''
el = ''
green = ''
italic = ''
magenta = ''
n = 'INFO'
neg = ''
nocolors = ''
question = ''
red = ''
reset = ''
simpleColorList = ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white']
title = ''
u = ''
warning = ''
white = ''
yellow = ''

 
Author
        Lilian BESSON (mailto:lilian.besson[AT]normale.fr)