blessings 1.7

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.

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.

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 + '!'

Though they are strings at heart, you can also use them as callable 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)

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 portable way to tell the terminal to undo certain pieces of formatting, even at the lowest level.

You might also 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.

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.

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.

Moving The Cursor

When you want to move the cursor to output text at a specific spot, you have a few choices.

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.'

with term.location(y=10):
    print 'We changed just the row.'

with term.location():
    print term.move(1, 1) + 'Hi'
    print term.move(9, 9) + 'Mom'

from blessings import Terminal

term = Terminal()
print term.move(10, 1) + 'Hi, mom!'

print term.move_up + 'Howdy!'

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.

Clearing The Screen

Blessings provides syntactic sugar over some screen-clearing capabilities:

clear

Clear the whole screen.

clear_eol

Clear to the end of the line.

clear_bol

Clear backward to the beginning of the line.

clear_eos

Clear to the end of screen.

Full-Screen Mode

Perhaps you have seen a full-screen program, such as an editor, restore the exact previous state of the terminal upon exiting, including, for example, the command-line prompt from which it was launched. Curses pretty much forces you into this behavior, but Blessings makes it optional. If you want to do the state-restoration thing, use these capabilities:

enter_fullscreen

Switch to the terminal mode where full-screen output is sanctioned. Print this before you do any output.

exit_fullscreen

Switch back to normal mode, restoring the exact state from before enter_fullscreen was used.

Using exit_fullscreen will wipe away any trace of your program’s output, so reserve it for when you don’t want to leave anything behind in the scrollback.

There’s also a context manager you can use as a shortcut:

from blessings import Terminal

term = Terminal()
with term.fullscreen():
    # Print some stuff.

Besides brevity, another advantage is that it switches back to normal mode even if an exception is raised in the with block.

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 a does_styling attribute on Terminal that lets you see whether your capabilities will return actual, working formatting codes. If it’s false, you should refrain from drawing progress bars and other frippery and just stick to content, since you’re apparently headed into a pipe:

from blessings import Terminal

term = Terminal()
if term.does_styling:
    with term.location(0, term.height - 1):
        print 'Progress: [=======>   ]'
print term.bold('Important stuff')