blessed 1.8

Before And After

With the built-in curses module, this is how you would typically 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.

The same program with Blessed is simply:

from blessed import Terminal

term = Terminal()
with term.location(0, term.height - 1):
    print('This is', term.underline('pretty!'))

Simple Formatting

Lots of handy formatting codes are available as attributes on a Terminal class instance. For example:

from blessed import Terminal

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

These capabilities (bold, normal) are translated to their sequences, which when displayed simply change the video attributes. And, when used as a callable, automatically wraps the given string with this sequence, and terminates it with normal.

The same can be written as:

print('I am' + term.bold('bold') + '!')

You may also use the Terminal instance as an argument for .format string method, so that capabilities can be displayed in-line for more complex strings:

print('{t.red_on_yellow}Candy corn{t.normal} for everyone!'.format(t=term))

Capabilities

The basic capabilities supported by most terminals are:

bold

Turn on ‘extra bright’ mode.

reverse

Switch fore and background attributes.

blink

Turn on blinking.

normal

Reset attributes to default.

The less commonly supported capabilities:

dim

Enable half-bright mode.

underline

Enable underline mode.

no_underline

Exit underline mode.

italic

Enable italicized text.

no_italic

Exit italics.

shadow

Enable shadow text mode (rare).

no_shadow

Exit shadow text mode.

standout

Enable standout mode (often, an alias for reverse.).

no_standout

Exit standout mode.

subscript

Enable subscript mode.

no_subscript

Exit subscript mode.

superscript

Enable superscript mode.

no_superscript

Exit superscript mode.

flash

Visual bell, flashes the screen.

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.

Many of these are aliases, their true capability names (such as ‘smul’ for ‘begin underline mode’) may still be used. Any capability in the terminfo(5) manual, under column Cap-name, may be used as an attribute to a Terminal instance. If it is not a supported capability, or a non-tty is used as an output stream, an empty string is returned.

Colors

Color terminals are capable of at least 8 basic colors.

• black

• red

• green

• yellow

• blue

• magenta

• cyan

• white

The same colors, prefixed with bright_ (synonymous with bold_), such as bright_blue, provides 16 colors in total.

The same colors, prefixed with on_ sets the background color, some terminals also provide an additional 8 high-intensity versions using on_bright, some example compound formats:

from blessed import Terminal

term = Terminal()

print(term.on_bright_blue('Blue skies!'))
print(term.bright_red_on_bright_yellow('Pepperoni Pizza!'))

There is also a numerical interface to colors, which takes an integer from 0-15.:

from blessed import Terminal

term = Terminal()

for n in range(16):
    print(term.color(n)('Color {}'.format(n)))

If the terminal defined by the TERM environment variable does not support colors, these simply return empty strings, or the string passed as an argument when used as a callable, without any video attributes. If the TERM defines a terminal that does support colors, but actually does not, they are usually harmless.

Colorless terminals, such as the amber or monochrome vt220, do not support colors but do support reverse video. For this reason, it may be desirable in some applications, such as a selection bar, to simply select a foreground color, followed by reverse video to achieve the desired background color effect:

from blessed import Terminal

term = Terminal()

print('some terminals {standout} more than others'.format(
    standout=term.green_reverse('standout')))

Which appears as bright white on green on color terminals, or black text on amber or green on monochrome terminals. You can check whether the terminal definition used supports colors, and how many, using the number_of_colors property, which returns any of 0 8 or 256 for terminal types such as vt220, ansi, and xterm-256color, respectively.

NOTE: On most color terminals, bright_black is actually a very dark shade of gray!

Compound Formatting

If you want to do lots of crazy formatting all at once, you can just mash it all together:

from blessed import Terminal

term = Terminal()

print(term.bold_underline_green_on_yellow('Woo'))

I’d be remiss if I didn’t credit couleur, where I probably got the idea for all this mashing. This compound notation comes in handy if you want to allow users to customize formatting, just allow compound formatters, like bold_green, as a command line argument or configuration item:

#!/usr/bin/env python
import argparse

parser = argparse.ArgumentParser(
    description='displays argument as specified style')
parser.add_argument('style', type=str, help='style formatter')
parser.add_argument('text', type=str, nargs='+')

from blessed import Terminal

term = Terminal()
args = parser.parse_args()

style = getattr(term, args.style)

print(style(' '.join(args.text)))

Saved as tprint.py, this could be called simply:

$ ./tprint.py bright_blue_reverse Blue Skies

Moving The Cursor

When you want to move the cursor, you have a few choices, the location(y=None, x=None) context manager, move(y, x), move_y(row), and move_x(col) attributes.

from blessed 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 blessed import Terminal

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

Height And Width

Use the height and width properties of the Terminal class instance:

from blessed import Terminal

term = Terminal()
height, width = term.height, term.width
with term.location(x=term.width / 3, y=term.height / 3):
    print('1/3 ways in!')

These are always current, so they may be used with a callback from SIGWINCH signals.:

import signal
from blessed import Terminal

term = Terminal()

def on_resize(sig, action):
    print('height={t.height}, width={t.width}'.format(t=term))

signal.signal(signal.SIGWINCH, on_resize)

term.inkey()

Clearing The Screen

Blessed 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

If you’ve ever noticed a program, such as an editor, restores the previous screen (such as your shell prompt) after exiting, you’re seeing the enter_fullscreen and exit_fullscreen attributes in effect.

enter_fullscreen

Switch to alternate screen, previous screen is stored by terminal driver.

exit_fullscreen

Switch back to standard screen, restoring the same terminal state.

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

from blessed import Terminal

term = Terminal()
with term.fullscreen():
    print(term.move_y(term.height/2) +
          term.center('press any key'))
    term.inkey()

Pipe Savvy

If your program isn’t attached to a terminal, such as piped to a program like less(1) 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, such as when piping output to less -r, pass argument force_styling=True to the Terminal constructor.

In any case, there is a does_styling attribute on Terminal that lets you see whether the terminal attached to the output stream is capable of formatting. If it is False, you may refrain from drawing progress bars and other frippery and just stick to content:

from blessed import Terminal

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

Sequence Awareness

Blessed may measure the printable width of strings containing sequences, providing .center, .ljust, and .rjust methods, using the terminal screen’s width as the default width value:

from blessed import Terminal

term = Terminal()
with term.location(y=term.height / 2):
    print (term.center(term.bold('X'))

Any string containing sequences may have its printable length measured using the .length method. Additionally, textwrap.wrap() is supplied on the Terminal class as method .wrap method that is also sequence-aware, so now you may word-wrap strings containing sequences. The following example displays a poem from Tao Te Ching, word-wrapped to 25 columns:

from blessed import Terminal

t = Terminal()

poem = u''.join((term.bold_blue('Plan difficult tasks '),
                 term.bold_black('through the simplest tasks'),
                 term.bold_cyan('Achieve large tasks '),
                 term.cyan('through the smallest tasks'))
for line in poem:
    print('\n'.join(term.wrap(line, width=25,
                              subsequent_indent=' ' * 4)))

Keyboard Input

The built-in python raw_input function does not return a value until the return key is pressed, and is not suitable for detecting each individual keypress, much less arrow or function keys that emit multibyte sequences. Special termios(4) routines are required to enter Non-canonical, known in curses as cbreak(3). These functions also receive bytes, which must be incrementally decoded to unicode.

Blessed handles all of these special cases with the following simple calls.

from blessed import Terminal
import sys

t = Terminal()

with t.cbreak():
    # blocks until any key is pressed.
    sys.stdin.read(1)

from blessed import Terminal

t = Terminal()

print("press 'q' to quit.")
with t.cbreak():
    val = None
    while val not in (u'q', u'Q',):
        val = t.inkey(timeout=5)
        if not val:
           # timeout
           print("It sure is quiet in here ...")
        elif val.is_sequence:
           print("got sequence: {}.".format((str(val), val.name, val.code)))
        elif val:
           print("got {}.".format(val))
    print('bye!')

got sequence: ('\x1b[A', 'KEY_UP', 259).
got sequence: ('\x1b[1;2A', 'KEY_SUP', 337).
got sequence: ('\x1b[17~', 'KEY_F6', 270).
got sequence: ('\x1b', 'KEY_ESCAPE', 361).
got sequence: ('\n', 'KEY_ENTER', 343).
got /.
It sure is quiet in here ...
got sequence: ('\x1bOP', 'KEY_F1', 265).
It sure is quiet in here ...
got q.
bye!