Skip to main content

A thin, practical wrapper around terminal formatting, positioning, and more

Project description

by Erik Rose

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.

Simple Formatting

Lots of handy formatting codes (“capabilities” in low-level parlance) are available as attributes on Terminal instances. For example:

from blessings import Terminal

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

Other simple capabilities of interest include…

  • clear_eol (clear to the end of the line)
  • reverse
  • underline
  • no_underline (which turns off underlining)
  • normal (which turns off everything)

At the lowest level, there’s no specific code for undoing most formatting. Though the inverse of underline is no_underline, the only way to turn off bold or reverse is normal, which also cancels any custom colors.

Some other terminal libraries implement fancy state machines to hide this detail, but I elected to keep Blessings easy to integrate and quick to learn.

Note

You might notice that these aren’t the typical incomprehensible terminfo capability names; we alias a few (and soon more) of the harder-to-remember ones for readability. However, all capabilities are available: you can reference any string-returning capability listed on the terminfo man page by the name under the “Cap-name” column: for example, rsubm.

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 'I am ' + term.color(2) + 'green' + term.normal + '!'

Parametrized capabilities of interest include…

  • color (takes a number 0-15)
  • bg_color (background color, also takes a number 0-15)

If you need more, you can also reference any string-returning capability listed on the terminfo man page by the name under the “Cap-name” column.

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):
    print 'Here is the bottom.'
print 'This is back where I came from.'

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.

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for blessings, version 1.0
Filename, size File type Python version Upload date Hashes
Filename, size blessings-1.0.tar.gz (7.3 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page