From b871a5a1b1eb10e9740dc9564a09bf871459e9da Mon Sep 17 00:00:00 2001 From: Jeff Quast Date: Wed, 15 Apr 2015 14:27:03 -0700 Subject: Merge together 'Brief Overview' and 'The Pitch'. --- docs/intro.rst | 101 +++++++++++++++++++++++++++++---------------------------- 1 file changed, 51 insertions(+), 50 deletions(-) diff --git a/docs/intro.rst b/docs/intro.rst index fefb747..c7bf503 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -44,19 +44,38 @@ Coding with *Blessings* looks like this... :: print('You pressed ' + repr(inp)) -The Pitch ---------- +Brief Overview +-------------- *Blessings* is a more simplified wrapper around curses_, providing : * Styles, color, and maybe a little positioning without necessarily clearing the whole screen first. -* Leave more than one screenful of scrollback in the buffer after your program - exits, like a well-behaved command-line application should. -* No more C-like calls to tigetstr_ and tparm_. +* Works great with standard Python string formatting. +* Provides up-to-the-moment terminal height and width, so you can respond to + terminal size changes. +* Avoids making a mess if the output gets piped to a non-terminal: + outputs to any file-like object such as *StringIO*, files, or pipes. +* Uses the `terminfo(5)`_ database so it works with any terminal type + and supports any terminal capability: No more C-like calls to tigetstr_ + and tparm_. +* 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. +* Provides plenty of context managers to safely express terminal modes, + automatically restoring the terminal to a safe state on exit. * Act intelligently when somebody redirects your output to a file, omitting all of the terminal sequences such as styling, colors, or positioning. -* Dead-simple keyboard handling, modeled after the Basic language's *INKEY$* +* Dead-simple keyboard handling: safely decoding unicode input in your + system's preferred locale and supports application/arrow keys. +* Allows the printable length of strings containing sequences to be + determined. + +Blessings **does not** provide... + +* Windows command prompt support. A PDCurses_ build of python for windows + provides only partial support at this time -- there are plans to merge with + the ansi_ module in concert with colorama_ to resolve this. `Patches welcome + `_! Before And After @@ -83,14 +102,22 @@ print some underlined text at the bottom of the screen:: normal = tigetstr('sgr0') else: sc = cup = rc = underline = normal = '' - print(sc) # Save cursor position. + + # 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] - print(tparm(cup, height - 1, 0)) # Move cursor to bottom. - print('This is {under}underlined{normal}!'.format(under=underline, - normal=normal)) - print(rc) # Restore cursor position. + + # 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 *Blessings* is simply:: @@ -98,53 +125,26 @@ The same program with *Blessings* is simply:: term = Terminal() with term.location(0, term.height - 1): - print('This is' + term.underline('pretty!')) - - -Brief Overview --------------- - -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 -*Blessings* has your back: - -* Uses the `terminfo(5)`_ database so it works with any terminal type. -* 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. -* Safely decodes internationalization keyboard input to their unicod e - equivalents. -* Safely decodes multibyte sequences for application/arrow keys. -* Allows the printable length of strings containing sequences to be determined. -* Provides plenty of context managers to safely express various terminal modes, - restoring to a safe state upon exit. - -Blessings does not provide... - -* Native color support on the Windows command prompt. A PDCurses_ build - of python for windows provides only partial support at this time -- there - are plans to merge with the ansi_ module in concert with colorama_ to - resolve this. `Patches welcome - `_! + print('This is' + term.underline('underlined') + '!') Further Documentation --------------------- More documentation can be found at http://blessings.readthedocs.org/ -Developers, Bugs ----------------- +Bugs, Contributing, Support +--------------------------- + +**Bugs** or suggestions? Visit the `issue tracker`_ and file an issue. +We welcome your bug reports and feature suggestions! -Bugs or suggestions? Visit the `issue tracker`_. +Would you like to **contribute**? That's awesome! We've written a +`guide `_ +to help you. -Pull requests require test coverage, we aim for 100% test coverage. +Are you stuck and need **support**? Give `stackoverflow`_ a try. If +you're still having trouble, we'd like to hear about it! Open an issue +in the `issue tracker`_ with a well-formed question. License ------- @@ -159,3 +159,4 @@ Blessings is under the MIT License. See the LICENSE file. .. _colorama: https://pypi.python.org/pypi/colorama .. _PDCurses: http://www.lfd.uci.edu/~gohlke/pythonlibs/#curses .. _`terminfo(5)`: http://invisible-island.net/ncurses/man/terminfo.5.html +.. _`stackoverflow`: http://stackoverflow.com/ -- cgit v1.2.1