Coding with Blessings looks like this…

Or, for byte-level control, you can drop down and play with raw terminal capabilities:

Full API Reference

That was long and full of incomprehensible trash! Let’s try it again, this time with Blessings:

Without Blessings, this is how you’d print some underlined text at the bottom of the screen:

Blessings lifts several of curses ’ limiting assumptions, and it makes your code pretty, too:

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 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)

(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

and shadow and no_shadow

and standout and no_standout

and subscript and no_subscript

and superscript and no_superscript

and 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. Moving Temporarily Most often, you’ll 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 - 1): print 'Here is the bottom.' print 'This is back where I came from.' Parameters to location() are x and then y , but you can also pass just one of them, leaving the other alone. For example… with term.location(y=10): print 'We changed just the row.' If you’re doing a series of move calls (see below) and want to return the cursor to its original position afterward, call location() with no arguments, and it will do only the position restoring: with term.location(): print term.move(1, 1) + 'Hi' print term.move(9, 9) + 'Mom' Note that, since location() uses the terminal’s built-in position-remembering machinery, you can’t usefully nest multiple calls. Use location() at the outermost spot, and use simpler things like move inside. Moving Permanently If you just want to move and aren’t worried about returning, do something like this: from blessings import Terminal term = Terminal() print term.move(10, 1) + 'Hi, mom!' move Position the cursor elsewhere. Parameters are y coordinate, then x coordinate. move_x Move the cursor to the given column. move_y Move the cursor to the given row. How does all this work? These are simply more terminal capabilities, wrapped to give them nicer names. The added wrinkle–that they take parameters–is also given a pleasant treatment: rather than making you dig up tparm() all the time, we simply make these capabilities into callable strings. You’d get the raw capability strings if you were to just print them, but they’re fully parametrized if you pass params to them as if they were functions. Consequently, you can also reference any other string-returning capability listed on the terminfo man page by its name under the “Cap-name” column. One-Notch Movement Finally, there are some parameterless movement capabilities that move the cursor one character in various directions: move_left

move_right

move_up

move_down For example… 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.