| OLD | NEW |
|---|
| (Empty) |
| 1 Download and docs: | |
| 2 http://pypi.python.org/pypi/colorama | |
| 3 Development: | |
| 4 http://code.google.com/p/colorama | |
| 5 | |
| 6 Description | |
| 7 =========== | |
| 8 | |
| 9 Makes ANSI escape character sequences, for producing colored terminal text and | |
| 10 cursor positioning, work under MS Windows. | |
| 11 | |
| 12 ANSI escape character sequences have long been used to produce colored terminal | |
| 13 text and cursor positioning on Unix and Macs. Colorama makes this work on | |
| 14 Windows, too. It also provides some shortcuts to help generate ANSI sequences, | |
| 15 and works fine in conjunction with any other ANSI sequence generation library, | |
| 16 such as Termcolor (http://pypi.python.org/pypi/termcolor.) | |
| 17 | |
| 18 This has the upshot of providing a simple cross-platform API for printing | |
| 19 colored terminal text from Python, and has the happy side-effect that existing | |
| 20 applications or libraries which use ANSI sequences to produce colored output on | |
| 21 Linux or Macs can now also work on Windows, simply by calling | |
| 22 ``colorama.init()``. | |
| 23 | |
| 24 Demo scripts in the source code repository prints some colored text using | |
| 25 ANSI sequences. Compare their output under Gnome-terminal's built in ANSI | |
| 26 handling, versus on Windows Command-Prompt using Colorama: | |
| 27 | |
| 28 .. image:: http://colorama.googlecode.com/hg/screenshots/ubuntu-demo.png | |
| 29 :width: 661 | |
| 30 :height: 357 | |
| 31 :alt: ANSI sequences on Ubuntu under gnome-terminal. | |
| 32 | |
| 33 .. image:: http://colorama.googlecode.com/hg/screenshots/windows-demo.png | |
| 34 :width: 668 | |
| 35 :height: 325 | |
| 36 :alt: Same ANSI sequences on Windows, using Colorama. | |
| 37 | |
| 38 These screengrabs show that Colorama on Windows does not support ANSI 'dim | |
| 39 text': it looks the same as 'normal text'. | |
| 40 | |
| 41 | |
| 42 Dependencies | |
| 43 ============ | |
| 44 | |
| 45 None, other than Python. Tested on Python 2.5.5, 2.6.5, 2.7, 3.1.2, and 3.2 | |
| 46 | |
| 47 | |
| 48 Usage | |
| 49 ===== | |
| 50 | |
| 51 Initialisation | |
| 52 -------------- | |
| 53 | |
| 54 Applications should initialise Colorama using:: | |
| 55 | |
| 56 from colorama import init | |
| 57 init() | |
| 58 | |
| 59 If you are on Windows, the call to ``init()`` will start filtering ANSI escape | |
| 60 sequences out of any text sent to stdout or stderr, and will replace them with | |
| 61 equivalent Win32 calls. | |
| 62 | |
| 63 Calling ``init()`` has no effect on other platforms (unless you request other | |
| 64 optional functionality, see keyword args below.) The intention is that | |
| 65 applications can call ``init()`` unconditionally on all platforms, after which | |
| 66 ANSI output should just work. | |
| 67 | |
| 68 To stop using colorama before your program exits, simply call ``deinit()``. | |
| 69 This will restore stdout and stderr to their original values, so that Colorama | |
| 70 is disabled. To start using Colorama again, call ``reinit()``, which wraps | |
| 71 stdout and stderr again, but is cheaper to call than doing ``init()`` all over | |
| 72 again. | |
| 73 | |
| 74 | |
| 75 Colored Output | |
| 76 -------------- | |
| 77 | |
| 78 Cross-platform printing of colored text can then be done using Colorama's | |
| 79 constant shorthand for ANSI escape sequences:: | |
| 80 | |
| 81 from colorama import Fore, Back, Style | |
| 82 print Fore.RED + 'some red text' | |
| 83 print Back.GREEN + and with a green background' | |
| 84 print Style.DIM + 'and in dim text' | |
| 85 print + Fore.RESET + Back.RESET + Style.RESET_ALL | |
| 86 print 'back to normal now' | |
| 87 | |
| 88 or simply by manually printing ANSI sequences from your own code:: | |
| 89 | |
| 90 print '/033[31m' + 'some red text' | |
| 91 print '/033[30m' # and reset to default color | |
| 92 | |
| 93 or Colorama can be used happily in conjunction with existing ANSI libraries | |
| 94 such as Termcolor:: | |
| 95 | |
| 96 from colorama import init | |
| 97 from termcolor import colored | |
| 98 | |
| 99 # use Colorama to make Termcolor work on Windows too | |
| 100 init() | |
| 101 | |
| 102 # then use Termcolor for all colored text output | |
| 103 print colored('Hello, World!', 'green', 'on_red') | |
| 104 | |
| 105 Available formatting constants are:: | |
| 106 | |
| 107 Fore: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET. | |
| 108 Back: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET. | |
| 109 Style: DIM, NORMAL, BRIGHT, RESET_ALL | |
| 110 | |
| 111 Style.RESET_ALL resets foreground, background and brightness. Colorama will | |
| 112 perform this reset automatically on program exit. | |
| 113 | |
| 114 | |
| 115 Cursor Positioning | |
| 116 ------------------ | |
| 117 | |
| 118 ANSI codes to reposition the cursor are supported. See demos/demo06.py for | |
| 119 an example of how to generate them. | |
| 120 | |
| 121 | |
| 122 Init Keyword Args | |
| 123 ----------------- | |
| 124 | |
| 125 ``init()`` accepts some kwargs to override default behaviour. | |
| 126 | |
| 127 init(autoreset=False): | |
| 128 If you find yourself repeatedly sending reset sequences to turn off color | |
| 129 changes at the end of every print, then ``init(autoreset=True)`` will | |
| 130 automate that:: | |
| 131 | |
| 132 from colorama import init | |
| 133 init(autoreset=True) | |
| 134 print Fore.RED + 'some red text' | |
| 135 print 'automatically back to default color again' | |
| 136 | |
| 137 init(strip=None): | |
| 138 Pass ``True`` or ``False`` to override whether ansi codes should be | |
| 139 stripped from the output. The default behaviour is to strip if on Windows. | |
| 140 | |
| 141 init(convert=None): | |
| 142 Pass ``True`` or ``False`` to override whether to convert ansi codes in the | |
| 143 output into win32 calls. The default behaviour is to convert if on Windows | |
| 144 and output is to a tty (terminal). | |
| 145 | |
| 146 init(wrap=True): | |
| 147 On Windows, colorama works by replacing ``sys.stdout`` and ``sys.stderr`` | |
| 148 with proxy objects, which override the .write() method to do their work. If | |
| 149 this wrapping causes you problems, then this can be disabled by passing | |
| 150 ``init(wrap=False)``. The default behaviour is to wrap if autoreset or | |
| 151 strip or convert are True. | |
| 152 | |
| 153 When wrapping is disabled, colored printing on non-Windows platforms will | |
| 154 continue to work as normal. To do cross-platform colored output, you can | |
| 155 use Colorama's ``AnsiToWin32`` proxy directly:: | |
| 156 | |
| 157 from colorama import init, AnsiToWin32 | |
| 158 init(wrap=False) | |
| 159 stream = AnsiToWin32(sys.stderr).stream | |
| 160 print >>stream, Fore.BLUE + 'blue text on stderr' | |
| 161 | |
| 162 | |
| 163 Status & Known Problems | |
| 164 ======================= | |
| 165 | |
| 166 I've personally only tested it on WinXP (CMD, Console2) and Ubuntu | |
| 167 (gnome-terminal, xterm), although it sounds like others are using it on other | |
| 168 platforms too. | |
| 169 | |
| 170 See outstanding issues and wishlist at: | |
| 171 http://code.google.com/p/colorama/issues/list | |
| 172 | |
| 173 If anything doesn't work for you, or doesn't do what you expected or hoped for, | |
| 174 I'd *love* to hear about it on that issues list. | |
| 175 | |
| 176 | |
| 177 Recognised ANSI Sequences | |
| 178 ========================= | |
| 179 | |
| 180 ANSI sequences generally take the form: | |
| 181 | |
| 182 ESC [ <param> ; <param> ... <command> | |
| 183 | |
| 184 Where <param> is an integer, and <command> is a single letter. Zero or more | |
| 185 params are passed to a <command>. If no params are passed, it is generally | |
| 186 synonymous with passing a single zero. No spaces exist in the sequence, they | |
| 187 have just been inserted here to make it easy to read. | |
| 188 | |
| 189 The only ANSI sequences that colorama converts into win32 calls are:: | |
| 190 | |
| 191 ESC [ 0 m # reset all (colors and brightness) | |
| 192 ESC [ 1 m # bright | |
| 193 ESC [ 2 m # dim (looks same as normal brightness) | |
| 194 ESC [ 22 m # normal brightness | |
| 195 | |
| 196 # FOREGROUND: | |
| 197 ESC [ 30 m # black | |
| 198 ESC [ 31 m # red | |
| 199 ESC [ 32 m # green | |
| 200 ESC [ 33 m # yellow | |
| 201 ESC [ 34 m # blue | |
| 202 ESC [ 35 m # magenta | |
| 203 ESC [ 36 m # cyan | |
| 204 ESC [ 37 m # white | |
| 205 ESC [ 39 m # reset | |
| 206 | |
| 207 # BACKGROUND | |
| 208 ESC [ 40 m # black | |
| 209 ESC [ 41 m # red | |
| 210 ESC [ 42 m # green | |
| 211 ESC [ 43 m # yellow | |
| 212 ESC [ 44 m # blue | |
| 213 ESC [ 45 m # magenta | |
| 214 ESC [ 46 m # cyan | |
| 215 ESC [ 47 m # white | |
| 216 ESC [ 49 m # reset | |
| 217 | |
| 218 # cursor positioning | |
| 219 ESC [ x;y H # position cursor at x,y | |
| 220 | |
| 221 # clear the screen | |
| 222 ESC [ mode J # clear the screen. Only mode 2 (clear entire screen) | |
| 223 # is supported. It should be easy to add other modes, | |
| 224 # let me know if that would be useful. | |
| 225 | |
| 226 Multiple numeric params to the 'm' command can be combined into a single | |
| 227 sequence, eg:: | |
| 228 | |
| 229 ESC [ 36 ; 45 ; 1 m # bright cyan text on magenta background | |
| 230 | |
| 231 All other ANSI sequences of the form ``ESC [ <param> ; <param> ... <command>`` | |
| 232 are silently stripped from the output on Windows. | |
| 233 | |
| 234 Any other form of ANSI sequence, such as single-character codes or alternative | |
| 235 initial characters, are not recognised nor stripped. It would be cool to add | |
| 236 them though. Let me know if it would be useful for you, via the issues on | |
| 237 google code. | |
| 238 | |
| 239 | |
| 240 Development | |
| 241 =========== | |
| 242 | |
| 243 Running tests requires: | |
| 244 | |
| 245 - Michael Foord's 'mock' module to be installed. | |
| 246 - Tests are written using the 2010 era updates to 'unittest', and require to | |
| 247 be run either using Python2.7 or greater, or else to have Michael Foord's | |
| 248 'unittest2' module installed. | |
| 249 | |
| 250 unittest2 test discovery doesn't work for colorama, so I use 'nose':: | |
| 251 | |
| 252 nosetests -s | |
| 253 | |
| 254 The -s is required because 'nosetests' otherwise applies a proxy of its own to | |
| 255 stdout, which confuses the unit tests. | |
| 256 | |
| 257 | |
| 258 Thanks | |
| 259 ====== | |
| 260 Daniel Griffith for multiple fabulous patches. | |
| 261 Oscar Lesta for valuable fix to stop ANSI chars being sent to non-tty output. | |
| 262 Roger Binns, for many suggestions, valuable feedback, & bug reports. | |
| 263 Tim Golden for thought and much appreciated feedback on the initial idea. | |
| 264 | |
| OLD | NEW |
|---|
Chromium Code Reviews
