1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
Metadata-Version: 1.1
Name: ansicolors
Version: 1.1.8
Summary: ANSI colors for Python
Home-page: http://github.com/jonathaneunice/colors/
Author: Jonathan Eunice
Author-email: jonathan.eunice@gmail.com
License: ISC
Description:
| |travisci| |version| |versions| |impls| |wheel| |coverage| |br-coverage|
.. |travisci| image:: https://api.travis-ci.org/jonathaneunice/colors.svg
:target: http://travis-ci.org/jonathaneunice/colors
.. |version| image:: http://img.shields.io/pypi/v/ansicolors.svg?style=flat
:alt: PyPI Package latest release
:target: https://pypi.python.org/pypi/ansicolors
.. |versions| image:: https://img.shields.io/pypi/pyversions/ansicolors.svg
:alt: Supported versions
:target: https://pypi.python.org/pypi/ansicolors
.. |impls| image:: https://img.shields.io/pypi/implementation/ansicolors.svg
:alt: Supported implementations
:target: https://pypi.python.org/pypi/ansicolors
.. |wheel| image:: https://img.shields.io/pypi/wheel/ansicolors.svg
:alt: Wheel packaging support
:target: https://pypi.python.org/pypi/ansicolors
.. |coverage| image:: https://img.shields.io/badge/test_coverage-100%25-6600CC.svg
:alt: Test line coverage
:target: https://pypi.python.org/pypi/ansicolors
.. |br-coverage| image:: https://img.shields.io/badge/branch_coverage-100%25-6600CC.svg
:alt: Test branch coverage
:target: https://pypi.python.org/pypi/ansicolors
ANSI colors for Python
======================
Add ANSI colors and decorations to your strings.
Example Usage
-------------
::
from __future__ import print_function # accomodate Python 2
from colors import *
print(color('my string', fg='blue'))
print(color('some text', fg='red', bg='yellow', style='underline'))
The strings returned by ``color`` will have embedded
`ANSI code sequences <https://en.wikipedia.org/wiki/ANSI_escape_code>`_
stipulating text colors and styles. For example, the above
code will print the strings::
'\x1b[34mmy string\x1b[0m'
'\x1b[31;43;4msome text\x1b[0m'
You can choose the foreground (text) color with the ``fg`` parameter,
the background color with ``bg``, and the style with ``style``.
You can choose one of the 8 basic ANSI colors: ``black``, ``red``, ``green``,
``yellow``, ``blue``, ``magenta``, ``cyan``, and ``white``, plus a special
``default`` which is display-specific, but usually a rational "no special
color" setting.
There are other ways to specify colors. Many devices support
an idiosyncratic 256-color scheme developed as an extension to
the original ANSI codes for the
`xterm terminal emulator <https://en.wikipedia.org/wiki/Xterm>`_.
Colors (or grays) from this larger palette can be specified via ``int``
value (0-255).
To see them all::
from __future__ import print_function
from colors import color
for i in range(256):
print(color('Color #%d' % i, fg=i))
The included ``show_colors.py`` program is a much-expanded version of this idea
that can be used to explore available color and style combinations on your
terminal or output device.
24-bit Color and CSS Compatibility
----------------------------------
Modern terminals go even further than the ``xterm`` 256, often supporting a
full 24-bit RGB color scheme. You can provide a full RGB value several ways:
* with a 3-element ``tuple`` or ``list`` of ``int``, each valued 0 to 255 (e.g. ``(255, 218, 185)``),
* a string containing a CSS-compatible color name (e.g. ``'peachpuff'``),
* a string containing a CSS-style hex value (e.g. ``'#aaa'`` or ``'#8a2be2'``)
* a string containing a CSS-style RGB notation (e.g. ``'rgb(102,51,153)'``)
These forms can be mixed and matched at will::
print(color('orange on gray', 'orange', 'gray'))
print(color('nice color', 'white', '#8a2be2'))
Note that any color name defined in the basic ANSI color set takes
primacy over the CSS color names. Combined with the fact that
terminals do not always agree which precise tone of blue should
qualify as ANSI ``blue``, there can be some ambiguity regarding
the named colors. If you need full precision, specify the RGB
color exactly. The ``parse_rgb`` function can be used to identify
the correct definition according to the CSS standards.
Caveats
-------
Unfortunately there is no guarantee that every terminal will support all the
colors and styles ANSI ostensibly defines. In fact, most implement a rather
small subset. Colors are better supported than styles, for which you *might* get
one or two of the most popular such as ``bold`` or ``underline``.
*Might.*
Whatever colors and styles are supported, there is no guarantee they will be
accurately rendered. Even at this late date, over **fifty years** after the codes
began to be standardized, support from terminals and output devices is limited,
fragemented, and piecemeal.
ANSI codes evolved in an entirely different historical context from today's.
Both the Web and the idea of broad standardization were decades in the future.
Display technology was low-resolution, colors were limited on the rare occasions
they were present, and color/style fidelity was not a major consideration.
Vendors thought little or nothing of creating their own proprietary codes,
implementing functions differently from other vendors, and/or co-opting codes
previously in use for something else. Practical ANSI reference materials
include *many* phrases such as 'hardly ever supported' and 'non-standard.'
We still use ANSI codes today not because they're especially good, but because
they're the best, most-standard approach that pre-Web displays even remotely
agreed upon. Even deep into the Web era, text output endures as an important
means of human-computer interaction. The good news, such is it is: ANSI's color
and style specifications ("SGR" or "Select Graphic Rendition" in ANSI
terminology) are the most-used and best-adhered-to portion of the whole ANSI
show.
More Examples
-------------
::
# use some partial functions
from __future__ import print_function # so works on Python 2 and 3 alike
from colors import red, green, blue
print(red('This is red'))
print(green('This is green'))
print(blue('This is blue'))
Optionally you can add a background color and/or styles.::
print(red('red on blue', bg='blue'))
print(green('green on black', bg='black', style='underline'))
You can use multiple styles at once. Separate them with
a ``+``.::
print(red('very important', style='bold+underline'))
You can additionally specify one of the supported styles: ``none``, ``bold``,
``faint``, ``italic``, ``underline``, ``blink``, ``blink2``, ``negative``,
``concealed``, ``crossed``. While most devices support only a few styles,
unsupported styles are generally ignored, so the only harm done is your text is
less pretty and/or formatted than you might like. A good general rule is
to enjoy the formatting if you get it, but don't depend on it--especially
don't depend on styles like ``blink`` (e.g. to highlight critical data) or
``concealed`` (e.g. to hide data). Most likely, they won't.
If you use a style often, you may want to create your own
named style::
from functools import partial
from colors import color
important = partial(color, fg='red', style='bold+underline'))
print(important('this is very important!'))
Utility Functions
-----------------
In deailing with ANSI-styled text, it can be necessary to determine the
"equivalent" text minus the styling. The function ``strip_color(s)`` does that,
removing ANSI codes from ``s``, returning its "plain text equivalent."
You may also wish to determine the effective length of a string. If it contains
ANSI codes, the builtin ``len()`` function will return the length including
those codes, even though they are logically 0-length. So plain ``len(s)`` is
probably not what you need. ``ansilen(s)`` in contrast returns the "effective"
length of the string, including only the non-ANSI characters. ``ansilen(s)`` is
equivalent to ``len(strip_color(s))``,
License
-------
``colors`` is licensed under the `ISC license <https://en.wikipedia.org/wiki/ISC_license>`_.
Keywords: ASNI color style console
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
