src/colorama-0.3.7-py2.7.egg-info

   1 Metadata-Version: 1.1
   2 Name: colorama
   3 Version: 0.3.7
   4 Summary: Cross-platform colored terminal text.
   5 Home-page: https://github.com/tartley/colorama
   6 Author: Arnon Yaari
   7 Author-email: tartley@tartley.com
   8 License: BSD
   9 Description: .. image:: https://pypip.in/version/colorama/badge.svg
  10             :target: https://pypi.python.org/pypi/colorama/
  11             :alt: Latest Version
  12
  13         .. image:: https://travis-ci.org/tartley/colorama.svg?branch=master
  14             :target: https://travis-ci.org/tartley/colorama
  15             :alt: Build Status
  16
  17         Download and docs:
  18             http://pypi.python.org/pypi/colorama
  19         Source code & Development:
  20             https://github.com/tartley/colorama
  21
  22         Description
  23         ===========
  24
  25         Makes ANSI escape character sequences (for producing colored terminal text and
  26         cursor positioning) work under MS Windows.
  27
  28         ANSI escape character sequences have long been used to produce colored terminal
  29         text and cursor positioning on Unix and Macs. Colorama makes this work on
  30         Windows, too, by wrapping ``stdout``, stripping ANSI sequences it finds (which
  31         would appear as gobbledygook in the output), and converting them into the
  32         appropriate win32 calls to modify the state of the terminal. On other platforms,
  33         Colorama does nothing.
  34
  35         Colorama also provides some shortcuts to help generate ANSI sequences
  36         but works fine in conjunction with any other ANSI sequence generation library,
  37         such as the venerable Termcolor (http://pypi.python.org/pypi/termcolor)
  38         or the fabulous Blessings (https://pypi.python.org/pypi/blessings).
  39
  40         This has the upshot of providing a simple cross-platform API for printing
  41         colored terminal text from Python, and has the happy side-effect that existing
  42         applications or libraries which use ANSI sequences to produce colored output on
  43         Linux or Macs can now also work on Windows, simply by calling
  44         ``colorama.init()``.
  45
  46         An alternative approach is to install ``ansi.sys`` on Windows machines, which
  47         provides the same behaviour for all applications running in terminals. Colorama
  48         is intended for situations where that isn't easy (e.g., maybe your app doesn't
  49         have an installer.)
  50
  51         Demo scripts in the source code repository print some colored text using
  52         ANSI sequences. Compare their output under Gnome-terminal's built in ANSI
  53         handling, versus on Windows Command-Prompt using Colorama:
  54
  55         .. image:: https://github.com/tartley/colorama/raw/master/screenshots/ubuntu-demo.png
  56             :width: 661
  57             :height: 357
  58             :alt: ANSI sequences on Ubuntu under gnome-terminal.
  59
  60         .. image:: https://github.com/tartley/colorama/raw/master/screenshots/windows-demo.png
  61             :width: 668
  62             :height: 325
  63             :alt: Same ANSI sequences on Windows, using Colorama.
  64
  65         These screengrabs show that, on Windows, Colorama does not support ANSI 'dim
  66         text'; it looks the same as 'normal text'.
  67
  68
  69         License
  70         =======
  71
  72         Copyright Jonathan Hartley 2013. BSD 3-Clause license; see LICENSE file.
  73
  74
  75         Dependencies
  76         ============
  77
  78         None, other than Python. Tested on Python 2.5.5, 2.6.5, 2.7, 3.1.2, 3.2, 3.3,
  79         3.4 and 3.5.
  80
  81         Usage
  82         =====
  83
  84         Initialisation
  85         --------------
  86
  87         Applications should initialise Colorama using:
  88
  89         .. code-block:: python
  90
  91             from colorama import init
  92             init()
  93
  94         On Windows, calling ``init()`` will filter ANSI escape sequences out of any
  95         text sent to ``stdout`` or ``stderr``, and replace them with equivalent Win32
  96         calls.
  97
  98         On other platforms, calling ``init()`` has no effect (unless you request other
  99         optional functionality; see "Init Keyword Args", below). By design, this permits
 100         applications to call ``init()`` unconditionally on all platforms, after which
 101         ANSI output should just work.
 102
 103         To stop using colorama before your program exits, simply call ``deinit()``.
 104         This will restore ``stdout`` and ``stderr`` to their original values, so that
 105         Colorama is disabled. To resume using Colorama again, call ``reinit()``; it is
 106         cheaper to calling ``init()`` again (but does the same thing).
 107
 108
 109         Colored Output
 110         --------------
 111
 112         Cross-platform printing of colored text can then be done using Colorama's
 113         constant shorthand for ANSI escape sequences:
 114
 115         .. code-block:: python
 116
 117             from colorama import Fore, Back, Style
 118             print(Fore.RED + 'some red text')
 119             print(Back.GREEN + 'and with a green background')
 120             print(Style.DIM + 'and in dim text')
 121             print(Style.RESET_ALL)
 122             print('back to normal now')
 123
 124         ...or simply by manually printing ANSI sequences from your own code:
 125
 126         .. code-block:: python
 127
 128             print('\033[31m' + 'some red text')
 129             print('\033[30m') # and reset to default color
 130
 131         ...or, Colorama can be used happily in conjunction with existing ANSI libraries
 132         such as Termcolor:
 133
 134         .. code-block:: python
 135
 136             from colorama import init
 137             from termcolor import colored
 138
 139             # use Colorama to make Termcolor work on Windows too
 140             init()
 141
 142             # then use Termcolor for all colored text output
 143             print(colored('Hello, World!', 'green', 'on_red'))
 144
 145         Available formatting constants are::
 146
 147             Fore: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET.
 148             Back: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET.
 149             Style: DIM, NORMAL, BRIGHT, RESET_ALL
 150
 151         ``Style.RESET_ALL`` resets foreground, background, and brightness. Colorama will
 152         perform this reset automatically on program exit.
 153
 154
 155         Cursor Positioning
 156         ------------------
 157
 158         ANSI codes to reposition the cursor are supported. See ``demos/demo06.py`` for
 159         an example of how to generate them.
 160
 161
 162         Init Keyword Args
 163         -----------------
 164
 165         ``init()`` accepts some ``**kwargs`` to override default behaviour.
 166
 167         init(autoreset=False):
 168             If you find yourself repeatedly sending reset sequences to turn off color
 169             changes at the end of every print, then ``init(autoreset=True)`` will
 170             automate that:
 171
 172             .. code-block:: python
 173
 174                 from colorama import init
 175                 init(autoreset=True)
 176                 print(Fore.RED + 'some red text')
 177                 print('automatically back to default color again')
 178
 179         init(strip=None):
 180             Pass ``True`` or ``False`` to override whether ansi codes should be
 181             stripped from the output. The default behaviour is to strip if on Windows
 182             or if output is redirected (not a tty).
 183
 184         init(convert=None):
 185             Pass ``True`` or ``False`` to override whether to convert ANSI codes in the
 186             output into win32 calls. The default behaviour is to convert if on Windows
 187             and output is to a tty (terminal).
 188
 189         init(wrap=True):
 190             On Windows, colorama works by replacing ``sys.stdout`` and ``sys.stderr``
 191             with proxy objects, which override the ``.write()`` method to do their work.
 192             If this wrapping causes you problems, then this can be disabled by passing
 193             ``init(wrap=False)``. The default behaviour is to wrap if ``autoreset`` or
 194             ``strip`` or ``convert`` are True.
 195
 196             When wrapping is disabled, colored printing on non-Windows platforms will
 197             continue to work as normal. To do cross-platform colored output, you can
 198             use Colorama's ``AnsiToWin32`` proxy directly:
 199
 200             .. code-block:: python
 201
 202                 import sys
 203                 from colorama import init, AnsiToWin32
 204                 init(wrap=False)
 205                 stream = AnsiToWin32(sys.stderr).stream
 206
 207                 # Python 2
 208                 print >>stream, Fore.BLUE + 'blue text on stderr'
 209
 210                 # Python 3
 211                 print(Fore.BLUE + 'blue text on stderr', file=stream)
 212
 213
 214         Status & Known Problems
 215         =======================
 216
 217         I've personally only tested it on Windows XP (CMD, Console2), Ubuntu
 218         (gnome-terminal, xterm), and OS X.
 219
 220         Some presumably valid ANSI sequences aren't recognised (see details below),
 221         but to my knowledge nobody has yet complained about this. Puzzling.
 222
 223         See outstanding issues and wishlist:
 224         https://github.com/tartley/colorama/issues
 225
 226         If anything doesn't work for you, or doesn't do what you expected or hoped for,
 227         I'd love to hear about it on that issues list, would be delighted by patches,
 228         and would be happy to grant commit access to anyone who submits a working patch
 229         or two.
 230
 231
 232         Recognised ANSI Sequences
 233         =========================
 234
 235         ANSI sequences generally take the form:
 236
 237             ESC [ <param> ; <param> ... <command>
 238
 239         Where ``<param>`` is an integer, and ``<command>`` is a single letter. Zero or
 240         more params are passed to a ``<command>``. If no params are passed, it is
 241         generally synonymous with passing a single zero. No spaces exist in the
 242         sequence; they have been inserted here simply to read more easily.
 243
 244         The only ANSI sequences that colorama converts into win32 calls are::
 245
 246             ESC [ 0 m       # reset all (colors and brightness)
 247             ESC [ 1 m       # bright
 248             ESC [ 2 m       # dim (looks same as normal brightness)
 249             ESC [ 22 m      # normal brightness
 250
 251             # FOREGROUND:
 252             ESC [ 30 m      # black
 253             ESC [ 31 m      # red
 254             ESC [ 32 m      # green
 255             ESC [ 33 m      # yellow
 256             ESC [ 34 m      # blue
 257             ESC [ 35 m      # magenta
 258             ESC [ 36 m      # cyan
 259             ESC [ 37 m      # white
 260             ESC [ 39 m      # reset
 261
 262             # BACKGROUND
 263             ESC [ 40 m      # black
 264             ESC [ 41 m      # red
 265             ESC [ 42 m      # green
 266             ESC [ 43 m      # yellow
 267             ESC [ 44 m      # blue
 268             ESC [ 45 m      # magenta
 269             ESC [ 46 m      # cyan
 270             ESC [ 47 m      # white
 271             ESC [ 49 m      # reset
 272
 273             # cursor positioning
 274             ESC [ y;x H     # position cursor at x across, y down
 275             ESC [ y;x f     # position cursor at x across, y down
 276             ESC [ n A       # move cursor n lines up
 277             ESC [ n B       # move cursor n lines down
 278             ESC [ n C       # move cursor n characters forward
 279             ESC [ n D       # move cursor n characters backward
 280
 281             # clear the screen
 282             ESC [ mode J    # clear the screen
 283
 284             # clear the line
 285             ESC [ mode K    # clear the line
 286
 287         Multiple numeric params to the ``'m'`` command can be combined into a single
 288         sequence::
 289
 290             ESC [ 36 ; 45 ; 1 m     # bright cyan text on magenta background
 291
 292         All other ANSI sequences of the form ``ESC [ <param> ; <param> ... <command>``
 293         are silently stripped from the output on Windows.
 294
 295         Any other form of ANSI sequence, such as single-character codes or alternative
 296         initial characters, are not recognised or stripped. It would be cool to add
 297         them though. Let me know if it would be useful for you, via the Issues on
 298         GitHub.
 299
 300
 301         Development
 302         ===========
 303
 304         Help and fixes welcome!
 305
 306         Running tests requires:
 307
 308         - Michael Foord's ``mock`` module to be installed.
 309         - Tests are written using 2010-era updates to ``unittest``, and require
 310           Python 2.7 or greater, OR to have Michael Foord's ``unittest2`` module
 311           installed.
 312
 313         To run tests::
 314
 315            python -m unittest discover -p *_test.py
 316
 317         This, like a few other handy commands, is captured in a ``Makefile``.
 318
 319         If you use nose to run the tests, you must pass the ``-s`` flag; otherwise,
 320         ``nosetests`` applies its own proxy to ``stdout``, which confuses the unit
 321         tests.
 322
 323
 324         Thanks
 325         ======
 326         * Marc Schlaich (schlamar) for a ``setup.py`` fix for Python2.5.
 327         * Marc Abramowitz, reported & fixed a crash on exit with closed ``stdout``,
 328           providing a solution to issue #7's setuptools/distutils debate,
 329           and other fixes.
 330         * User 'eryksun', for guidance on correctly instantiating ``ctypes.windll``.
 331         * Matthew McCormick for politely pointing out a longstanding crash on non-Win.
 332         * Ben Hoyt, for a magnificent fix under 64-bit Windows.
 333         * Jesse at Empty Square for submitting a fix for examples in the README.
 334         * User 'jamessp', an observant documentation fix for cursor positioning.
 335         * User 'vaal1239', Dave Mckee & Lackner Kristof for a tiny but much-needed Win7
 336           fix.
 337         * Julien Stuyck, for wisely suggesting Python3 compatible updates to README.
 338         * Daniel Griffith for multiple fabulous patches.
 339         * Oscar Lesta for a valuable fix to stop ANSI chars being sent to non-tty
 340           output.
 341         * Roger Binns, for many suggestions, valuable feedback, & bug reports.
 342         * Tim Golden for thought and much appreciated feedback on the initial idea.
 343         * User 'Zearin' for updates to the README file.
 344         * John Szakmeister for adding support for light colors
 345         * Charles Merriam for adding documentation to demos
 346         * Jurko for a fix on 64-bit Windows CPython2.5 w/o ctypes
 347         * Florian Bruhin for a fix when stdout or stderr are None
 348         * Thomas Weininger for fixing ValueError on Windows
 349         * Remi Rampin for better Github integration and fixes to the README file
 350         * Simeon Visser for closing a file handle using 'with' and updating classifiers
 351           to include Python 3.3 and 3.4
 352         * Andy Neff for fixing RESET of LIGHT_EX colors.
 353         * Jonathan Hartley for the initial idea and implementation.
 354
 355
 356 Keywords: color colour terminal text ansi windows crossplatform xplatform
 357 Platform: UNKNOWN
 358 Classifier: Development Status :: 5 - Production/Stable
 359 Classifier: Environment :: Console
 360 Classifier: Intended Audience :: Developers
 361 Classifier: License :: OSI Approved :: BSD License
 362 Classifier: Operating System :: OS Independent
 363 Classifier: Programming Language :: Python :: 2
 364 Classifier: Programming Language :: Python :: 2.5
 365 Classifier: Programming Language :: Python :: 2.6
 366 Classifier: Programming Language :: Python :: 2.7
 367 Classifier: Programming Language :: Python :: 3
 368 Classifier: Programming Language :: Python :: 3.1
 369 Classifier: Programming Language :: Python :: 3.2
 370 Classifier: Programming Language :: Python :: 3.3
 371 Classifier: Programming Language :: Python :: 3.4
 372 Classifier: Programming Language :: Python :: 3.5
 373 Classifier: Topic :: Terminals