This is the API documentation for the Blessings terminal library. Because Blessings uses quite a bit of dynamism, you should read the readme first, as not all the useful stuff shows up in these autogenerated docs. However, if you’re looking for seldom-used keyword args or a peek at the internals, you’re in the right place.
An abstraction around terminal capabilities
Unlike curses, this doesn’t require clearing the screen before doing anything, and it’s friendlier to use. It keeps the endless calls to tigetstr() and tparm() out of your code, and it acts intelligently when somebody pipes your output to a non-terminal.
- The stream the terminal outputs to. It’s convenient to pass the stream around with the terminal; it’s almost always needed when the terminal is and saves sticking lots of extra args on client functions in practice.
- Whether stream appears to be a terminal. You can examine this value to decide whether to draw progress bars or other frippery.
Initialize the terminal.
If stream is not a tty, I will default to returning an empty Unicode string for all capability values, so things like piping your output to a file won’t strew escape sequences all over the place. The ls command sets a precedent for this: it defaults to columnar output when being sent to a tty and one-item-per-line when not.
Return parametrized terminal capabilities, like bold.
For example, you can say term.bold to get the string that turns on bold formatting and term.normal to get the string that turns it off again. Or you can take a shortcut: term.bold('hi') bolds its argument and sets everything to normal afterward. You can even combine things: term.bold_underline_red_on_bright_green('yowzers!').
For a parametrized capability like cup, pass the parameters too: some_term.cup(line, column).
man terminfo for a complete list of capabilities.
Return values are always Unicode.
Return a context manager for temporarily moving the cursor.
Move the cursor to a certain position on entry, let you print stuff there, then return the cursor to its original position:
term = Terminal() with term.location(2, 5): print 'Hello, world!' for x in xrange(10): print 'I can do it %i times!' % x
Specify x to move to a certain column, y to move to a certain row, both, or neither. If you specify neither, only the saving and restoration of cursor position will happen. This can be useful if you simply want to restore your place after doing some manual cursor movement.
The height of the terminal in characters
If no stream or a stream not representing a terminal was passed in at construction, return the dimension of the controlling terminal so piping to things that eventually display on the terminal (like less -R) work. If a stream representing a terminal was passed in, return the dimensions of that terminal. If there somehow is no controlling terminal, return None. (Thus, you should check that is_a_tty is true before doing any math on the result.)
The width of the terminal in characters
See height() for some corner cases.
Return a capability that sets the foreground color.
The capability is unparametrized until called and passed a number (0-15), at which point it returns another string which represents a specific color change. This second string can further be called to color a piece of text and set everything back to normal afterward.
|Parameters:||num – The number, 0-15, of the color|
Return a capability that sets the background color.
Return the number of colors the terminal supports.
Common values are 0, 8, 16, 88, and 256.
Though the underlying capability returns -1 when there is no color support, we return 0. This lets you test more Pythonically:
if term.number_of_colors: ...
We also return 0 if the terminal won’t tell us how many colors it supports, which I think is rare.