forked from unicorn-wg/gecko-dev
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathPKG-INFO
426 lines (323 loc) · 17.5 KB
/
PKG-INFO
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
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
Metadata-Version: 1.0
Name: blessings
Version: 1.3
Summary: A thin, practical wrapper around terminal formatting, positioning, and more
Home-page: https://github.com/erikrose/blessings
Author: Erik Rose
Author-email: [email protected]
License: MIT
Description: =========
Blessings
=========
Coding with Blessings looks like this... ::
from blessings import Terminal
t = Terminal()
print t.bold('Hi there!')
print t.bold_red_on_bright_green('It hurts my eyes!')
with t.location(0, t.height - 1):
print 'This is at the bottom.'
Or, for byte-level control, you can drop down and play with raw terminal
capabilities::
print '{t.bold}All your {t.red}bold and red base{t.normal}'.format(t=t)
print t.wingo(2)
The Pitch
=========
Blessings lifts several of curses_' limiting assumptions, and it makes your
code pretty, too:
* Use styles, color, and maybe a little positioning without clearing the whole
screen first.
* Leave more than one screenful of scrollback in the buffer after your program
exits, like a well-behaved command-line app should.
* Get rid of all those noisy, C-like calls to ``tigetstr`` and ``tparm``, so
your code doesn't get crowded out by terminal bookkeeping.
* Act intelligently when somebody redirects your output to a file, omitting the
terminal control codes the user doesn't want to see (optional).
.. _curses: http://docs.python.org/library/curses.html
Before And After
----------------
Without Blessings, this is how you'd print some underlined text at the bottom
of the screen::
from curses import tigetstr, setupterm, tparm
from fcntl import ioctl
from os import isatty
import struct
import sys
from termios import TIOCGWINSZ
# If we want to tolerate having our output piped to other commands or
# files without crashing, we need to do all this branching:
if hasattr(sys.stdout, 'fileno') and isatty(sys.stdout.fileno()):
setupterm()
sc = tigetstr('sc')
cup = tigetstr('cup')
rc = tigetstr('rc')
underline = tigetstr('smul')
normal = tigetstr('sgr0')
else:
sc = cup = rc = underline = normal = ''
print sc # Save cursor position.
if cup:
# tigetnum('lines') doesn't always update promptly, hence this:
height = struct.unpack('hhhh', ioctl(0, TIOCGWINSZ, '\000' * 8))[0]
print tparm(cup, height - 1, 0) # Move cursor to bottom.
print 'This is {under}underlined{normal}!'.format(under=underline,
normal=normal)
print rc # Restore cursor position.
Phew! That was long and full of incomprehensible trash! Let's try it again,
this time with Blessings::
from blessings import Terminal
term = Terminal()
with term.location(0, term.height - 1):
print 'This is', term.underline('pretty!')
Much better.
What It Provides
================
Blessings provides just one top-level object: ``Terminal``. Instantiating a
``Terminal`` figures out whether you're on a terminal at all and, if so, does
any necessary terminal setup. After that, you can proceed to ask it all sorts
of things about the terminal. Terminal terminal terminal.
Simple Formatting
-----------------
Lots of handy formatting codes ("capabilities" in low-level parlance) are
available as attributes on a ``Terminal``. For example::
from blessings import Terminal
term = Terminal()
print 'I am ' + term.bold + 'bold' + term.normal + '!'
You can also use them as wrappers so you don't have to say ``normal``
afterward::
print 'I am', term.bold('bold') + '!'
Or, if you want fine-grained control while maintaining some semblance of
brevity, you can combine it with Python's string formatting, which makes
attributes easy to access::
print 'All your {t.red}base {t.underline}are belong to us{t.normal}'.format(t=term)
Simple capabilities of interest include...
* ``bold``
* ``reverse``
* ``underline``
* ``no_underline`` (which turns off underlining)
* ``blink``
* ``normal`` (which turns off everything, even colors)
* ``clear_eol`` (clear to the end of the line)
* ``clear_bol`` (clear to beginning of line)
* ``clear_eos`` (clear to end of screen)
Here are a few more which are less likely to work on all terminals:
* ``dim``
* ``italic`` and ``no_italic``
* ``shadow`` and ``no_shadow``
* ``standout`` and ``no_standout``
* ``subscript`` and ``no_subscript``
* ``superscript`` and ``no_superscript``
* ``flash`` (which flashes the screen once)
Note that, while the inverse of ``underline`` is ``no_underline``, the only way
to turn off ``bold`` or ``reverse`` is ``normal``, which also cancels any
custom colors. This is because there's no way to tell the terminal to undo
certain pieces of formatting, even at the lowest level.
You might notice that the above aren't the typical incomprehensible terminfo
capability names; we alias a few of the harder-to-remember ones for
readability. However, you aren't limited to these: you can reference any
string-returning capability listed on the `terminfo man page`_ by the name
under the "Cap-name" column: for example, ``term.rum``.
.. _`terminfo man page`: http://www.manpagez.com/man/5/terminfo/
Color
-----
16 colors, both foreground and background, are available as easy-to-remember
attributes::
from blessings import Terminal
term = Terminal()
print term.red + term.on_green + 'Red on green? Ick!' + term.normal
print term.bright_red + term.on_bright_blue + 'This is even worse!' + term.normal
You can also call them as wrappers, which sets everything back to normal at the
end::
print term.red_on_green('Red on green? Ick!')
print term.yellow('I can barely see it.')
The available colors are...
* ``black``
* ``red``
* ``green``
* ``yellow``
* ``blue``
* ``magenta``
* ``cyan``
* ``white``
You can set the background color instead of the foreground by prepending
``on_``, as in ``on_blue``. There is also a ``bright`` version of each color:
for example, ``on_bright_blue``.
There is also a numerical interface to colors, which takes an integer from
0-15::
term.color(5) + 'Hello' + term.normal
term.on_color(3) + 'Hello' + term.normal
term.color(5)('Hello')
term.on_color(3)('Hello')
If some color is unsupported (for instance, if only the normal colors are
available, not the bright ones), trying to use it will, on most terminals, have
no effect: the foreground and background colors will stay as they were. You can
get fancy and do different things depending on the supported colors by checking
`number_of_colors`_.
.. _`number_of_colors`: http://packages.python.org/blessings/#blessings.Terminal.number_of_colors
Compound Formatting
-------------------
If you want to do lots of crazy formatting all at once, you can just mash it
all together::
from blessings import Terminal
term = Terminal()
print term.bold_underline_green_on_yellow + 'Woo' + term.normal
Or you can use your newly coined attribute as a wrapper, which implicitly sets
everything back to normal afterward::
print term.bold_underline_green_on_yellow('Woo')
This compound notation comes in handy if you want to allow users to customize
the formatting of your app: just have them pass in a format specifier like
"bold_green" on the command line, and do a quick ``getattr(term,
that_option)('Your text')`` when you do your formatting.
I'd be remiss if I didn't credit couleur_, where I probably got the idea for
all this mashing.
.. _couleur: http://pypi.python.org/pypi/couleur
Parametrized Capabilities
-------------------------
Some capabilities take parameters. Rather than making you dig up ``tparm()``
all the time, we simply make such capabilities into callable strings. You can
pass the parameters right in::
from blessings import Terminal
term = Terminal()
print term.move(10, 1)
Here are some of interest:
``move``
Position the cursor elsewhere. Parameters are y coordinate, then x
coordinate.
``move_x``
Move the cursor to the given column.
``move_y``
Move the cursor to the given row.
You can also reference any other string-returning capability listed on the
`terminfo man page`_ by its name under the "Cap-name" column.
.. _`terminfo man page`: http://www.manpagez.com/man/5/terminfo/
Height and Width
----------------
It's simple to get the height and width of the terminal, in characters::
from blessings import Terminal
term = Terminal()
height = term.height
width = term.width
These are newly updated each time you ask for them, so they're safe to use from
SIGWINCH handlers.
Temporary Repositioning
-----------------------
Sometimes you need to flit to a certain location, print something, and then
return: for example, when updating a progress bar at the bottom of the screen.
``Terminal`` provides a context manager for doing this concisely::
from blessings import Terminal
term = Terminal()
with term.location(0, term.height - 1):
print 'Here is the bottom.'
print 'This is back where I came from.'
Parameters to ``location()`` are ``x`` and then ``y``, but you can also pass
just one of them, leaving the other alone. For example... ::
with term.location(y=10):
print 'We changed just the row.'
If you want to reposition permanently, see ``move``, in an example above.
Pipe Savvy
----------
If your program isn't attached to a terminal, like if it's being piped to
another command or redirected to a file, all the capability attributes on
``Terminal`` will return empty strings. You'll get a nice-looking file without
any formatting codes gumming up the works.
If you want to override this--like if you anticipate your program being piped
through ``less -r``, which handles terminal escapes just fine--pass
``force_styling=True`` to the ``Terminal`` constructor.
In any case, there is an ``is_a_tty`` attribute on ``Terminal`` that lets you
see whether the attached stream seems to be a terminal. If it's false, you
might refrain from drawing progress bars and other frippery, since you're
apparently headed into a pipe::
from blessings import Terminal
term = Terminal()
if term.is_a_tty:
with term.location(0, term.height - 1):
print 'Progress: [=======> ]'
print term.bold('Important stuff')
Shopping List
=============
There are decades of legacy tied up in terminal interaction, so attention to
detail and behavior in edge cases make a difference. Here are some ways
Blessings has your back:
* Uses the terminfo database so it works with any terminal type
* Provides up-to-the-moment terminal height and width, so you can respond to
terminal size changes (SIGWINCH signals). (Most other libraries query the
``COLUMNS`` and ``LINES`` environment variables or the ``cols`` or ``lines``
terminal capabilities, which don't update promptly, if at all.)
* Avoids making a mess if the output gets piped to a non-terminal
* Works great with standard Python string templating
* Provides convenient access to all terminal capabilities, not just a sugared
few
* Outputs to any file-like object, not just stdout
* Keeps a minimum of internal state, so you can feel free to mix and match with
calls to curses or whatever other terminal libraries you like
Blessings does not provide...
* Native color support on the Windows command prompt. However, it should work
when used in concert with colorama_.
.. _colorama: http://pypi.python.org/pypi/colorama/0.2.4
Bugs
====
Bugs or suggestions? Visit the `issue tracker`_.
.. _`issue tracker`: https://github.com/erikrose/blessings/issues/new
License
=======
Blessings is under the MIT License. See the LICENSE file.
Version History
===============
1.3
* Add ``number_of_colors``, which tells you how many colors the terminal
supports.
* Made ``color(n)`` and ``on_color(n)`` callable to wrap a string, like the
named colors can. Also, make them both fall back to the ``setf`` and
``setb`` capabilities (like the named colors do) if the ANSI ``setaf`` and
``setab`` aren't available.
* Allow ``color`` attr to act as an unparametrized string, not just a
callable.
* Make ``height`` and ``width`` examine any passed-in stream before falling
back to stdout. (This rarely if ever affects actual behavior; it's mostly
philosophical.)
* Make caching simpler and slightly more efficient.
* Get rid of a reference cycle between Terminals and FormattingStrings.
* Update docs to reflect that terminal addressing (as in ``location()``) is
0-based.
1.2
* Added support for Python 3! We need 3.2.3 or greater, because the curses
library couldn't decide whether to accept strs or bytes before that
(http://bugs.python.org/issue10570).
* Everything that comes out of the library is now unicode. This lets us
support Python 3 without making a mess of the code, and Python 2 should
continue to work unless you were testing types (and badly). Please file a
bug if this causes trouble for you.
* Changed to the MIT License for better world domination.
* Added Sphinx docs.
1.1
* Added nicely named attributes for colors.
* Introduced compound formatting.
* Added wrapper behavior for styling and colors.
* Let you force capabilities to be non-empty, even if the output stream is
not a terminal.
* Added the ``is_a_tty`` attribute for telling whether the output stream is a
terminal.
* Sugared the remaining interesting string capabilities.
* Let ``location()`` operate on just an x *or* y coordinate.
1.0
* Extracted Blessings from nose-progressive, my `progress-bar-having,
traceback-shortcutting, rootin', tootin' testrunner`_. It provided the
tootin' functionality.
.. _`progress-bar-having, traceback-shortcutting, rootin', tootin' testrunner`: http://pypi.python.org/pypi/nose-progressive/
Keywords: terminal,tty,curses,ncurses,formatting,style,color,console
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Terminals