| 1 |
Metadata-Version: 2.1 |
| 2 |
Name: colorama |
| 3 |
Version: 0.4.6 |
| 4 |
Summary: Cross-platform colored terminal text. |
| 5 |
Project-URL: Homepage, https://github.com/tartley/colorama |
| 6 |
Author-email: Jonathan Hartley <[email protected]> |
| 7 |
License-File: LICENSE.txt |
| 8 |
Keywords: ansi,color,colour,crossplatform,terminal,text,windows,xplatform |
| 9 |
Classifier: Development Status :: 5 - Production/Stable |
| 10 |
Classifier: Environment :: Console |
| 11 |
Classifier: Intended Audience :: Developers |
| 12 |
Classifier: License :: OSI Approved :: BSD License |
| 13 |
Classifier: Operating System :: OS Independent |
| 14 |
Classifier: Programming Language :: Python |
| 15 |
Classifier: Programming Language :: Python :: 2 |
| 16 |
Classifier: Programming Language :: Python :: 2.7 |
| 17 |
Classifier: Programming Language :: Python :: 3 |
| 18 |
Classifier: Programming Language :: Python :: 3.7 |
| 19 |
Classifier: Programming Language :: Python :: 3.8 |
| 20 |
Classifier: Programming Language :: Python :: 3.9 |
| 21 |
Classifier: Programming Language :: Python :: 3.10 |
| 22 |
Classifier: Programming Language :: Python :: Implementation :: CPython |
| 23 |
Classifier: Programming Language :: Python :: Implementation :: PyPy |
| 24 |
Classifier: Topic :: Terminals |
| 25 |
Requires-Python: !=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7 |
| 26 |
Description-Content-Type: text/x-rst |
| 27 |
|
| 28 |
.. image:: https://img.shields.io/pypi/v/colorama.svg |
| 29 |
:target: https://pypi.org/project/colorama/ |
| 30 |
:alt: Latest Version |
| 31 |
|
| 32 |
.. image:: https://img.shields.io/pypi/pyversions/colorama.svg |
| 33 |
:target: https://pypi.org/project/colorama/ |
| 34 |
:alt: Supported Python versions |
| 35 |
|
| 36 |
.. image:: https://github.com/tartley/colorama/actions/workflows/test.yml/badge.svg |
| 37 |
:target: https://github.com/tartley/colorama/actions/workflows/test.yml |
| 38 |
:alt: Build Status |
| 39 |
|
| 40 |
Colorama |
| 41 |
======== |
| 42 |
|
| 43 |
Makes ANSI escape character sequences (for producing colored terminal text and |
| 44 |
cursor positioning) work under MS Windows. |
| 45 |
|
| 46 |
.. |donate| image:: https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif |
| 47 |
:target: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=2MZ9D2GMLYCUJ&item_name=Colorama¤cy_code=USD |
| 48 |
:alt: Donate with Paypal |
| 49 |
|
| 50 |
`PyPI for releases <https://pypi.org/project/colorama/>`_ | |
| 51 |
`Github for source <https://github.com/tartley/colorama>`_ | |
| 52 |
`Colorama for enterprise on Tidelift <https://github.com/tartley/colorama/blob/master/ENTERPRISE.md>`_ |
| 53 |
|
| 54 |
If you find Colorama useful, please |donate| to the authors. Thank you! |
| 55 |
|
| 56 |
Installation |
| 57 |
------------ |
| 58 |
|
| 59 |
Tested on CPython 2.7, 3.7, 3.8, 3.9 and 3.10 and Pypy 2.7 and 3.8. |
| 60 |
|
| 61 |
No requirements other than the standard library. |
| 62 |
|
| 63 |
.. code-block:: bash |
| 64 |
|
| 65 |
pip install colorama |
| 66 |
# or |
| 67 |
conda install -c anaconda colorama |
| 68 |
|
| 69 |
Description |
| 70 |
----------- |
| 71 |
|
| 72 |
ANSI escape character sequences have long been used to produce colored terminal |
| 73 |
text and cursor positioning on Unix and Macs. Colorama makes this work on |
| 74 |
Windows, too, by wrapping ``stdout``, stripping ANSI sequences it finds (which |
| 75 |
would appear as gobbledygook in the output), and converting them into the |
| 76 |
appropriate win32 calls to modify the state of the terminal. On other platforms, |
| 77 |
Colorama does nothing. |
| 78 |
|
| 79 |
This has the upshot of providing a simple cross-platform API for printing |
| 80 |
colored terminal text from Python, and has the happy side-effect that existing |
| 81 |
applications or libraries which use ANSI sequences to produce colored output on |
| 82 |
Linux or Macs can now also work on Windows, simply by calling |
| 83 |
``colorama.just_fix_windows_console()`` (since v0.4.6) or ``colorama.init()`` |
| 84 |
(all versions, but may have other side-effects – see below). |
| 85 |
|
| 86 |
An alternative approach is to install ``ansi.sys`` on Windows machines, which |
| 87 |
provides the same behaviour for all applications running in terminals. Colorama |
| 88 |
is intended for situations where that isn't easy (e.g., maybe your app doesn't |
| 89 |
have an installer.) |
| 90 |
|
| 91 |
Demo scripts in the source code repository print some colored text using |
| 92 |
ANSI sequences. Compare their output under Gnome-terminal's built in ANSI |
| 93 |
handling, versus on Windows Command-Prompt using Colorama: |
| 94 |
|
| 95 |
.. image:: https://github.com/tartley/colorama/raw/master/screenshots/ubuntu-demo.png |
| 96 |
:width: 661 |
| 97 |
:height: 357 |
| 98 |
:alt: ANSI sequences on Ubuntu under gnome-terminal. |
| 99 |
|
| 100 |
.. image:: https://github.com/tartley/colorama/raw/master/screenshots/windows-demo.png |
| 101 |
:width: 668 |
| 102 |
:height: 325 |
| 103 |
:alt: Same ANSI sequences on Windows, using Colorama. |
| 104 |
|
| 105 |
These screenshots show that, on Windows, Colorama does not support ANSI 'dim |
| 106 |
text'; it looks the same as 'normal text'. |
| 107 |
|
| 108 |
Usage |
| 109 |
----- |
| 110 |
|
| 111 |
Initialisation |
| 112 |
.............. |
| 113 |
|
| 114 |
If the only thing you want from Colorama is to get ANSI escapes to work on |
| 115 |
Windows, then run: |
| 116 |
|
| 117 |
.. code-block:: python |
| 118 |
|
| 119 |
from colorama import just_fix_windows_console |
| 120 |
just_fix_windows_console() |
| 121 |
|
| 122 |
If you're on a recent version of Windows 10 or better, and your stdout/stderr |
| 123 |
are pointing to a Windows console, then this will flip the magic configuration |
| 124 |
switch to enable Windows' built-in ANSI support. |
| 125 |
|
| 126 |
If you're on an older version of Windows, and your stdout/stderr are pointing to |
| 127 |
a Windows console, then this will wrap ``sys.stdout`` and/or ``sys.stderr`` in a |
| 128 |
magic file object that intercepts ANSI escape sequences and issues the |
| 129 |
appropriate Win32 calls to emulate them. |
| 130 |
|
| 131 |
In all other circumstances, it does nothing whatsoever. Basically the idea is |
| 132 |
that this makes Windows act like Unix with respect to ANSI escape handling. |
| 133 |
|
| 134 |
It's safe to call this function multiple times. It's safe to call this function |
| 135 |
on non-Windows platforms, but it won't do anything. It's safe to call this |
| 136 |
function when one or both of your stdout/stderr are redirected to a file – it |
| 137 |
won't do anything to those streams. |
| 138 |
|
| 139 |
Alternatively, you can use the older interface with more features (but also more |
| 140 |
potential footguns): |
| 141 |
|
| 142 |
.. code-block:: python |
| 143 |
|
| 144 |
from colorama import init |
| 145 |
init() |
| 146 |
|
| 147 |
This does the same thing as ``just_fix_windows_console``, except for the |
| 148 |
following differences: |
| 149 |
|
| 150 |
- It's not safe to call ``init`` multiple times; you can end up with multiple |
| 151 |
layers of wrapping and broken ANSI support. |
| 152 |
|
| 153 |
- Colorama will apply a heuristic to guess whether stdout/stderr support ANSI, |
| 154 |
and if it thinks they don't, then it will wrap ``sys.stdout`` and |
| 155 |
``sys.stderr`` in a magic file object that strips out ANSI escape sequences |
| 156 |
before printing them. This happens on all platforms, and can be convenient if |
| 157 |
you want to write your code to emit ANSI escape sequences unconditionally, and |
| 158 |
let Colorama decide whether they should actually be output. But note that |
| 159 |
Colorama's heuristic is not particularly clever. |
| 160 |
|
| 161 |
- ``init`` also accepts explicit keyword args to enable/disable various |
| 162 |
functionality – see below. |
| 163 |
|
| 164 |
To stop using Colorama before your program exits, simply call ``deinit()``. |
| 165 |
This will restore ``stdout`` and ``stderr`` to their original values, so that |
| 166 |
Colorama is disabled. To resume using Colorama again, call ``reinit()``; it is |
| 167 |
cheaper than calling ``init()`` again (but does the same thing). |
| 168 |
|
| 169 |
Most users should depend on ``colorama >= 0.4.6``, and use |
| 170 |
``just_fix_windows_console``. The old ``init`` interface will be supported |
| 171 |
indefinitely for backwards compatibility, but we don't plan to fix any issues |
| 172 |
with it, also for backwards compatibility. |
| 173 |
|
| 174 |
Colored Output |
| 175 |
.............. |
| 176 |
|
| 177 |
Cross-platform printing of colored text can then be done using Colorama's |
| 178 |
constant shorthand for ANSI escape sequences. These are deliberately |
| 179 |
rudimentary, see below. |
| 180 |
|
| 181 |
.. code-block:: python |
| 182 |
|
| 183 |
from colorama import Fore, Back, Style |
| 184 |
print(Fore.RED + 'some red text') |
| 185 |
print(Back.GREEN + 'and with a green background') |
| 186 |
print(Style.DIM + 'and in dim text') |
| 187 |
print(Style.RESET_ALL) |
| 188 |
print('back to normal now') |
| 189 |
|
| 190 |
...or simply by manually printing ANSI sequences from your own code: |
| 191 |
|
| 192 |
.. code-block:: python |
| 193 |
|
| 194 |
print('\033[31m' + 'some red text') |
| 195 |
print('\033[39m') # and reset to default color |
| 196 |
|
| 197 |
...or, Colorama can be used in conjunction with existing ANSI libraries |
| 198 |
such as the venerable `Termcolor <https://pypi.org/project/termcolor/>`_ |
| 199 |
the fabulous `Blessings <https://pypi.org/project/blessings/>`_, |
| 200 |
or the incredible `_Rich <https://pypi.org/project/rich/>`_. |
| 201 |
|
| 202 |
If you wish Colorama's Fore, Back and Style constants were more capable, |
| 203 |
then consider using one of the above highly capable libraries to generate |
| 204 |
colors, etc, and use Colorama just for its primary purpose: to convert |
| 205 |
those ANSI sequences to also work on Windows: |
| 206 |
|
| 207 |
SIMILARLY, do not send PRs adding the generation of new ANSI types to Colorama. |
| 208 |
We are only interested in converting ANSI codes to win32 API calls, not |
| 209 |
shortcuts like the above to generate ANSI characters. |
| 210 |
|
| 211 |
.. code-block:: python |
| 212 |
|
| 213 |
from colorama import just_fix_windows_console |
| 214 |
from termcolor import colored |
| 215 |
|
| 216 |
# use Colorama to make Termcolor work on Windows too |
| 217 |
just_fix_windows_console() |
| 218 |
|
| 219 |
# then use Termcolor for all colored text output |
| 220 |
print(colored('Hello, World!', 'green', 'on_red')) |
| 221 |
|
| 222 |
Available formatting constants are:: |
| 223 |
|
| 224 |
Fore: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET. |
| 225 |
Back: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET. |
| 226 |
Style: DIM, NORMAL, BRIGHT, RESET_ALL |
| 227 |
|
| 228 |
``Style.RESET_ALL`` resets foreground, background, and brightness. Colorama will |
| 229 |
perform this reset automatically on program exit. |
| 230 |
|
| 231 |
These are fairly well supported, but not part of the standard:: |
| 232 |
|
| 233 |
Fore: LIGHTBLACK_EX, LIGHTRED_EX, LIGHTGREEN_EX, LIGHTYELLOW_EX, LIGHTBLUE_EX, LIGHTMAGENTA_EX, LIGHTCYAN_EX, LIGHTWHITE_EX |
| 234 |
Back: LIGHTBLACK_EX, LIGHTRED_EX, LIGHTGREEN_EX, LIGHTYELLOW_EX, LIGHTBLUE_EX, LIGHTMAGENTA_EX, LIGHTCYAN_EX, LIGHTWHITE_EX |
| 235 |
|
| 236 |
Cursor Positioning |
| 237 |
.................. |
| 238 |
|
| 239 |
ANSI codes to reposition the cursor are supported. See ``demos/demo06.py`` for |
| 240 |
an example of how to generate them. |
| 241 |
|
| 242 |
Init Keyword Args |
| 243 |
................. |
| 244 |
|
| 245 |
``init()`` accepts some ``**kwargs`` to override default behaviour. |
| 246 |
|
| 247 |
init(autoreset=False): |
| 248 |
If you find yourself repeatedly sending reset sequences to turn off color |
| 249 |
changes at the end of every print, then ``init(autoreset=True)`` will |
| 250 |
automate that: |
| 251 |
|
| 252 |
.. code-block:: python |
| 253 |
|
| 254 |
from colorama import init |
| 255 |
init(autoreset=True) |
| 256 |
print(Fore.RED + 'some red text') |
| 257 |
print('automatically back to default color again') |
| 258 |
|
| 259 |
init(strip=None): |
| 260 |
Pass ``True`` or ``False`` to override whether ANSI codes should be |
| 261 |
stripped from the output. The default behaviour is to strip if on Windows |
| 262 |
or if output is redirected (not a tty). |
| 263 |
|
| 264 |
init(convert=None): |
| 265 |
Pass ``True`` or ``False`` to override whether to convert ANSI codes in the |
| 266 |
output into win32 calls. The default behaviour is to convert if on Windows |
| 267 |
and output is to a tty (terminal). |
| 268 |
|
| 269 |
init(wrap=True): |
| 270 |
On Windows, Colorama works by replacing ``sys.stdout`` and ``sys.stderr`` |
| 271 |
with proxy objects, which override the ``.write()`` method to do their work. |
| 272 |
If this wrapping causes you problems, then this can be disabled by passing |
| 273 |
``init(wrap=False)``. The default behaviour is to wrap if ``autoreset`` or |
| 274 |
``strip`` or ``convert`` are True. |
| 275 |
|
| 276 |
When wrapping is disabled, colored printing on non-Windows platforms will |
| 277 |
continue to work as normal. To do cross-platform colored output, you can |
| 278 |
use Colorama's ``AnsiToWin32`` proxy directly: |
| 279 |
|
| 280 |
.. code-block:: python |
| 281 |
|
| 282 |
import sys |
| 283 |
from colorama import init, AnsiToWin32 |
| 284 |
init(wrap=False) |
| 285 |
stream = AnsiToWin32(sys.stderr).stream |
| 286 |
|
| 287 |
# Python 2 |
| 288 |
print >>stream, Fore.BLUE + 'blue text on stderr' |
| 289 |
|
| 290 |
# Python 3 |
| 291 |
print(Fore.BLUE + 'blue text on stderr', file=stream) |
| 292 |
|
| 293 |
Recognised ANSI Sequences |
| 294 |
......................... |
| 295 |
|
| 296 |
ANSI sequences generally take the form:: |
| 297 |
|
| 298 |
ESC [ <param> ; <param> ... <command> |
| 299 |
|
| 300 |
Where ``<param>`` is an integer, and ``<command>`` is a single letter. Zero or |
| 301 |
more params are passed to a ``<command>``. If no params are passed, it is |
| 302 |
generally synonymous with passing a single zero. No spaces exist in the |
| 303 |
sequence; they have been inserted here simply to read more easily. |
| 304 |
|
| 305 |
The only ANSI sequences that Colorama converts into win32 calls are:: |
| 306 |
|
| 307 |
ESC [ 0 m # reset all (colors and brightness) |
| 308 |
ESC [ 1 m # bright |
| 309 |
ESC [ 2 m # dim (looks same as normal brightness) |
| 310 |
ESC [ 22 m # normal brightness |
| 311 |
|
| 312 |
# FOREGROUND: |
| 313 |
ESC [ 30 m # black |
| 314 |
ESC [ 31 m # red |
| 315 |
ESC [ 32 m # green |
| 316 |
ESC [ 33 m # yellow |
| 317 |
ESC [ 34 m # blue |
| 318 |
ESC [ 35 m # magenta |
| 319 |
ESC [ 36 m # cyan |
| 320 |
ESC [ 37 m # white |
| 321 |
ESC [ 39 m # reset |
| 322 |
|
| 323 |
# BACKGROUND |
| 324 |
ESC [ 40 m # black |
| 325 |
ESC [ 41 m # red |
| 326 |
ESC [ 42 m # green |
| 327 |
ESC [ 43 m # yellow |
| 328 |
ESC [ 44 m # blue |
| 329 |
ESC [ 45 m # magenta |
| 330 |
ESC [ 46 m # cyan |
| 331 |
ESC [ 47 m # white |
| 332 |
ESC [ 49 m # reset |
| 333 |
|
| 334 |
# cursor positioning |
| 335 |
ESC [ y;x H # position cursor at x across, y down |
| 336 |
ESC [ y;x f # position cursor at x across, y down |
| 337 |
ESC [ n A # move cursor n lines up |
| 338 |
ESC [ n B # move cursor n lines down |
| 339 |
ESC [ n C # move cursor n characters forward |
| 340 |
ESC [ n D # move cursor n characters backward |
| 341 |
|
| 342 |
# clear the screen |
| 343 |
ESC [ mode J # clear the screen |
| 344 |
|
| 345 |
# clear the line |
| 346 |
ESC [ mode K # clear the line |
| 347 |
|
| 348 |
Multiple numeric params to the ``'m'`` command can be combined into a single |
| 349 |
sequence:: |
| 350 |
|
| 351 |
ESC [ 36 ; 45 ; 1 m # bright cyan text on magenta background |
| 352 |
|
| 353 |
All other ANSI sequences of the form ``ESC [ <param> ; <param> ... <command>`` |
| 354 |
are silently stripped from the output on Windows. |
| 355 |
|
| 356 |
Any other form of ANSI sequence, such as single-character codes or alternative |
| 357 |
initial characters, are not recognised or stripped. It would be cool to add |
| 358 |
them though. Let me know if it would be useful for you, via the Issues on |
| 359 |
GitHub. |
| 360 |
|
| 361 |
Status & Known Problems |
| 362 |
----------------------- |
| 363 |
|
| 364 |
I've personally only tested it on Windows XP (CMD, Console2), Ubuntu |
| 365 |
(gnome-terminal, xterm), and OS X. |
| 366 |
|
| 367 |
Some valid ANSI sequences aren't recognised. |
| 368 |
|
| 369 |
If you're hacking on the code, see `README-hacking.md`_. ESPECIALLY, see the |
| 370 |
explanation there of why we do not want PRs that allow Colorama to generate new |
| 371 |
types of ANSI codes. |
| 372 |
|
| 373 |
See outstanding issues and wish-list: |
| 374 |
https://github.com/tartley/colorama/issues |
| 375 |
|
| 376 |
If anything doesn't work for you, or doesn't do what you expected or hoped for, |
| 377 |
I'd love to hear about it on that issues list, would be delighted by patches, |
| 378 |
and would be happy to grant commit access to anyone who submits a working patch |
| 379 |
or two. |
| 380 |
|
| 381 |
.. _README-hacking.md: README-hacking.md |
| 382 |
|
| 383 |
License |
| 384 |
------- |
| 385 |
|
| 386 |
Copyright Jonathan Hartley & Arnon Yaari, 2013-2020. BSD 3-Clause license; see |
| 387 |
LICENSE file. |
| 388 |
|
| 389 |
Professional support |
| 390 |
-------------------- |
| 391 |
|
| 392 |
.. |tideliftlogo| image:: https://cdn2.hubspot.net/hubfs/4008838/website/logos/logos_for_download/Tidelift_primary-shorthand-logo.png |
| 393 |
:alt: Tidelift |
| 394 |
:target: https://tidelift.com/subscription/pkg/pypi-colorama?utm_source=pypi-colorama&utm_medium=referral&utm_campaign=readme |
| 395 |
|
| 396 |
.. list-table:: |
| 397 |
:widths: 10 100 |
| 398 |
|
| 399 |
* - |tideliftlogo| |
| 400 |
- Professional support for colorama is available as part of the |
| 401 |
`Tidelift Subscription`_. |
| 402 |
Tidelift gives software development teams a single source for purchasing |
| 403 |
and maintaining their software, with professional grade assurances from |
| 404 |
the experts who know it best, while seamlessly integrating with existing |
| 405 |
tools. |
| 406 |
|
| 407 |
.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-colorama?utm_source=pypi-colorama&utm_medium=referral&utm_campaign=readme |
| 408 |
|
| 409 |
Thanks |
| 410 |
------ |
| 411 |
|
| 412 |
See the CHANGELOG for more thanks! |
| 413 |
|
| 414 |
* Marc Schlaich (schlamar) for a ``setup.py`` fix for Python2.5. |
| 415 |
* Marc Abramowitz, reported & fixed a crash on exit with closed ``stdout``, |
| 416 |
providing a solution to issue #7's setuptools/distutils debate, |
| 417 |
and other fixes. |
| 418 |
* User 'eryksun', for guidance on correctly instantiating ``ctypes.windll``. |
| 419 |
* Matthew McCormick for politely pointing out a longstanding crash on non-Win. |
| 420 |
* Ben Hoyt, for a magnificent fix under 64-bit Windows. |
| 421 |
* Jesse at Empty Square for submitting a fix for examples in the README. |
| 422 |
* User 'jamessp', an observant documentation fix for cursor positioning. |
| 423 |
* User 'vaal1239', Dave Mckee & Lackner Kristof for a tiny but much-needed Win7 |
| 424 |
fix. |
| 425 |
* Julien Stuyck, for wisely suggesting Python3 compatible updates to README. |
| 426 |
* Daniel Griffith for multiple fabulous patches. |
| 427 |
* Oscar Lesta for a valuable fix to stop ANSI chars being sent to non-tty |
| 428 |
output. |
| 429 |
* Roger Binns, for many suggestions, valuable feedback, & bug reports. |
| 430 |
* Tim Golden for thought and much appreciated feedback on the initial idea. |
| 431 |
* User 'Zearin' for updates to the README file. |
| 432 |
* John Szakmeister for adding support for light colors |
| 433 |
* Charles Merriam for adding documentation to demos |
| 434 |
* Jurko for a fix on 64-bit Windows CPython2.5 w/o ctypes |
| 435 |
* Florian Bruhin for a fix when stdout or stderr are None |
| 436 |
* Thomas Weininger for fixing ValueError on Windows |
| 437 |
* Remi Rampin for better Github integration and fixes to the README file |
| 438 |
* Simeon Visser for closing a file handle using 'with' and updating classifiers |
| 439 |
to include Python 3.3 and 3.4 |
| 440 |
* Andy Neff for fixing RESET of LIGHT_EX colors. |
| 441 |
* Jonathan Hartley for the initial idea and implementation. |