416 lines
14 KiB
Plaintext
416 lines
14 KiB
Plaintext
Metadata-Version: 2.1
|
|
Name: colorama
|
|
Version: 0.4.4
|
|
Summary: Cross-platform colored terminal text.
|
|
Home-page: https://github.com/tartley/colorama
|
|
Author: Jonathan Hartley
|
|
Author-email: tartley@tartley.com
|
|
Maintainer: Arnon Yaari
|
|
License: BSD
|
|
Keywords: color colour terminal text ansi windows crossplatform xplatform
|
|
Platform: UNKNOWN
|
|
Classifier: Development Status :: 5 - Production/Stable
|
|
Classifier: Environment :: Console
|
|
Classifier: Intended Audience :: Developers
|
|
Classifier: License :: OSI Approved :: BSD License
|
|
Classifier: Operating System :: OS Independent
|
|
Classifier: Programming Language :: Python
|
|
Classifier: Programming Language :: Python :: 2
|
|
Classifier: Programming Language :: Python :: 2.7
|
|
Classifier: Programming Language :: Python :: 3
|
|
Classifier: Programming Language :: Python :: 3.5
|
|
Classifier: Programming Language :: Python :: 3.6
|
|
Classifier: Programming Language :: Python :: 3.7
|
|
Classifier: Programming Language :: Python :: 3.8
|
|
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
Classifier: Programming Language :: Python :: Implementation :: PyPy
|
|
Classifier: Topic :: Terminals
|
|
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*
|
|
|
|
.. image:: https://img.shields.io/pypi/v/colorama.svg
|
|
:target: https://pypi.org/project/colorama/
|
|
:alt: Latest Version
|
|
|
|
.. image:: https://img.shields.io/pypi/pyversions/colorama.svg
|
|
:target: https://pypi.org/project/colorama/
|
|
:alt: Supported Python versions
|
|
|
|
.. image:: https://travis-ci.org/tartley/colorama.svg?branch=master
|
|
:target: https://travis-ci.org/tartley/colorama
|
|
:alt: Build Status
|
|
|
|
Colorama
|
|
========
|
|
|
|
Makes ANSI escape character sequences (for producing colored terminal text and
|
|
cursor positioning) work under MS Windows.
|
|
|
|
.. |donate| image:: https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif
|
|
:target: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=2MZ9D2GMLYCUJ&item_name=Colorama¤cy_code=USD
|
|
:alt: Donate with Paypal
|
|
|
|
`PyPI for releases <https://pypi.org/project/colorama/>`_ ·
|
|
`Github for source <https://github.com/tartley/colorama>`_ ·
|
|
`Colorama for enterprise on Tidelift <https://github.com/tartley/colorama/blob/master/ENTERPRISE.md>`_
|
|
|
|
If you find Colorama useful, please |donate| to the authors. Thank you!
|
|
|
|
|
|
Installation
|
|
------------
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install colorama
|
|
# or
|
|
conda install -c anaconda colorama
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
ANSI escape character sequences have long been used to produce colored terminal
|
|
text and cursor positioning on Unix and Macs. Colorama makes this work on
|
|
Windows, too, by wrapping ``stdout``, stripping ANSI sequences it finds (which
|
|
would appear as gobbledygook in the output), and converting them into the
|
|
appropriate win32 calls to modify the state of the terminal. On other platforms,
|
|
Colorama does nothing.
|
|
|
|
This has the upshot of providing a simple cross-platform API for printing
|
|
colored terminal text from Python, and has the happy side-effect that existing
|
|
applications or libraries which use ANSI sequences to produce colored output on
|
|
Linux or Macs can now also work on Windows, simply by calling
|
|
``colorama.init()``.
|
|
|
|
An alternative approach is to install ``ansi.sys`` on Windows machines, which
|
|
provides the same behaviour for all applications running in terminals. Colorama
|
|
is intended for situations where that isn't easy (e.g., maybe your app doesn't
|
|
have an installer.)
|
|
|
|
Demo scripts in the source code repository print some colored text using
|
|
ANSI sequences. Compare their output under Gnome-terminal's built in ANSI
|
|
handling, versus on Windows Command-Prompt using Colorama:
|
|
|
|
.. image:: https://github.com/tartley/colorama/raw/master/screenshots/ubuntu-demo.png
|
|
:width: 661
|
|
:height: 357
|
|
:alt: ANSI sequences on Ubuntu under gnome-terminal.
|
|
|
|
.. image:: https://github.com/tartley/colorama/raw/master/screenshots/windows-demo.png
|
|
:width: 668
|
|
:height: 325
|
|
:alt: Same ANSI sequences on Windows, using Colorama.
|
|
|
|
These screenshots show that, on Windows, Colorama does not support ANSI 'dim
|
|
text'; it looks the same as 'normal text'.
|
|
|
|
Usage
|
|
-----
|
|
|
|
Initialisation
|
|
..............
|
|
|
|
Applications should initialise Colorama using:
|
|
|
|
.. code-block:: python
|
|
|
|
from colorama import init
|
|
init()
|
|
|
|
On Windows, calling ``init()`` will filter ANSI escape sequences out of any
|
|
text sent to ``stdout`` or ``stderr``, and replace them with equivalent Win32
|
|
calls.
|
|
|
|
On other platforms, calling ``init()`` has no effect (unless you request other
|
|
optional functionality; see "Init Keyword Args", below). By design, this permits
|
|
applications to call ``init()`` unconditionally on all platforms, after which
|
|
ANSI output should just work.
|
|
|
|
To stop using Colorama before your program exits, simply call ``deinit()``.
|
|
This will restore ``stdout`` and ``stderr`` to their original values, so that
|
|
Colorama is disabled. To resume using Colorama again, call ``reinit()``; it is
|
|
cheaper than calling ``init()`` again (but does the same thing).
|
|
|
|
|
|
Colored Output
|
|
..............
|
|
|
|
Cross-platform printing of colored text can then be done using Colorama's
|
|
constant shorthand for ANSI escape sequences:
|
|
|
|
.. code-block:: python
|
|
|
|
from colorama import Fore, Back, Style
|
|
print(Fore.RED + 'some red text')
|
|
print(Back.GREEN + 'and with a green background')
|
|
print(Style.DIM + 'and in dim text')
|
|
print(Style.RESET_ALL)
|
|
print('back to normal now')
|
|
|
|
...or simply by manually printing ANSI sequences from your own code:
|
|
|
|
.. code-block:: python
|
|
|
|
print('\033[31m' + 'some red text')
|
|
print('\033[39m') # and reset to default color
|
|
|
|
...or, Colorama can be used in conjunction with existing ANSI libraries
|
|
such as the venerable `Termcolor <https://pypi.org/project/termcolor/>`_
|
|
or the fabulous `Blessings <https://pypi.org/project/blessings/>`_.
|
|
This is highly recommended for anything more than trivial coloring:
|
|
|
|
.. code-block:: python
|
|
|
|
from colorama import init
|
|
from termcolor import colored
|
|
|
|
# use Colorama to make Termcolor work on Windows too
|
|
init()
|
|
|
|
# then use Termcolor for all colored text output
|
|
print(colored('Hello, World!', 'green', 'on_red'))
|
|
|
|
Available formatting constants are::
|
|
|
|
Fore: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET.
|
|
Back: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET.
|
|
Style: DIM, NORMAL, BRIGHT, RESET_ALL
|
|
|
|
``Style.RESET_ALL`` resets foreground, background, and brightness. Colorama will
|
|
perform this reset automatically on program exit.
|
|
|
|
|
|
Cursor Positioning
|
|
..................
|
|
|
|
ANSI codes to reposition the cursor are supported. See ``demos/demo06.py`` for
|
|
an example of how to generate them.
|
|
|
|
|
|
Init Keyword Args
|
|
.................
|
|
|
|
``init()`` accepts some ``**kwargs`` to override default behaviour.
|
|
|
|
init(autoreset=False):
|
|
If you find yourself repeatedly sending reset sequences to turn off color
|
|
changes at the end of every print, then ``init(autoreset=True)`` will
|
|
automate that:
|
|
|
|
.. code-block:: python
|
|
|
|
from colorama import init
|
|
init(autoreset=True)
|
|
print(Fore.RED + 'some red text')
|
|
print('automatically back to default color again')
|
|
|
|
init(strip=None):
|
|
Pass ``True`` or ``False`` to override whether ANSI codes should be
|
|
stripped from the output. The default behaviour is to strip if on Windows
|
|
or if output is redirected (not a tty).
|
|
|
|
init(convert=None):
|
|
Pass ``True`` or ``False`` to override whether to convert ANSI codes in the
|
|
output into win32 calls. The default behaviour is to convert if on Windows
|
|
and output is to a tty (terminal).
|
|
|
|
init(wrap=True):
|
|
On Windows, Colorama works by replacing ``sys.stdout`` and ``sys.stderr``
|
|
with proxy objects, which override the ``.write()`` method to do their work.
|
|
If this wrapping causes you problems, then this can be disabled by passing
|
|
``init(wrap=False)``. The default behaviour is to wrap if ``autoreset`` or
|
|
``strip`` or ``convert`` are True.
|
|
|
|
When wrapping is disabled, colored printing on non-Windows platforms will
|
|
continue to work as normal. To do cross-platform colored output, you can
|
|
use Colorama's ``AnsiToWin32`` proxy directly:
|
|
|
|
.. code-block:: python
|
|
|
|
import sys
|
|
from colorama import init, AnsiToWin32
|
|
init(wrap=False)
|
|
stream = AnsiToWin32(sys.stderr).stream
|
|
|
|
# Python 2
|
|
print >>stream, Fore.BLUE + 'blue text on stderr'
|
|
|
|
# Python 3
|
|
print(Fore.BLUE + 'blue text on stderr', file=stream)
|
|
|
|
|
|
Recognised ANSI Sequences
|
|
.........................
|
|
|
|
ANSI sequences generally take the form::
|
|
|
|
ESC [ <param> ; <param> ... <command>
|
|
|
|
Where ``<param>`` is an integer, and ``<command>`` is a single letter. Zero or
|
|
more params are passed to a ``<command>``. If no params are passed, it is
|
|
generally synonymous with passing a single zero. No spaces exist in the
|
|
sequence; they have been inserted here simply to read more easily.
|
|
|
|
The only ANSI sequences that Colorama converts into win32 calls are::
|
|
|
|
ESC [ 0 m # reset all (colors and brightness)
|
|
ESC [ 1 m # bright
|
|
ESC [ 2 m # dim (looks same as normal brightness)
|
|
ESC [ 22 m # normal brightness
|
|
|
|
# FOREGROUND:
|
|
ESC [ 30 m # black
|
|
ESC [ 31 m # red
|
|
ESC [ 32 m # green
|
|
ESC [ 33 m # yellow
|
|
ESC [ 34 m # blue
|
|
ESC [ 35 m # magenta
|
|
ESC [ 36 m # cyan
|
|
ESC [ 37 m # white
|
|
ESC [ 39 m # reset
|
|
|
|
# BACKGROUND
|
|
ESC [ 40 m # black
|
|
ESC [ 41 m # red
|
|
ESC [ 42 m # green
|
|
ESC [ 43 m # yellow
|
|
ESC [ 44 m # blue
|
|
ESC [ 45 m # magenta
|
|
ESC [ 46 m # cyan
|
|
ESC [ 47 m # white
|
|
ESC [ 49 m # reset
|
|
|
|
# cursor positioning
|
|
ESC [ y;x H # position cursor at x across, y down
|
|
ESC [ y;x f # position cursor at x across, y down
|
|
ESC [ n A # move cursor n lines up
|
|
ESC [ n B # move cursor n lines down
|
|
ESC [ n C # move cursor n characters forward
|
|
ESC [ n D # move cursor n characters backward
|
|
|
|
# clear the screen
|
|
ESC [ mode J # clear the screen
|
|
|
|
# clear the line
|
|
ESC [ mode K # clear the line
|
|
|
|
Multiple numeric params to the ``'m'`` command can be combined into a single
|
|
sequence::
|
|
|
|
ESC [ 36 ; 45 ; 1 m # bright cyan text on magenta background
|
|
|
|
All other ANSI sequences of the form ``ESC [ <param> ; <param> ... <command>``
|
|
are silently stripped from the output on Windows.
|
|
|
|
Any other form of ANSI sequence, such as single-character codes or alternative
|
|
initial characters, are not recognised or stripped. It would be cool to add
|
|
them though. Let me know if it would be useful for you, via the Issues on
|
|
GitHub.
|
|
|
|
|
|
Status & Known Problems
|
|
-----------------------
|
|
|
|
I've personally only tested it on Windows XP (CMD, Console2), Ubuntu
|
|
(gnome-terminal, xterm), and OS X.
|
|
|
|
Some presumably valid ANSI sequences aren't recognised (see details below),
|
|
but to my knowledge nobody has yet complained about this. Puzzling.
|
|
|
|
See outstanding issues and wish-list:
|
|
https://github.com/tartley/colorama/issues
|
|
|
|
If anything doesn't work for you, or doesn't do what you expected or hoped for,
|
|
I'd love to hear about it on that issues list, would be delighted by patches,
|
|
and would be happy to grant commit access to anyone who submits a working patch
|
|
or two.
|
|
|
|
|
|
License
|
|
-------
|
|
|
|
Copyright Jonathan Hartley & Arnon Yaari, 2013-2020. BSD 3-Clause license; see
|
|
LICENSE file.
|
|
|
|
|
|
Development
|
|
-----------
|
|
|
|
Help and fixes welcome!
|
|
|
|
Tested on CPython 2.7, 3.5, 3.6, 3.7 and 3.8.
|
|
|
|
No requirements other than the standard library.
|
|
Development requirements are captured in requirements-dev.txt.
|
|
|
|
To create and populate a virtual environment::
|
|
|
|
./bootstrap.ps1 # Windows
|
|
make bootstrap # Linux
|
|
|
|
To run tests::
|
|
|
|
./test.ps1 # Windows
|
|
make test # Linux
|
|
|
|
If you use nose to run the tests, you must pass the ``-s`` flag; otherwise,
|
|
``nosetests`` applies its own proxy to ``stdout``, which confuses the unit
|
|
tests.
|
|
|
|
|
|
Professional support
|
|
--------------------
|
|
|
|
.. |tideliftlogo| image:: https://cdn2.hubspot.net/hubfs/4008838/website/logos/logos_for_download/Tidelift_primary-shorthand-logo.png
|
|
:alt: Tidelift
|
|
:target: https://tidelift.com/subscription/pkg/pypi-colorama?utm_source=pypi-colorama&utm_medium=referral&utm_campaign=readme
|
|
|
|
.. list-table::
|
|
:widths: 10 100
|
|
|
|
* - |tideliftlogo|
|
|
- Professional support for colorama is available as part of the
|
|
`Tidelift Subscription`_.
|
|
Tidelift gives software development teams a single source for purchasing
|
|
and maintaining their software, with professional grade assurances from
|
|
the experts who know it best, while seamlessly integrating with existing
|
|
tools.
|
|
|
|
.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-colorama?utm_source=pypi-colorama&utm_medium=referral&utm_campaign=readme
|
|
|
|
|
|
Thanks
|
|
------
|
|
|
|
* Marc Schlaich (schlamar) for a ``setup.py`` fix for Python2.5.
|
|
* Marc Abramowitz, reported & fixed a crash on exit with closed ``stdout``,
|
|
providing a solution to issue #7's setuptools/distutils debate,
|
|
and other fixes.
|
|
* User 'eryksun', for guidance on correctly instantiating ``ctypes.windll``.
|
|
* Matthew McCormick for politely pointing out a longstanding crash on non-Win.
|
|
* Ben Hoyt, for a magnificent fix under 64-bit Windows.
|
|
* Jesse at Empty Square for submitting a fix for examples in the README.
|
|
* User 'jamessp', an observant documentation fix for cursor positioning.
|
|
* User 'vaal1239', Dave Mckee & Lackner Kristof for a tiny but much-needed Win7
|
|
fix.
|
|
* Julien Stuyck, for wisely suggesting Python3 compatible updates to README.
|
|
* Daniel Griffith for multiple fabulous patches.
|
|
* Oscar Lesta for a valuable fix to stop ANSI chars being sent to non-tty
|
|
output.
|
|
* Roger Binns, for many suggestions, valuable feedback, & bug reports.
|
|
* Tim Golden for thought and much appreciated feedback on the initial idea.
|
|
* User 'Zearin' for updates to the README file.
|
|
* John Szakmeister for adding support for light colors
|
|
* Charles Merriam for adding documentation to demos
|
|
* Jurko for a fix on 64-bit Windows CPython2.5 w/o ctypes
|
|
* Florian Bruhin for a fix when stdout or stderr are None
|
|
* Thomas Weininger for fixing ValueError on Windows
|
|
* Remi Rampin for better Github integration and fixes to the README file
|
|
* Simeon Visser for closing a file handle using 'with' and updating classifiers
|
|
to include Python 3.3 and 3.4
|
|
* Andy Neff for fixing RESET of LIGHT_EX colors.
|
|
* Jonathan Hartley for the initial idea and implementation.
|
|
|
|
|
|
|