blessings 1.0

The Pitch

curses is a great library, but there are a couple situations where it doesn’t fit:

• You want to use bold, color, and maybe a little positioning without clearing the whole screen first.

• You want to leave more than one screenful of scrollback in the buffer after your program exits.

In essence, you want to act like a well-behaved command-line app, not a full-screen pseudo-GUI one.

If that’s your use case–or even if you just want to get the noise out of your code–Blessings is for you. Without it, this is how you’d print some underlined text at the bottom of the screen:

from curses import tigetstr, tigetnum, 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')
    plain = tigetstr('sgr0')
else:
    sc = cup = rc = underline = plain = ''
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, 0)  # Move cursor to bottom.
print 'This is {under}underlined{plain}!'.format(under=underline,
                                                 plain=plain)
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):
    print 'This is {under}underlined{plain}!'.format(under=term.underline,
                                                     plain=term.no_underline)

It’s short, it’s obvious, and it keeps all those nasty tigetstr() and tparm() calls out of your code. It also acts intelligently when somebody redirects your output to a file, omitting the terminal control codes you don’t want to see.

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.

from blessings import Terminal

term = Terminal()
print 'I am ' + term.bold + 'bold' + term.normal + '!'

from blessings import Terminal

term = Terminal()
print 'I am ' + term.color(2) + 'green' + term.normal + '!'

from blessings import Terminal

term = Terminal()
height = term.height
width = term.width

from blessings import Terminal

term = Terminal()
with term.location(0, term.height):
    print 'Here is the bottom.'
print 'This is back where I came from.'

Future Plans

• Comb through the terminfo man page for useful capabilities with confounding names, and add sugary attribute names for them.

• A more mnemonic way of specifying colors. Remember that setaf and setf take subtly different color mappings, so maybe term.red would be a good idea.

• An is_terminal attr on Terminal that you can check before drawing progress bars and other such things that are interesting only in a terminal context

• A relative-positioning version of location()

Bugs or suggestions? Visit the issue tracker.

Version History

1.0

• Extracted Blessings from nose-progressive, my progress-bar-having, traceback-shortcutting, rootin’, tootin’ testrunner. It provided the tootin’ functionality.