1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/python/blessings/PKG-INFO Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,426 @@
1.4 +Metadata-Version: 1.0
1.5 +Name: blessings
1.6 +Version: 1.3
1.7 +Summary: A thin, practical wrapper around terminal formatting, positioning, and more
1.8 +Home-page: https://github.com/erikrose/blessings
1.9 +Author: Erik Rose
1.10 +Author-email: erikrose@grinchcentral.com
1.11 +License: MIT
1.12 +Description: =========
1.13 + Blessings
1.14 + =========
1.15 +
1.16 + Coding with Blessings looks like this... ::
1.17 +
1.18 + from blessings import Terminal
1.19 +
1.20 + t = Terminal()
1.21 +
1.22 + print t.bold('Hi there!')
1.23 + print t.bold_red_on_bright_green('It hurts my eyes!')
1.24 +
1.25 + with t.location(0, t.height - 1):
1.26 + print 'This is at the bottom.'
1.27 +
1.28 + Or, for byte-level control, you can drop down and play with raw terminal
1.29 + capabilities::
1.30 +
1.31 + print '{t.bold}All your {t.red}bold and red base{t.normal}'.format(t=t)
1.32 + print t.wingo(2)
1.33 +
1.34 + The Pitch
1.35 + =========
1.36 +
1.37 + Blessings lifts several of curses_' limiting assumptions, and it makes your
1.38 + code pretty, too:
1.39 +
1.40 + * Use styles, color, and maybe a little positioning without clearing the whole
1.41 + screen first.
1.42 + * Leave more than one screenful of scrollback in the buffer after your program
1.43 + exits, like a well-behaved command-line app should.
1.44 + * Get rid of all those noisy, C-like calls to ``tigetstr`` and ``tparm``, so
1.45 + your code doesn't get crowded out by terminal bookkeeping.
1.46 + * Act intelligently when somebody redirects your output to a file, omitting the
1.47 + terminal control codes the user doesn't want to see (optional).
1.48 +
1.49 + .. _curses: http://docs.python.org/library/curses.html
1.50 +
1.51 + Before And After
1.52 + ----------------
1.53 +
1.54 + Without Blessings, this is how you'd print some underlined text at the bottom
1.55 + of the screen::
1.56 +
1.57 + from curses import tigetstr, setupterm, tparm
1.58 + from fcntl import ioctl
1.59 + from os import isatty
1.60 + import struct
1.61 + import sys
1.62 + from termios import TIOCGWINSZ
1.63 +
1.64 + # If we want to tolerate having our output piped to other commands or
1.65 + # files without crashing, we need to do all this branching:
1.66 + if hasattr(sys.stdout, 'fileno') and isatty(sys.stdout.fileno()):
1.67 + setupterm()
1.68 + sc = tigetstr('sc')
1.69 + cup = tigetstr('cup')
1.70 + rc = tigetstr('rc')
1.71 + underline = tigetstr('smul')
1.72 + normal = tigetstr('sgr0')
1.73 + else:
1.74 + sc = cup = rc = underline = normal = ''
1.75 + print sc # Save cursor position.
1.76 + if cup:
1.77 + # tigetnum('lines') doesn't always update promptly, hence this:
1.78 + height = struct.unpack('hhhh', ioctl(0, TIOCGWINSZ, '\000' * 8))[0]
1.79 + print tparm(cup, height - 1, 0) # Move cursor to bottom.
1.80 + print 'This is {under}underlined{normal}!'.format(under=underline,
1.81 + normal=normal)
1.82 + print rc # Restore cursor position.
1.83 +
1.84 + Phew! That was long and full of incomprehensible trash! Let's try it again,
1.85 + this time with Blessings::
1.86 +
1.87 + from blessings import Terminal
1.88 +
1.89 + term = Terminal()
1.90 + with term.location(0, term.height - 1):
1.91 + print 'This is', term.underline('pretty!')
1.92 +
1.93 + Much better.
1.94 +
1.95 + What It Provides
1.96 + ================
1.97 +
1.98 + Blessings provides just one top-level object: ``Terminal``. Instantiating a
1.99 + ``Terminal`` figures out whether you're on a terminal at all and, if so, does
1.100 + any necessary terminal setup. After that, you can proceed to ask it all sorts
1.101 + of things about the terminal. Terminal terminal terminal.
1.102 +
1.103 + Simple Formatting
1.104 + -----------------
1.105 +
1.106 + Lots of handy formatting codes ("capabilities" in low-level parlance) are
1.107 + available as attributes on a ``Terminal``. For example::
1.108 +
1.109 + from blessings import Terminal
1.110 +
1.111 + term = Terminal()
1.112 + print 'I am ' + term.bold + 'bold' + term.normal + '!'
1.113 +
1.114 + You can also use them as wrappers so you don't have to say ``normal``
1.115 + afterward::
1.116 +
1.117 + print 'I am', term.bold('bold') + '!'
1.118 +
1.119 + Or, if you want fine-grained control while maintaining some semblance of
1.120 + brevity, you can combine it with Python's string formatting, which makes
1.121 + attributes easy to access::
1.122 +
1.123 + print 'All your {t.red}base {t.underline}are belong to us{t.normal}'.format(t=term)
1.124 +
1.125 + Simple capabilities of interest include...
1.126 +
1.127 + * ``bold``
1.128 + * ``reverse``
1.129 + * ``underline``
1.130 + * ``no_underline`` (which turns off underlining)
1.131 + * ``blink``
1.132 + * ``normal`` (which turns off everything, even colors)
1.133 + * ``clear_eol`` (clear to the end of the line)
1.134 + * ``clear_bol`` (clear to beginning of line)
1.135 + * ``clear_eos`` (clear to end of screen)
1.136 +
1.137 + Here are a few more which are less likely to work on all terminals:
1.138 +
1.139 + * ``dim``
1.140 + * ``italic`` and ``no_italic``
1.141 + * ``shadow`` and ``no_shadow``
1.142 + * ``standout`` and ``no_standout``
1.143 + * ``subscript`` and ``no_subscript``
1.144 + * ``superscript`` and ``no_superscript``
1.145 + * ``flash`` (which flashes the screen once)
1.146 +
1.147 + Note that, while the inverse of ``underline`` is ``no_underline``, the only way
1.148 + to turn off ``bold`` or ``reverse`` is ``normal``, which also cancels any
1.149 + custom colors. This is because there's no way to tell the terminal to undo
1.150 + certain pieces of formatting, even at the lowest level.
1.151 +
1.152 + You might notice that the above aren't the typical incomprehensible terminfo
1.153 + capability names; we alias a few of the harder-to-remember ones for
1.154 + readability. However, you aren't limited to these: you can reference any
1.155 + string-returning capability listed on the `terminfo man page`_ by the name
1.156 + under the "Cap-name" column: for example, ``term.rum``.
1.157 +
1.158 + .. _`terminfo man page`: http://www.manpagez.com/man/5/terminfo/
1.159 +
1.160 + Color
1.161 + -----
1.162 +
1.163 + 16 colors, both foreground and background, are available as easy-to-remember
1.164 + attributes::
1.165 +
1.166 + from blessings import Terminal
1.167 +
1.168 + term = Terminal()
1.169 + print term.red + term.on_green + 'Red on green? Ick!' + term.normal
1.170 + print term.bright_red + term.on_bright_blue + 'This is even worse!' + term.normal
1.171 +
1.172 + You can also call them as wrappers, which sets everything back to normal at the
1.173 + end::
1.174 +
1.175 + print term.red_on_green('Red on green? Ick!')
1.176 + print term.yellow('I can barely see it.')
1.177 +
1.178 + The available colors are...
1.179 +
1.180 + * ``black``
1.181 + * ``red``
1.182 + * ``green``
1.183 + * ``yellow``
1.184 + * ``blue``
1.185 + * ``magenta``
1.186 + * ``cyan``
1.187 + * ``white``
1.188 +
1.189 + You can set the background color instead of the foreground by prepending
1.190 + ``on_``, as in ``on_blue``. There is also a ``bright`` version of each color:
1.191 + for example, ``on_bright_blue``.
1.192 +
1.193 + There is also a numerical interface to colors, which takes an integer from
1.194 + 0-15::
1.195 +
1.196 + term.color(5) + 'Hello' + term.normal
1.197 + term.on_color(3) + 'Hello' + term.normal
1.198 +
1.199 + term.color(5)('Hello')
1.200 + term.on_color(3)('Hello')
1.201 +
1.202 + If some color is unsupported (for instance, if only the normal colors are
1.203 + available, not the bright ones), trying to use it will, on most terminals, have
1.204 + no effect: the foreground and background colors will stay as they were. You can
1.205 + get fancy and do different things depending on the supported colors by checking
1.206 + `number_of_colors`_.
1.207 +
1.208 + .. _`number_of_colors`: http://packages.python.org/blessings/#blessings.Terminal.number_of_colors
1.209 +
1.210 + Compound Formatting
1.211 + -------------------
1.212 +
1.213 + If you want to do lots of crazy formatting all at once, you can just mash it
1.214 + all together::
1.215 +
1.216 + from blessings import Terminal
1.217 +
1.218 + term = Terminal()
1.219 + print term.bold_underline_green_on_yellow + 'Woo' + term.normal
1.220 +
1.221 + Or you can use your newly coined attribute as a wrapper, which implicitly sets
1.222 + everything back to normal afterward::
1.223 +
1.224 + print term.bold_underline_green_on_yellow('Woo')
1.225 +
1.226 + This compound notation comes in handy if you want to allow users to customize
1.227 + the formatting of your app: just have them pass in a format specifier like
1.228 + "bold_green" on the command line, and do a quick ``getattr(term,
1.229 + that_option)('Your text')`` when you do your formatting.
1.230 +
1.231 + I'd be remiss if I didn't credit couleur_, where I probably got the idea for
1.232 + all this mashing.
1.233 +
1.234 + .. _couleur: http://pypi.python.org/pypi/couleur
1.235 +
1.236 + Parametrized Capabilities
1.237 + -------------------------
1.238 +
1.239 + Some capabilities take parameters. Rather than making you dig up ``tparm()``
1.240 + all the time, we simply make such capabilities into callable strings. You can
1.241 + pass the parameters right in::
1.242 +
1.243 + from blessings import Terminal
1.244 +
1.245 + term = Terminal()
1.246 + print term.move(10, 1)
1.247 +
1.248 + Here are some of interest:
1.249 +
1.250 + ``move``
1.251 + Position the cursor elsewhere. Parameters are y coordinate, then x
1.252 + coordinate.
1.253 + ``move_x``
1.254 + Move the cursor to the given column.
1.255 + ``move_y``
1.256 + Move the cursor to the given row.
1.257 +
1.258 + You can also reference any other string-returning capability listed on the
1.259 + `terminfo man page`_ by its name under the "Cap-name" column.
1.260 +
1.261 + .. _`terminfo man page`: http://www.manpagez.com/man/5/terminfo/
1.262 +
1.263 + Height and Width
1.264 + ----------------
1.265 +
1.266 + It's simple to get the height and width of the terminal, in characters::
1.267 +
1.268 + from blessings import Terminal
1.269 +
1.270 + term = Terminal()
1.271 + height = term.height
1.272 + width = term.width
1.273 +
1.274 + These are newly updated each time you ask for them, so they're safe to use from
1.275 + SIGWINCH handlers.
1.276 +
1.277 + Temporary Repositioning
1.278 + -----------------------
1.279 +
1.280 + Sometimes you need to flit to a certain location, print something, and then
1.281 + return: for example, when updating a progress bar at the bottom of the screen.
1.282 + ``Terminal`` provides a context manager for doing this concisely::
1.283 +
1.284 + from blessings import Terminal
1.285 +
1.286 + term = Terminal()
1.287 + with term.location(0, term.height - 1):
1.288 + print 'Here is the bottom.'
1.289 + print 'This is back where I came from.'
1.290 +
1.291 + Parameters to ``location()`` are ``x`` and then ``y``, but you can also pass
1.292 + just one of them, leaving the other alone. For example... ::
1.293 +
1.294 + with term.location(y=10):
1.295 + print 'We changed just the row.'
1.296 +
1.297 + If you want to reposition permanently, see ``move``, in an example above.
1.298 +
1.299 + Pipe Savvy
1.300 + ----------
1.301 +
1.302 + If your program isn't attached to a terminal, like if it's being piped to
1.303 + another command or redirected to a file, all the capability attributes on
1.304 + ``Terminal`` will return empty strings. You'll get a nice-looking file without
1.305 + any formatting codes gumming up the works.
1.306 +
1.307 + If you want to override this--like if you anticipate your program being piped
1.308 + through ``less -r``, which handles terminal escapes just fine--pass
1.309 + ``force_styling=True`` to the ``Terminal`` constructor.
1.310 +
1.311 + In any case, there is an ``is_a_tty`` attribute on ``Terminal`` that lets you
1.312 + see whether the attached stream seems to be a terminal. If it's false, you
1.313 + might refrain from drawing progress bars and other frippery, since you're
1.314 + apparently headed into a pipe::
1.315 +
1.316 + from blessings import Terminal
1.317 +
1.318 + term = Terminal()
1.319 + if term.is_a_tty:
1.320 + with term.location(0, term.height - 1):
1.321 + print 'Progress: [=======> ]'
1.322 + print term.bold('Important stuff')
1.323 +
1.324 + Shopping List
1.325 + =============
1.326 +
1.327 + There are decades of legacy tied up in terminal interaction, so attention to
1.328 + detail and behavior in edge cases make a difference. Here are some ways
1.329 + Blessings has your back:
1.330 +
1.331 + * Uses the terminfo database so it works with any terminal type
1.332 + * Provides up-to-the-moment terminal height and width, so you can respond to
1.333 + terminal size changes (SIGWINCH signals). (Most other libraries query the
1.334 + ``COLUMNS`` and ``LINES`` environment variables or the ``cols`` or ``lines``
1.335 + terminal capabilities, which don't update promptly, if at all.)
1.336 + * Avoids making a mess if the output gets piped to a non-terminal
1.337 + * Works great with standard Python string templating
1.338 + * Provides convenient access to all terminal capabilities, not just a sugared
1.339 + few
1.340 + * Outputs to any file-like object, not just stdout
1.341 + * Keeps a minimum of internal state, so you can feel free to mix and match with
1.342 + calls to curses or whatever other terminal libraries you like
1.343 +
1.344 + Blessings does not provide...
1.345 +
1.346 + * Native color support on the Windows command prompt. However, it should work
1.347 + when used in concert with colorama_.
1.348 +
1.349 + .. _colorama: http://pypi.python.org/pypi/colorama/0.2.4
1.350 +
1.351 + Bugs
1.352 + ====
1.353 +
1.354 + Bugs or suggestions? Visit the `issue tracker`_.
1.355 +
1.356 + .. _`issue tracker`: https://github.com/erikrose/blessings/issues/new
1.357 +
1.358 + License
1.359 + =======
1.360 +
1.361 + Blessings is under the MIT License. See the LICENSE file.
1.362 +
1.363 + Version History
1.364 + ===============
1.365 +
1.366 + 1.3
1.367 + * Add ``number_of_colors``, which tells you how many colors the terminal
1.368 + supports.
1.369 + * Made ``color(n)`` and ``on_color(n)`` callable to wrap a string, like the
1.370 + named colors can. Also, make them both fall back to the ``setf`` and
1.371 + ``setb`` capabilities (like the named colors do) if the ANSI ``setaf`` and
1.372 + ``setab`` aren't available.
1.373 + * Allow ``color`` attr to act as an unparametrized string, not just a
1.374 + callable.
1.375 + * Make ``height`` and ``width`` examine any passed-in stream before falling
1.376 + back to stdout. (This rarely if ever affects actual behavior; it's mostly
1.377 + philosophical.)
1.378 + * Make caching simpler and slightly more efficient.
1.379 + * Get rid of a reference cycle between Terminals and FormattingStrings.
1.380 + * Update docs to reflect that terminal addressing (as in ``location()``) is
1.381 + 0-based.
1.382 +
1.383 + 1.2
1.384 + * Added support for Python 3! We need 3.2.3 or greater, because the curses
1.385 + library couldn't decide whether to accept strs or bytes before that
1.386 + (http://bugs.python.org/issue10570).
1.387 + * Everything that comes out of the library is now unicode. This lets us
1.388 + support Python 3 without making a mess of the code, and Python 2 should
1.389 + continue to work unless you were testing types (and badly). Please file a
1.390 + bug if this causes trouble for you.
1.391 + * Changed to the MIT License for better world domination.
1.392 + * Added Sphinx docs.
1.393 +
1.394 + 1.1
1.395 + * Added nicely named attributes for colors.
1.396 + * Introduced compound formatting.
1.397 + * Added wrapper behavior for styling and colors.
1.398 + * Let you force capabilities to be non-empty, even if the output stream is
1.399 + not a terminal.
1.400 + * Added the ``is_a_tty`` attribute for telling whether the output stream is a
1.401 + terminal.
1.402 + * Sugared the remaining interesting string capabilities.
1.403 + * Let ``location()`` operate on just an x *or* y coordinate.
1.404 +
1.405 + 1.0
1.406 + * Extracted Blessings from nose-progressive, my `progress-bar-having,
1.407 + traceback-shortcutting, rootin', tootin' testrunner`_. It provided the
1.408 + tootin' functionality.
1.409 +
1.410 + .. _`progress-bar-having, traceback-shortcutting, rootin', tootin' testrunner`: http://pypi.python.org/pypi/nose-progressive/
1.411 +
1.412 +Keywords: terminal,tty,curses,ncurses,formatting,style,color,console
1.413 +Platform: UNKNOWN
1.414 +Classifier: Intended Audience :: Developers
1.415 +Classifier: Natural Language :: English
1.416 +Classifier: Development Status :: 5 - Production/Stable
1.417 +Classifier: Environment :: Console
1.418 +Classifier: Environment :: Console :: Curses
1.419 +Classifier: License :: OSI Approved :: MIT License
1.420 +Classifier: Operating System :: POSIX
1.421 +Classifier: Programming Language :: Python :: 2
1.422 +Classifier: Programming Language :: Python :: 2.5
1.423 +Classifier: Programming Language :: Python :: 2.6
1.424 +Classifier: Programming Language :: Python :: 2.7
1.425 +Classifier: Programming Language :: Python :: 3
1.426 +Classifier: Programming Language :: Python :: 3.2
1.427 +Classifier: Topic :: Software Development :: Libraries
1.428 +Classifier: Topic :: Software Development :: User Interfaces
1.429 +Classifier: Topic :: Terminals
