1Metadata-Version: 1.2 2Name: blessed 3Version: 1.19.0 4Summary: Easy, practical library for making terminal apps, by providing an elegant, well-documented interface to Colors, Keyboard input, and screen Positioning capabilities. 5Home-page: https://github.com/jquast/blessed 6Author: Jeff Quast, Erik Rose, Avram Lubkin 7Author-email: contact@jeffquast.com 8License: MIT 9Project-URL: Documentation, https://blessed.readthedocs.io 10Description: | |pypi_downloads| |codecov| |windows| |linux| |mac| |bsd| 11 12 Introduction 13 ============ 14 15 Blessed is an easy, practical *library* for making *terminal* apps, by providing an elegant, 16 well-documented interface to Colors_, Keyboard_ input, and screen position and Location_ 17 capabilities. 18 19 .. code-block:: python 20 21 from blessed import Terminal 22 23 term = Terminal() 24 25 print(term.home + term.clear + term.move_y(term.height // 2)) 26 print(term.black_on_darkkhaki(term.center('press any key to continue.'))) 27 28 with term.cbreak(), term.hidden_cursor(): 29 inp = term.inkey() 30 31 print(term.move_down(2) + 'You pressed ' + term.bold(repr(inp))) 32 33 .. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_basic_intro.gif 34 :alt: Animation of running the code example 35 36 It's meant to be *fun* and *easy*, to do basic terminal graphics and styling with Python using 37 *blessed*. Terminal_ is the only class you need to import and the only object you should need for 38 Terminal capabilities. 39 40 Whether you want to improve CLI apps with colors, or make fullscreen applications or games, 41 *blessed* should help get you started quickly. Your users will love it because it works on Windows, 42 Mac, and Linux, and you will love it because it has plenty of documentation and examples! 43 44 Full documentation at https://blessed.readthedocs.io/en/latest/ 45 46 Examples 47 -------- 48 49 .. figure:: https://dxtz6bzwq9sxx.cloudfront.net/blessed_demo_intro.gif 50 :alt: Animations of x11-colorpicker.py, bounce.py, worms.py, and plasma.py 51 52 x11-colorpicker.py_, bounce.py_, worms.py_, and plasma.py_, from our repository. 53 54 Exemplary 3rd-party examples which use *blessed*, 55 56 .. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_3rdparty_voltron.png 57 :alt: Screenshot of 'Voltron' (By the author of Voltron, from their README). 58 59 Voltron_ is an extensible debugger UI toolkit written in Python 60 61 .. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_3rdparty_cursewords.gif 62 :alt: Animation of 'cursewords' (By the author of cursewords, from their README). 63 64 cursewords_ is "graphical" command line program for solving crossword puzzles in the terminal. 65 66 .. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_3rdparty_githeat.gif 67 :alt: Animation of 'githeat.interactive', using blessed repository at the time of capture. 68 69 GitHeat_ builds an interactive heatmap of git history. 70 71 .. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_3rdparty_dashing.gif 72 :alt: Animations from 'Dashing' (By the author of Dashing, from their README) 73 74 Dashing_ is a library to quickly create terminal-based dashboards. 75 76 .. figure:: https://dxtz6bzwq9sxx.cloudfront.net/demo_3rdparty_enlighten.gif 77 :alt: Animations from 'Enlighten' (By the author of Enlighten, from their README) 78 79 Enlighten_ is a console progress bar library that allows simultaneous output without redirection. 80 81 .. figure:: https://dxtz6bzwq9sxx.cloudfront.net/blessed_3rdparty_macht.gif 82 :alt: Demonstration of 'macht', a 2048 clone 83 84 macht_ is a clone of the (briefly popular) puzzle game, 2048. 85 86 Requirements 87 ------------ 88 89 *Blessed* works with Windows, Mac, Linux, and BSD's, on Python 2.7, 3.4, 3.5, 3.6, 3.7, and 3.8. 90 91 Brief Overview 92 -------------- 93 94 *Blessed* is more than just a Python wrapper around curses_: 95 96 * Styles_, Colors_, and maybe a little positioning without necessarily clearing the whole screen 97 first. 98 * Works great with Python's new f-strings_ or any other kind of string formatting. 99 * Provides up-to-the-moment Location_ and terminal height and width, so you can respond to terminal 100 size changes. 101 * Avoids making a mess if the output gets piped to a non-terminal, you can output sequences to any 102 file-like object such as *StringIO*, files, pipes or sockets. 103 * Uses `terminfo(5)`_ so it works with any terminal type and capability: No more C-like calls to 104 tigetstr_ and tparm_. 105 * Non-obtrusive calls to only the capabilities database ensures that you are free to mix and match 106 with calls to any other curses application code or library you like. 107 * Provides context managers `Terminal.fullscreen()`_ and `Terminal.hidden_cursor()`_ to safely 108 express terminal modes, curses development will no longer fudge up your shell. 109 * Act intelligently when somebody redirects your output to a file, omitting all of the special 110 sequences colors, but still containing all of the text. 111 112 *Blessed* is a fork of `blessings <https://github.com/erikrose/blessings>`_, which does all of 113 the same above with the same API, as well as following **enhancements**: 114 115 * Windows support, new since Dec. 2019! 116 * Dead-simple keyboard handling: safely decoding unicode input in your system's preferred locale and 117 supports application/arrow keys. 118 * 24-bit color support, using `Terminal.color_rgb()`_ and `Terminal.on_color_rgb()`_ and all X11 119 Colors_ by name, and not by number. 120 * Determine cursor location using `Terminal.get_location()`_, enter key-at-a-time input mode using 121 `Terminal.cbreak()`_ or `Terminal.raw()`_ context managers, and read timed key presses using 122 `Terminal.inkey()`_. 123 * Allows the *printable length* of strings that contain sequences to be determined by 124 `Terminal.length()`_, supporting additional methods `Terminal.wrap()`_ and `Terminal.center()`_, 125 terminal-aware variants of the built-in function `textwrap.wrap()`_ and method `str.center()`_, 126 respectively. 127 * Allows sequences to be removed from strings that contain them, using `Terminal.strip_seqs()`_ or 128 sequences and whitespace using `Terminal.strip()`_. 129 130 Before And After 131 ---------------- 132 133 With the built-in curses_ module, this is how you would typically 134 print some underlined text at the bottom of the screen: 135 136 .. code-block:: python 137 138 from curses import tigetstr, setupterm, tparm 139 from fcntl import ioctl 140 from os import isatty 141 import struct 142 import sys 143 from termios import TIOCGWINSZ 144 145 # If we want to tolerate having our output piped to other commands or 146 # files without crashing, we need to do all this branching: 147 if hasattr(sys.stdout, 'fileno') and isatty(sys.stdout.fileno()): 148 setupterm() 149 sc = tigetstr('sc') 150 cup = tigetstr('cup') 151 rc = tigetstr('rc') 152 underline = tigetstr('smul') 153 normal = tigetstr('sgr0') 154 else: 155 sc = cup = rc = underline = normal = '' 156 157 # Save cursor position. 158 print(sc) 159 160 if cup: 161 # tigetnum('lines') doesn't always update promptly, hence this: 162 height = struct.unpack('hhhh', ioctl(0, TIOCGWINSZ, '\000' * 8))[0] 163 164 # Move cursor to bottom. 165 print(tparm(cup, height - 1, 0)) 166 167 print('This is {under}underlined{normal}!' 168 .format(under=underline, normal=normal)) 169 170 # Restore cursor position. 171 print(rc) 172 173 The same program with *Blessed* is simply: 174 175 .. code-block:: python 176 177 from blessed import Terminal 178 179 term = Terminal() 180 with term.location(0, term.height - 1): 181 print('This is ' + term.underline('underlined') + '!', end='') 182 183 .. _curses: https://docs.python.org/3/library/curses.html 184 .. _tigetstr: http://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/tigetstr.3 185 .. _tparm: http://man.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/tparm.3 186 .. _`terminfo(5)`: https://invisible-island.net/ncurses/man/terminfo.5.html 187 .. _str.center(): https://docs.python.org/3/library/stdtypes.html#str.center 188 .. _textwrap.wrap(): https://docs.python.org/3/library/textwrap.html#textwrap.wrap 189 .. _Terminal: https://blessed.readthedocs.io/en/stable/terminal.html 190 .. _`Terminal.fullscreen()`: https://blessed.readthedocs.io/en/latest/api/terminal.html#blessed.terminal.Terminal.fullscreen 191 .. _`Terminal.get_location()`: https://blessed.readthedocs.io/en/latest/location.html#finding-the-cursor 192 .. _`Terminal.color_rgb()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.color_rgb 193 .. _`Terminal.hidden_cursor()`: https://blessed.readthedocs.io/en/latest/api/terminal.html#blessed.terminal.Terminal.hidden_cursor 194 .. _`Terminal.on_color_rgb()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.on_color_rgb 195 .. _`Terminal.length()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.length 196 .. _`Terminal.strip()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.strip 197 .. _`Terminal.rstrip()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.rstrip 198 .. _`Terminal.lstrip()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.lstrip 199 .. _`Terminal.strip_seqs()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.strip_seqs 200 .. _`Terminal.wrap()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.wrap 201 .. _`Terminal.center()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.center 202 .. _`Terminal.rjust()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.rjust 203 .. _`Terminal.ljust()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.ljust 204 .. _`Terminal.cbreak()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.cbreak 205 .. _`Terminal.raw()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.raw 206 .. _`Terminal.inkey()`: https://blessed.readthedocs.io/en/stable/api/terminal.html#blessed.terminal.Terminal.inkey 207 .. _Colors: https://blessed.readthedocs.io/en/stable/colors.html 208 .. _Styles: https://blessed.readthedocs.io/en/stable/terminal.html#styles 209 .. _Location: https://blessed.readthedocs.io/en/stable/location.html 210 .. _Keyboard: https://blessed.readthedocs.io/en/stable/keyboard.html 211 .. _Examples: https://blessed.readthedocs.io/en/stable/examples.html 212 .. _x11-colorpicker.py: https://blessed.readthedocs.io/en/stable/examples.html#x11-colorpicker-py 213 .. _bounce.py: https://blessed.readthedocs.io/en/stable/examples.html#bounce-py 214 .. _worms.py: https://blessed.readthedocs.io/en/stable/examples.html#worms-py 215 .. _plasma.py: https://blessed.readthedocs.io/en/stable/examples.html#plasma-py 216 .. _Voltron: https://github.com/snare/voltron 217 .. _cursewords: https://github.com/thisisparker/cursewords 218 .. _GitHeat: https://github.com/AmmsA/Githeat 219 .. _Dashing: https://github.com/FedericoCeratto/dashing 220 .. _Enlighten: https://github.com/Rockhopper-Technologies/enlighten 221 .. _macht: https://github.com/rolfmorel/macht 222 .. _f-strings: https://docs.python.org/3/reference/lexical_analysis.html#f-strings 223 .. |pypi_downloads| image:: https://img.shields.io/pypi/dm/blessed.svg?logo=pypi 224 :alt: Downloads 225 :target: https://pypi.org/project/blessed/ 226 .. |codecov| image:: https://codecov.io/gh/jquast/blessed/branch/master/graph/badge.svg 227 :alt: codecov.io Code Coverage 228 :target: https://codecov.io/gh/jquast/blessed/ 229 .. |linux| image:: https://img.shields.io/badge/Linux-yes-success?logo=linux 230 :alt: Linux supported 231 .. |windows| image:: https://img.shields.io/badge/Windows-NEW-success?logo=windows 232 :alt: Windows supported 233 .. |mac| image:: https://img.shields.io/badge/MacOS-yes-success?logo=apple 234 :alt: MacOS supported 235 .. |bsd| image:: https://img.shields.io/badge/BSD-yes-success?logo=freebsd 236 :alt: BSD supported 237 238Keywords: terminal,sequences,tty,curses,ncurses,formatting,style,color,console,keyboard,ansi,xterm 239Platform: UNKNOWN 240Classifier: Intended Audience :: Developers 241Classifier: Natural Language :: English 242Classifier: Development Status :: 5 - Production/Stable 243Classifier: Environment :: Console 244Classifier: Environment :: Console :: Curses 245Classifier: License :: OSI Approved :: MIT License 246Classifier: Operating System :: POSIX 247Classifier: Operating System :: Microsoft :: Windows 248Classifier: Programming Language :: Python :: 2 249Classifier: Programming Language :: Python :: 2.7 250Classifier: Programming Language :: Python :: 3 251Classifier: Programming Language :: Python :: 3.4 252Classifier: Programming Language :: Python :: 3.5 253Classifier: Programming Language :: Python :: 3.6 254Classifier: Programming Language :: Python :: 3.7 255Classifier: Programming Language :: Python :: 3.8 256Classifier: Programming Language :: Python :: 3.9 257Classifier: Topic :: Software Development :: Libraries 258Classifier: Topic :: Software Development :: User Interfaces 259Classifier: Topic :: Terminals 260Classifier: Typing :: Typed 261Requires-Python: >=2.7 262
