| |pypi_downloads| |codecov| |windows| |linux| |mac| |bsd|
Blessed is an easy, practical library for making terminal apps, by providing an elegant, well-documented interface to Colors, Keyboard input, and screen position and Location_ capabilities.
.. code-block:: python
from blessed import Terminal
term = Terminal()
print(term.home + term.clear + term.move_y(term.height // 2))
print(term.black_on_darkkhaki(term.center('press any key to continue.')))
with term.cbreak(), term.hidden_cursor():
inp = term.inkey()
print(term.move_down(2) + 'You pressed ' + term.bold(repr(inp)))
.. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_basic_intro.gif :alt: Animation of running the code example
It's meant to be fun and easy, to do basic terminal graphics and styling with Python using blessed. Terminal_ is the only class you need to import and the only object you should need for Terminal capabilities.
Whether you want to improve CLI apps with colors, or make fullscreen applications or games, blessed should help get you started quickly. Your users will love it because it works on Windows, Mac, and Linux, and you will love it because it has plenty of documentation and examples!
Full documentation at https://blessed.readthedocs.io/en/latest/
.. figure:: https://dxtz6bzwq9sxx.cloudfront.net/blessed_demo_intro.gif :alt: Animations of x11-colorpicker.py, bounce.py, worms.py, and plasma.py
x11-colorpicker.py, bounce.py, worms.py, and plasma.py, from our repository.
Exemplary 3rd-party examples which use blessed,
.. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_3rdparty_voltron.png :alt: Screenshot of 'Voltron' (By the author of Voltron, from their README).
Voltron_ is an extensible debugger UI toolkit written in Python
.. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_3rdparty_cursewords.gif :alt: Animation of 'cursewords' (By the author of cursewords, from their README).
cursewords_ is "graphical" command line program for solving crossword puzzles in the terminal.
.. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_3rdparty_githeat.gif :alt: Animation of 'githeat.interactive', using blessed repository at the time of capture.
GitHeat_ builds an interactive heatmap of git history.
.. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_3rdparty_dashing.gif :alt: Animations from 'Dashing' (By the author of Dashing, from their README)
Dashing_ is a library to quickly create terminal-based dashboards.
.. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_3rdparty_enlighten.gif :alt: Animations from 'Enlighten' (By the author of Enlighten, from their README)
Enlighten_ is a console progress bar library that allows simultaneous output without redirection.
.. figure:: https://dxtz6bzwq9sxx.cloudfront.net/blessed_3rdparty_macht.gif :alt: Demonstration of 'macht', a 2048 clone
macht_ is a clone of the (briefly popular) puzzle game, 2048.
Blessed works with Windows, Mac, Linux, and BSD's, on Python 2.7, 3.5+.
Blessed is more than just a Python wrapper around curses_:
terminfo(5)
so it works with any terminal type and capability: No more C-like calls to
tigetstr and tparm_.Terminal.fullscreen()
_ and Terminal.hidden_cursor()
_ to safely
express terminal modes, curses development will no longer fudge up your shell.Blessed is a fork of blessings <https://github.com/erikrose/blessings>
_, which does all of
the same above with the same API, as well as following enhancements:
Terminal.color_rgb()
_ and Terminal.on_color_rgb()
and all X11
Colors by name, and not by number.Terminal.get_location()
, enter key-at-a-time input mode using
Terminal.cbreak()
or Terminal.raw()
context managers, and read timed key presses using
Terminal.inkey()
.Terminal.length()
, supporting additional methods Terminal.wrap()
and Terminal.center()
,
terminal-aware variants of the built-in function textwrap.wrap()
and method str.center()
_,
respectively.Terminal.strip_seqs()
or
sequences and whitespace using Terminal.strip()
.With the built-in curses_ module, this is how you would typically print some underlined text at the bottom of the screen:
.. code-block:: python
from curses import tigetstr, setupterm, tparm
from fcntl import ioctl
from os import isatty
import struct
import sys
from termios import TIOCGWINSZ
# If we want to tolerate having our output piped to other commands or
# files without crashing, we need to do all this branching:
if hasattr(sys.stdout, 'fileno') and isatty(sys.stdout.fileno()):
setupterm()
sc = tigetstr('sc')
cup = tigetstr('cup')
rc = tigetstr('rc')
underline = tigetstr('smul')
normal = tigetstr('sgr0')
else:
sc = cup = rc = underline = normal = ''
# Save cursor position.
print(sc)
if cup:
# tigetnum('lines') doesn't always update promptly, hence this:
height = struct.unpack('hhhh', ioctl(0, TIOCGWINSZ, '\000' * 8))[0]
# Move cursor to bottom.
print(tparm(cup, height - 1, 0))
print('This is {under}underlined{normal}!'
.format(under=underline, normal=normal))
# Restore cursor position.
print(rc)
The same program with Blessed is simply:
.. code-block:: python
from blessed import Terminal
term = Terminal()
with term.location(0, term.height - 1):
print('This is ' + term.underline('underlined') + '!', end='')
.. _curses: https://docs.python.org/3/library/curses.html
.. _tigetstr: http://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/tigetstr.3
.. tparm: http://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/tparm.3
.. terminfo(5)
: https://invisible-island.net/ncurses/man/terminfo.5.html
.. _str.center(): https://docs.python.org/3/library/stdtypes.html#str.center
.. _textwrap.wrap(): https://docs.python.org/3/library/textwrap.html#textwrap.wrap
.. Terminal: https://blessed.readthedocs.io/en/stable/terminal.html
.. Terminal.fullscreen()
: https://blessed.readthedocs.io/en/latest/api/terminal.html#blessed.terminal.Terminal.fullscreen
.. _Terminal.get_location()
: https://blessed.readthedocs.io/en/latest/location.html#finding-the-cursor
.. _Terminal.color_rgb()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.color_rgb
.. _Terminal.hidden_cursor()
: https://blessed.readthedocs.io/en/latest/api/terminal.html#blessed.terminal.Terminal.hidden_cursor
.. _Terminal.on_color_rgb()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.on_color_rgb
.. Terminal.length()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.length
.. Terminal.strip()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.strip
.. Terminal.rstrip()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.rstrip
.. Terminal.lstrip()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.lstrip
.. _Terminal.strip_seqs()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.strip_seqs
.. Terminal.wrap()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.wrap
.. Terminal.center()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.center
.. Terminal.rjust()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.rjust
.. Terminal.ljust()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.ljust
.. Terminal.cbreak()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.cbreak
.. Terminal.raw()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.raw
.. _Terminal.inkey()
: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.inkey
.. _Colors: https://blessed.readthedocs.io/en/stable/colors.html
.. _Styles: https://blessed.readthedocs.io/en/stable/terminal.html#styles
.. _Location: https://blessed.readthedocs.io/en/stable/location.html
.. _Keyboard: https://blessed.readthedocs.io/en/stable/keyboard.html
.. _Examples: https://blessed.readthedocs.io/en/stable/examples.html
.. _x11-colorpicker.py: https://blessed.readthedocs.io/en/stable/examples.html#x11-colorpicker-py
.. _bounce.py: https://blessed.readthedocs.io/en/stable/examples.html#bounce-py
.. _worms.py: https://blessed.readthedocs.io/en/stable/examples.html#worms-py
.. _plasma.py: https://blessed.readthedocs.io/en/stable/examples.html#plasma-py
.. _Voltron: https://github.com/snare/voltron
.. _cursewords: https://github.com/thisisparker/cursewords
.. _GitHeat: https://github.com/AmmsA/Githeat
.. _Dashing: https://github.com/FedericoCeratto/dashing
.. _Enlighten: https://github.com/Rockhopper-Technologies/enlighten
.. _macht: https://github.com/rolfmorel/macht
.. _f-strings: https://docs.python.org/3/reference/lexical_analysis.html#f-strings
.. |pypi_downloads| image:: https://img.shields.io/pypi/dm/blessed.svg?logo=pypi
:alt: Downloads
:target: https://pypi.org/project/blessed/
.. |codecov| image:: https://codecov.io/gh/jquast/blessed/branch/master/graph/badge.svg
:alt: codecov.io Code Coverage
:target: https://codecov.io/gh/jquast/blessed/
.. |linux| image:: https://img.shields.io/badge/Linux-yes-success?logo=linux
:alt: Linux supported
.. |windows| image:: https://img.shields.io/badge/Windows-yes-success?logo=windows
:alt: Windows supported
.. |mac| image:: https://img.shields.io/badge/MacOS-yes-success?logo=apple
:alt: MacOS supported
.. |bsd| image:: https://img.shields.io/badge/BSD-yes-success?logo=freebsd
:alt: BSD supported