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 |