METADATA 13 KB

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