5 Coding with Blessings looks like this... ::
7 from blessings import Terminal
11 print t.bold('Hi there!')
12 print t.bold_red_on_bright_green('It hurts my eyes!')
14 with t.location(0, t.height - 1):
15 print 'This is at the bottom.'
17 Or, for byte-level control, you can drop down and play with raw terminal
20 print '{t.bold}All your {t.red}bold and red base{t.normal}'.format(t=t)
26 Blessings lifts several of curses_' limiting assumptions, and it makes your
29 * Use styles, color, and maybe a little positioning without clearing the whole
31 * Leave more than one screenful of scrollback in the buffer after your program
32 exits, like a well-behaved command-line app should.
33 * Get rid of all those noisy, C-like calls to ``tigetstr`` and ``tparm``, so
34 your code doesn't get crowded out by terminal bookkeeping.
35 * Act intelligently when somebody redirects your output to a file, omitting the
36 terminal control codes the user doesn't want to see (optional).
38 .. _curses: http://docs.python.org/library/curses.html
43 Without Blessings, this is how you'd print some underlined text at the bottom
46 from curses import tigetstr, setupterm, tparm
47 from fcntl import ioctl
51 from termios import TIOCGWINSZ
53 # If we want to tolerate having our output piped to other commands or
54 # files without crashing, we need to do all this branching:
55 if hasattr(sys.stdout, 'fileno') and isatty(sys.stdout.fileno()):
60 underline = tigetstr('smul')
61 normal = tigetstr('sgr0')
63 sc = cup = rc = underline = normal = ''
64 print sc # Save cursor position.
66 # tigetnum('lines') doesn't always update promptly, hence this:
67 height = struct.unpack('hhhh', ioctl(0, TIOCGWINSZ, '\000' * 8))[0]
68 print tparm(cup, height - 1, 0) # Move cursor to bottom.
69 print 'This is {under}underlined{normal}!'.format(under=underline,
71 print rc # Restore cursor position.
73 Phew! That was long and full of incomprehensible trash! Let's try it again,
74 this time with Blessings::
76 from blessings import Terminal
79 with term.location(0, term.height - 1):
80 print 'This is', term.underline('pretty!')
87 Blessings provides just one top-level object: ``Terminal``. Instantiating a
88 ``Terminal`` figures out whether you're on a terminal at all and, if so, does
89 any necessary terminal setup. After that, you can proceed to ask it all sorts
90 of things about the terminal. Terminal terminal terminal.
95 Lots of handy formatting codes ("capabilities" in low-level parlance) are
96 available as attributes on a ``Terminal``. For example::
98 from blessings import Terminal
101 print 'I am ' + term.bold + 'bold' + term.normal + '!'
103 You can also use them as wrappers so you don't have to say ``normal``
106 print 'I am', term.bold('bold') + '!'
108 Or, if you want fine-grained control while maintaining some semblance of
109 brevity, you can combine it with Python's string formatting, which makes
110 attributes easy to access::
112 print 'All your {t.red}base {t.underline}are belong to us{t.normal}'.format(t=term)
114 Simple capabilities of interest include...
119 * ``no_underline`` (which turns off underlining)
121 * ``normal`` (which turns off everything, even colors)
122 * ``clear_eol`` (clear to the end of the line)
123 * ``clear_bol`` (clear to beginning of line)
124 * ``clear_eos`` (clear to end of screen)
126 Here are a few more which are less likely to work on all terminals:
129 * ``italic`` and ``no_italic``
130 * ``shadow`` and ``no_shadow``
131 * ``standout`` and ``no_standout``
132 * ``subscript`` and ``no_subscript``
133 * ``superscript`` and ``no_superscript``
134 * ``flash`` (which flashes the screen once)
136 Note that, while the inverse of ``underline`` is ``no_underline``, the only way
137 to turn off ``bold`` or ``reverse`` is ``normal``, which also cancels any
138 custom colors. This is because there's no way to tell the terminal to undo
139 certain pieces of formatting, even at the lowest level.
141 You might notice that the above aren't the typical incomprehensible terminfo
142 capability names; we alias a few of the harder-to-remember ones for
143 readability. However, you aren't limited to these: you can reference any
144 string-returning capability listed on the `terminfo man page`_ by the name
145 under the "Cap-name" column: for example, ``term.rum``.
147 .. _`terminfo man page`: http://www.manpagez.com/man/5/terminfo/
152 16 colors, both foreground and background, are available as easy-to-remember
155 from blessings import Terminal
158 print term.red + term.on_green + 'Red on green? Ick!' + term.normal
159 print term.bright_red + term.on_bright_blue + 'This is even worse!' + term.normal
161 You can also call them as wrappers, which sets everything back to normal at the
164 print term.red_on_green('Red on green? Ick!')
165 print term.yellow('I can barely see it.')
167 The available colors are...
178 You can set the background color instead of the foreground by prepending
179 ``on_``, as in ``on_blue``. There is also a ``bright`` version of each color:
180 for example, ``on_bright_blue``.
182 There is also a numerical interface to colors, which takes an integer from
185 term.color(5) + 'Hello' + term.normal
186 term.on_color(3) + 'Hello' + term.normal
188 term.color(5)('Hello')
189 term.on_color(3)('Hello')
191 If some color is unsupported (for instance, if only the normal colors are
192 available, not the bright ones), trying to use it will, on most terminals, have
193 no effect: the foreground and background colors will stay as they were. You can
194 get fancy and do different things depending on the supported colors by checking
197 .. _`number_of_colors`: http://packages.python.org/blessings/#blessings.Terminal.number_of_colors
202 If you want to do lots of crazy formatting all at once, you can just mash it
205 from blessings import Terminal
208 print term.bold_underline_green_on_yellow + 'Woo' + term.normal
210 Or you can use your newly coined attribute as a wrapper, which implicitly sets
211 everything back to normal afterward::
213 print term.bold_underline_green_on_yellow('Woo')
215 This compound notation comes in handy if you want to allow users to customize
216 the formatting of your app: just have them pass in a format specifier like
217 "bold_green" on the command line, and do a quick ``getattr(term,
218 that_option)('Your text')`` when you do your formatting.
220 I'd be remiss if I didn't credit couleur_, where I probably got the idea for
223 .. _couleur: http://pypi.python.org/pypi/couleur
225 Parametrized Capabilities
226 -------------------------
228 Some capabilities take parameters. Rather than making you dig up ``tparm()``
229 all the time, we simply make such capabilities into callable strings. You can
230 pass the parameters right in::
232 from blessings import Terminal
235 print term.move(10, 1)
237 Here are some of interest:
240 Position the cursor elsewhere. Parameters are y coordinate, then x
243 Move the cursor to the given column.
245 Move the cursor to the given row.
247 You can also reference any other string-returning capability listed on the
248 `terminfo man page`_ by its name under the "Cap-name" column.
250 .. _`terminfo man page`: http://www.manpagez.com/man/5/terminfo/
255 It's simple to get the height and width of the terminal, in characters::
257 from blessings import Terminal
263 These are newly updated each time you ask for them, so they're safe to use from
266 Temporary Repositioning
267 -----------------------
269 Sometimes you need to flit to a certain location, print something, and then
270 return: for example, when updating a progress bar at the bottom of the screen.
271 ``Terminal`` provides a context manager for doing this concisely::
273 from blessings import Terminal
276 with term.location(0, term.height - 1):
277 print 'Here is the bottom.'
278 print 'This is back where I came from.'
280 Parameters to ``location()`` are ``x`` and then ``y``, but you can also pass
281 just one of them, leaving the other alone. For example... ::
283 with term.location(y=10):
284 print 'We changed just the row.'
286 If you want to reposition permanently, see ``move``, in an example above.
291 If your program isn't attached to a terminal, like if it's being piped to
292 another command or redirected to a file, all the capability attributes on
293 ``Terminal`` will return empty strings. You'll get a nice-looking file without
294 any formatting codes gumming up the works.
296 If you want to override this--like if you anticipate your program being piped
297 through ``less -r``, which handles terminal escapes just fine--pass
298 ``force_styling=True`` to the ``Terminal`` constructor.
300 In any case, there is an ``is_a_tty`` attribute on ``Terminal`` that lets you
301 see whether the attached stream seems to be a terminal. If it's false, you
302 might refrain from drawing progress bars and other frippery, since you're
303 apparently headed into a pipe::
305 from blessings import Terminal
309 with term.location(0, term.height - 1):
310 print 'Progress: [=======> ]'
311 print term.bold('Important stuff')
316 There are decades of legacy tied up in terminal interaction, so attention to
317 detail and behavior in edge cases make a difference. Here are some ways
318 Blessings has your back:
320 * Uses the terminfo database so it works with any terminal type
321 * Provides up-to-the-moment terminal height and width, so you can respond to
322 terminal size changes (SIGWINCH signals). (Most other libraries query the
323 ``COLUMNS`` and ``LINES`` environment variables or the ``cols`` or ``lines``
324 terminal capabilities, which don't update promptly, if at all.)
325 * Avoids making a mess if the output gets piped to a non-terminal
326 * Works great with standard Python string templating
327 * Provides convenient access to all terminal capabilities, not just a sugared
329 * Outputs to any file-like object, not just stdout
330 * Keeps a minimum of internal state, so you can feel free to mix and match with
331 calls to curses or whatever other terminal libraries you like
333 Blessings does not provide...
335 * Native color support on the Windows command prompt. However, it should work
336 when used in concert with colorama_.
338 .. _colorama: http://pypi.python.org/pypi/colorama/0.2.4
343 Bugs or suggestions? Visit the `issue tracker`_.
345 .. _`issue tracker`: https://github.com/erikrose/blessings/issues/new
350 Blessings is under the MIT License. See the LICENSE file.
356 * Add ``number_of_colors``, which tells you how many colors the terminal
358 * Made ``color(n)`` and ``on_color(n)`` callable to wrap a string, like the
359 named colors can. Also, make them both fall back to the ``setf`` and
360 ``setb`` capabilities (like the named colors do) if the ANSI ``setaf`` and
361 ``setab`` aren't available.
362 * Allow ``color`` attr to act as an unparametrized string, not just a
364 * Make ``height`` and ``width`` examine any passed-in stream before falling
365 back to stdout. (This rarely if ever affects actual behavior; it's mostly
367 * Make caching simpler and slightly more efficient.
368 * Get rid of a reference cycle between Terminals and FormattingStrings.
369 * Update docs to reflect that terminal addressing (as in ``location()``) is
373 * Added support for Python 3! We need 3.2.3 or greater, because the curses
374 library couldn't decide whether to accept strs or bytes before that
375 (http://bugs.python.org/issue10570).
376 * Everything that comes out of the library is now unicode. This lets us
377 support Python 3 without making a mess of the code, and Python 2 should
378 continue to work unless you were testing types (and badly). Please file a
379 bug if this causes trouble for you.
380 * Changed to the MIT License for better world domination.
384 * Added nicely named attributes for colors.
385 * Introduced compound formatting.
386 * Added wrapper behavior for styling and colors.
387 * Let you force capabilities to be non-empty, even if the output stream is
389 * Added the ``is_a_tty`` attribute for telling whether the output stream is a
391 * Sugared the remaining interesting string capabilities.
392 * Let ``location()`` operate on just an x *or* y coordinate.
395 * Extracted Blessings from nose-progressive, my `progress-bar-having,
396 traceback-shortcutting, rootin', tootin' testrunner`_. It provided the
397 tootin' functionality.
399 .. _`progress-bar-having, traceback-shortcutting, rootin', tootin' testrunner`: http://pypi.python.org/pypi/nose-progressive/