Terminal

A visual example of the below interaction with the Terminal class, in IPython.

Blessed 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 setup:

>>> import blessed
>>> term = blessed.Terminal()

This is the only object, named term here, that you should need from blessed, for all of the remaining examples in our documentation.

You can proceed to ask it all sorts of things about the terminal, such as its size:

>>> term.height, term.width
(34, 102)

Support for Colors:

>>> term.number_of_colors
256

And create printable strings containing sequences for Colors:

>>> term.green_reverse('ALL SYSTEMS GO')
'\x1b[32m\x1b[7mALL SYSTEMS GO\x1b[m'

When printed, these codes make your terminal go to work:

>>> print(term.white_on_firebrick3('SYSTEM OFFLINE'))

And thanks to f-strings since python 3.6, it’s very easy to mix attributes and strings together:

>>> print(f"{term.yellow}Yellow is brown, {term.bright_yellow}"
          f"Bright yellow is actually yellow!{term.normal}")

Capabilities

Any capability in the terminfo(5) manual, under column Cap-name can be an attribute of the Terminal class, such as ‘smul’ for ‘begin underline mode’.

There are a lot of interesting capabilities in the terminfo(5) manual page, but many of these will return an empty string, as they are not supported by your terminal. They can still be used, but have no effect. For example, blink only works on a few terminals, does yours?

>>> print(term.blink("Insert System disk into drive A:"))

Compound Formatting

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

>>> print(term.underline_bold_green_on_yellow('They live! In sewers!'))

This compound notation comes in handy for users & configuration to customize your app, too!

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.

Suggest to always combine home and clear, and, in almost all emulators, clearing the screen after setting the background color will repaint the background of the screen:

>>> print(term.home + term.on_blue + term.clear)

Styles

In addition to Colors, blessed also supports the limited amount of styles that terminals can do. These are:

bold

Turn on ‘extra bright’ mode.

reverse

Switch fore and background attributes.

normal

Reset attributes to default.

underline

Enable underline mode.

no_underline

Disable underline mode.

Note

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.

Full-Screen Mode

If you’ve ever noticed how a program like vim(1) restores you to your unix shell history after exiting, it’s actually a pretty basic trick that all terminal emulators support, that blessed provides using the fullscreen() context manager over these two basic capabilities:

enter_fullscreen

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

exit_fullscreen

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

with term.fullscreen(), term.cbreak():
    print(term.move_y(term.height // 2) +
          term.center('press any key').rstrip())
    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 for any Colors, Location, or other sequences. 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 value True to the force_styling parameter.

In any case, there is a does_styling attribute 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:

if term.does_styling:
    with term.location(x=0, y=term.height - 1):
        print('Progress: [=======>   ]')
print(term.bold("60%"))