Screenshots

What It Provides

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. After that, you can proceed to ask it all sorts of things
about the terminal, such as its size and color support, and use its styling
to construct strings containing color and styling. Also, the special sequences
inserted with application keys (arrow and function keys) are understood and
decoded, as well as your locale-specific encoded multibyte input.

Simple Formatting

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

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:

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:

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:

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 08 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:

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:

NOTE: The location method receives arguments in form of (x, y),
where the move argument receives arguments in form of (y, x). This is a
flaw in the original erikrose/blessings implementation, kept for
compatibility.

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

NOTE: move_down is often valued as \n, which additionally returns
the carriage to column 0, depending on your terminal emulator.

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.

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:

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:

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.

cbreak

The context manager cbreak can be used to enter key-at-a-time mode: Any
keypress by the user is immediately consumed by read calls:

raw

The context manager raw is the same as cbreak, except interrupt (^C),
quit (^\), suspend (^Z), and flow control (^S, ^Q) characters are not trapped,
but instead sent directly as their natural character. This is necessary if you
actually want to handle the receipt of Ctrl+C

inkey

The method inkey resolves many issues with terminal input by returning
a unicode-derived Keypress instance. Although its return value may be
printed, joined with, or compared to other unicode strings, it also provides
the special attributes is_sequence (bool), code (int),
and name (str):

A timeout value of None (default) will block forever. Any other value specifies
the length of time to poll for input, if no input is received after such time
has elapsed, an empty string is returned. A timeout value of 0 is nonblocking.

keyboard codes

The return value of the Terminal method inkey may be inspected for ts property
is_sequence. When True, it means the value is a multibyte sequence,
representing an application key of your terminal.

The code property (int) may then be compared with any of the following
attributes of the Terminal instance, which are equivalent to the same
available in curs_getch(3), with the following exceptions:

use KEY_DELETE instead of KEY_DC (chr(127))

use KEY_INSERT instead of KEY_IC

use KEY_PGUP instead of KEY_PPAGE

use KEY_PGDOWN instead of KEY_NPAGE

use KEY_ESCAPE instead of KEY_EXIT

use KEY_SUP instead of KEY_SR (shift + up)

use KEY_SDOWN instead of KEY_SF (shift + down)

Additionally, use any of the following common attributes:

KEY_BACKSPACE (chr(8)).

KEY_TAB (chr(9)).

KEY_DOWN, KEY_UP, KEY_LEFT, KEY_RIGHT.

KEY_SLEFT (shift + left).

KEY_SRIGHT (shift + right).

KEY_HOME, KEY_END.

KEY_F1 through KEY_F22.

Shopping List

There are decades of legacy tied up in terminal interaction, so attention to
detail and behavior in edge cases make a difference. Here are some ways
Blessed has your back:

Provides up-to-the-moment terminal height and width, so you can respond to
terminal size changes (SIGWINCH signals). (Most other libraries query the
COLUMNS and LINES environment variables or the cols or lines
terminal capabilities, which don’t update promptly, if at all.)

Avoids making a mess if the output gets piped to a non-terminal.

Works great with standard Python string formatting.

Provides convenient access to all terminal capabilities.

Outputs to any file-like object (StringIO, file), not just stdout.

Keeps a minimum of internal state, so you can feel free to mix and match with
calls to curses or whatever other terminal libraries you like

Version History

introduced: context manager cbreak() and raw(), which is equivalent
to tty.setcbreak() and tty.setraw(), allowing input from stdin to be
read as each key is pressed.

introduced: inkey() and kbhit(), which will return 1 or more
characters as a unicode sequence, with attributes .code and .name
non-None when a multibyte sequence is received, allowing arrow keys and
such to be detected. Optional value timeout allows timed polling or
blocking.

bugfix: allow unsupported terminal capabilities to be callable just as
supported capabilities, so that the return value of term.color(n) may
be called on terminals without color capabilities.

bugfix: for terminals without underline, such as vt220,
term.underline('text'). would be u'text' + term.normal, now is
only u'text'.

enhancement: some attributes are now properties, raise exceptions when
assigned.

enhancement: pypy is now a supported python platform implementation.

enhancement: removed pokemon curses.error exceptions.

enhancement: converted nose tests to pytest, merged travis and tox.

enhancement: pytest fixtures, paired with a new @as_subprocess
decorator
are used to test a multitude of terminal types.

enhancement: test accessories @as_subprocess resolves various issues
with different terminal types that previously went untested.

deprecation: python2.5 is no longer supported (as tox does not supported).

1.6

Add does_styling property. This takes force_styling into account
and should replace most uses of is_a_tty.

Make is_a_tty a read-only property, like does_styling. Writing to
it never would have done anything constructive.

Add fullscreen() and hidden_cursor() to the auto-generated docs.

1.5.1

Clean up fabfile, removing the redundant test command.

Add Travis support.

Make python setup.py test work without spurious errors on 2.6.

Work around a tox parsing bug in its config file.

Make context managers clean up after themselves even if there’s an
exception. (Vitja Makarov)

Parameterizing a capability no longer crashes when there is no tty. (Vitja
Makarov)

1.5

Add syntactic sugar and documentation for enter_fullscreen and
exit_fullscreen.

Add context managers fullscreen() and hidden_cursor().

Now you can force a Terminal never to emit styles by passing
force_styling=None.

1.4

Add syntactic sugar for cursor visibility control and single-space-movement
capabilities.

Endorse the location() idiom for restoring cursor position after a
series of manual movements.

Fix a bug in which location() wouldn’t do anything when passed zeroes.

Allow tests to be run with python setup.py test.

1.3

Added number_of_colors, which tells you how many colors the terminal
supports.

Made color(n) and on_color(n) callable to wrap a string, like the
named colors can. Also, make them both fall back to the setf and
setb capabilities (like the named colors do) if the ANSI setaf and
setab aren’t available.

Allowed color attr to act as an unparametrized string, not just a
callable.

Made height and width examine any passed-in stream before falling
back to stdout. (This rarely if ever affects actual behavior; it’s mostly
philosophical.)

Made caching simpler and slightly more efficient.

Got rid of a reference cycle between Terminals and FormattingStrings.

Updated docs to reflect that terminal addressing (as in location()) is
0-based.

1.2

Added support for Python 3! We need 3.2.3 or greater, because the curses
library couldn’t decide whether to accept strs or bytes before that
(http://bugs.python.org/issue10570).

Everything that comes out of the library is now unicode. This lets us
support Python 3 without making a mess of the code, and Python 2 should
continue to work unless you were testing types (and badly). Please file a
bug if this causes trouble for you.

Changed to the MIT License for better world domination.

Added Sphinx docs.

1.1

Added nicely named attributes for colors.

Introduced compound formatting.

Added wrapper behavior for styling and colors.

Let you force capabilities to be non-empty, even if the output stream is
not a terminal.

Added the is_a_tty attribute for telling whether the output stream is a
terminal.