Terminal

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)

Hyperlinks

Maybe you haven’t noticed, because it’s a recent addition to terminal emulators, is that they can now support hyperlinks, like to HTML, or even file:// URLs, which allows creating clickable links of text.

>>> print(f"blessed {term.link('https://blessed.readthedocs.org', 'documentation')}")
blessed documentation

Hover your cursor over documentation, and it should highlight as a clickable URL.

Animation of running code example and clicking a hyperlink

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