Metadata-Version: 2.0
Name: blessed
Version: 1.10.0
Summary: A thin, practical wrapper around terminal styling, screen positioning, and keyboard input.
Home-page: https://github.com/erikrose/blessed
Author: Jeff Quast, Erik Rose
Author-email: contact@jeffquast.com
License: MIT
Keywords: terminal,sequences,tty,curses,ncurses,formatting,style,color,console,keyboard,ansi,xterm
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Terminals
Requires-Dist: wcwidth (>=0.1.4)
Requires-Dist: six (>=1.9.0)

.. image:: https://img.shields.io/travis/jquast/blessed.svg
    :alt: Travis Continuous Integration
    :target: https://travis-ci.org/jquast/blessed/

.. image:: https://img.shields.io/teamcity/http/teamcity-master.pexpect.org/s/Blessed_BuildHead.png
    :alt: TeamCity Build status
    :target: https://teamcity-master.pexpect.org/viewType.html?buildTypeId=Blessed_BuildHead&branch_Blessed=%3Cdefault%3E&tab=buildTypeStatusDiv

.. image:: https://img.shields.io/coveralls/jekyll/jekyll/master.svg
    :alt: Coveralls Code Coverage
    :target: https://coveralls.io/r/jquast/blessed?branch=master

.. image:: https://img.shields.io/pypi/v/blessed.svg
    :alt: Latest Version
    :target: https://pypi.python.org/pypi/blessed

.. image:: https://img.shields.io/pypi/dm/blessed.svg
    :alt: Downloads
    :target: https://pypi.python.org/pypi/blessed

Introduction
============

Blessed is a thin, practical wrapper around terminal capabilities in Python.

Coding with *Blessed* looks like this... ::

    from blessed import Terminal

    t = Terminal()

    print(t.bold('Hi there!'))
    print(t.bold_red_on_bright_green('It hurts my eyes!'))

    with t.location(0, t.height - 1):
        print(t.center(t.blink('press any key to continue.')))

    with t.cbreak():
        inp = t.inkey()
    print('You pressed ' + repr(inp))


Brief Overview
--------------

*Blessed* is a more simplified wrapper around curses_, providing :

* Styles, color, and maybe a little positioning without necessarily
  clearing the whole screen first.
* 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: 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.

Blessed **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 <https://github.com/jquast/blessed/issues/18>`_!


Before And After
----------------

With the built-in curses_ module, this is how you would typically
print some underlined text at the bottom of the screen::

    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::

    from blessed import Terminal

    term = Terminal()
    with term.location(0, term.height - 1):
        print('This is' + term.underline('underlined') + '!')

Further Documentation
---------------------

More documentation can be found at http://blessed.readthedocs.org/en/latest/

Bugs, Contributing, Support
---------------------------

**Bugs** or suggestions? Visit the `issue tracker`_ and file an issue.
We welcome your bug reports and feature suggestions!

Would you like to **contribute**?  That's awesome!  We've written a
`guide <http://blessed.readthedocs.org/en/latest/contributing.html>`_
to help you.

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
-------

Blessed is under the MIT License. See the LICENSE file.

Forked
------

Blessed is a fork of `blessings <https://github.com/erikrose/blessings>`_.
Changes since 1.7 have all been proposed but unaccepted upstream.

Furthermore, a project in the node.js language of the `same name
<https://github.com/chjj/blessed>`_ is **not** related, or a fork
of each other in any way.

.. _`issue tracker`: https://github.com/jquast/blessed/issues/
.. _curses: https://docs.python.org/3/library/curses.html
.. _tigetstr: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/tigetstr.3
.. _tparm: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/tparm.3
.. _ansi: https://github.com/tehmaze/ansi
.. _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/


Version History
===============
1.10
  * workaround: provide ``sc`` and ``rc`` for Terminals of ``kind='ansi'``,
    repairing :meth:`~.Terminal.location` :ghissue:`44`.
  * bugfix: length of simple SGR reset sequence ``\x1b[m`` was not correctly
    determined on all terminal types, :ghissue:`45`.
  * deprecated: ``_intr_continue`` arguments introduced in 1.8 are now marked
    deprecated in 1.10: beginning with python 3.5, the default behavior is as
    though this argument is always True, `PEP-475
    <https://www.python.org/dev/peps/pep-0475/>`_, blessed does the same.

1.9
  * enhancement: :paramref:`~.Terminal.wrap.break_long_words` now supported by
    :meth:`Terminal.wrap`
  * Ignore :class:`curses.error` message ``'tparm() returned NULL'``:
    this occurs on win32 or other platforms using a limited curses
    implementation, such as PDCurses_, where :func:`curses.tparm` is
    not implemented, or no terminal capability database is available.
  * Context manager :meth:`~.keypad` emits sequences that enable
    "application keys" such as the diagonal keys on the numpad.
    This is equivalent to :meth:`curses.window.keypad`.
  * bugfix: translate keypad application keys correctly.
  * enhancement: no longer depend on the '2to3' tool for python 3 support.
  * enhancement: allow ``civis`` and ``cnorm`` (*hide_cursor*, *normal_hide*)
    to work with terminal-type *ansi* by emulating support by proxy.
  * enhancement: new public attribute: :attr:`~.kind`: the very same as given
    :paramref:`Terminal.__init__.kind` keyword argument.  Or, when not given,
    determined by and equivalent to the ``TERM`` Environment variable.

1.8
  * enhancement: export keyboard-read function as public method ``getch()``,
    so that it may be overridden by custom terminal implementers.
  * enhancement: allow :meth:`~.inkey` and :meth:`~.kbhit` to return early
    when interrupted by signal by passing argument ``_intr_continue=False``.
  * enhancement: allow ``hpa`` and ``vpa`` (*move_x*, *move_y*) to work on
    tmux(1) or screen(1) by emulating support by proxy.
  * enhancement: add :meth:`~.Terminal.rstrip` and :meth:`~.Terminal.lstrip`,
    strips both sequences and trailing or leading whitespace, respectively.
  * enhancement: include wcwidth_ library support for
    :meth:`~.Terminal.length`: the printable width of many kinds of CJK
    (Chinese, Japanese, Korean) ideographs and various combining characters
    may now be determined.
  * enhancement: better support for detecting the length or sequences of
    externally-generated *ecma-48* codes when using ``xterm`` or ``aixterm``.
  * bugfix: when :func:`locale.getpreferredencoding` returns empty string or
    an encoding that is not valid for ``codecs.getincrementaldecoder``,
    fallback to ASCII and emit a warning.
  * bugfix: ensure :class:`~.FormattingString` and
    :class:`~.ParameterizingString` may be pickled.
  * bugfix: allow `~.inkey` and related to be called without a keyboard.
  * **change**: ``term.keyboard_fd`` is set ``None`` if ``stream`` or
    ``sys.stdout`` is not a tty, making ``term.inkey()``, ``term.cbreak()``,
    ``term.raw()``, no-op.
  * bugfix: ``\x1bOH`` (KEY_HOME) was incorrectly mapped as KEY_LEFT.

1.7
  * Forked github project `erikrose/blessings`_ to `jquast/blessed`_, this
    project was previously known as **blessings** version 1.6 and prior.
  * introduced: context manager :meth:`~.cbreak`, which is equivalent to
    entering terminal state by :func:`tty.setcbreak` and returning
    on exit, as well as the lesser recommended :meth:`~.raw`,
    pairing from :func:`tty.setraw`.
  * introduced: :meth:`~.inkey`, which will return one or more characters
    received by the keyboard as a unicode sequence, with additional attributes
    :attr:`~.Keystroke.code` and :attr:`~.Keystroke.name`.  This allows
    application keys (such as the up arrow, or home key) to be detected.
    Optional value :paramref:`~.inkey.timeout` allows for timed poll.
  * introduced: :meth:`~.Terminal.center`, :meth:`~.Terminal.rjust`,
    :meth:`~.Terminal.ljust`, allowing text containing sequences to be aligned
    to detected horizontal screen width, or by
    :paramref:`~.Terminal.center.width` specified.
  * introduced: :meth:`~.wrap` method.  Allows text containing sequences to be
    word-wrapped without breaking mid-sequence, honoring their printable width.
  * introduced: :meth:`~.Terminal.strip`, strips all sequences *and*
    whitespace.
  * introduced: :meth:`~.Terminal.strip_seqs` strip only sequences.
  * introduced: :meth:`~.Terminal.rstrip` and :meth:`~.Terminal.lstrip` strips
    both sequences and trailing or leading whitespace, respectively.
  * bugfix: cannot call :func:`curses.setupterm` more than once per process
    (from :meth:`Terminal.__init__`):  Previously, blessed pretended
    to support several instances of different Terminal :attr:`~.kind`, but was
    actually using the :attr:`~.kind` specified by the first instantiation of
    :class:`~.Terminal`.  A warning is now issued.  Although this is
    misbehavior is still allowed, a :class:`warnings.WarningMessage` is now
    emitted to notify about subsequent terminal misbehavior.
  * bugfix: resolved issue where :attr:`~.number_of_colors` fails when
    :attr:`~.does_styling` is ``False``.  Resolves issue where piping tests
    output would fail.
  * bugfix: warn and set :attr:`~.does_styling` to ``False`` when the given
    :attr:`~.kind` is not found in the terminal capability database.
  * bugfix: allow unsupported terminal capabilities to be callable just as
    supported capabilities, so that the return value of
    :attr:`~.color`\(n) may be called on terminals without color
    capabilities.
  * bugfix: for terminals without underline, such as vt220,
    ``term.underline('text')`` would emit ``u'text' + term.normal``.
    Now it emits only ``u'text'``.
  * enhancement: some attributes are now properties, raise exceptions when
    assigned.
  * enhancement: pypy is now a supported python platform implementation.
  * enhancement: removed pokemon ``curses.error`` exceptions.
  * enhancement: do not ignore :class:`curses.error` exceptions, unhandled
    curses errors are legitimate errors and should be reported as a bug.
  * enhancement: converted nose tests to pytest, merged travis and tox.
  * enhancement: pytest fixtures, paired with a new ``@as_subprocess``
    decorator
    are used to test a multitude of terminal types.
  * enhancement: test accessories ``@as_subprocess`` resolves various issues
    with different terminal types that previously went untested.
  * deprecation: python2.5 is no longer supported (as tox does not supported).

1.6
  * Add :attr:`~.does_styling`. This takes :attr:`~.force_styling`
    into account and should replace most uses of :attr:`~.is_a_tty`.
  * Make :attr:`~.is_a_tty` a read-only property like :attr:`~.does_styling`.
    Writing to it never would have done anything constructive.
  * Add :meth:`~.fullscreen`` and :meth:`hidden_cursor` to the
    auto-generated docs.

1.5.1
  * Clean up fabfile, removing the redundant ``test`` command.
  * Add Travis support.
  * Make ``python setup.py test`` work without spurious errors on 2.6.
  * Work around a tox parsing bug in its config file.
  * Make context managers clean up after themselves even if there's an
    exception (Vitja Makarov :ghpull:`29`).
  * Parameterizing a capability no longer crashes when there is no tty
    (Vitja Makarov :ghpull:`31`)

1.5
  * Add syntactic sugar and documentation for ``enter_fullscreen``
    and ``exit_fullscreen``.
  * Add context managers :meth:`~.fullscreen` and :meth:`~.hidden_cursor`.
  * Now you can force a :class:`~.Terminal` to never to emit styles by
    passing keyword argument ``force_styling=None``.

1.4
  * Add syntactic sugar for cursor visibility control and single-space-movement
    capabilities.
  * Endorse the :meth:`~.location` context manager for restoring cursor
    position after a series of manual movements.
  * Fix a bug in which :meth:`~.location` that wouldn't do anything when
    passed zeros.
  * Allow tests to be run with ``python setup.py test``.

1.3
  * Added :attr:`~.number_of_colors`, which tells you how many colors the
    terminal supports.
  * Made :attr:`~.color`\(n) and :attr:`~.on_color`\(n) callable to wrap a
    string, like the named colors can. Also, make them both fall back to the
    ``setf`` and ``setb`` capabilities (like the named colors do) if the
    termcap entries for ``setaf`` and ``setab`` are not available.
  * Allowed :attr:`~.color` to act as an unparametrized string, not just a
    callable.
  * Made :attr:`~.height` and :attr:`~.width` examine any passed-in stream
    before falling back to stdout (This rarely if ever affects actual behavior;
    it's mostly philosophical).
  * Made caching simpler and slightly more efficient.
  * Got rid of a reference cycle between :class:`~.Terminal` and
    :class:`~.FormattingString`.
  * Updated docs to reflect that terminal addressing (as in :meth:`~location`)
    is 0-based.

1.2
  * Added support for Python 3! We need 3.2.3 or greater, because the curses
    library couldn't decide whether to accept strs or bytes before that
    (http://bugs.python.org/issue10570).
  * Everything that comes out of the library is now unicode. This lets us
    support Python 3 without making a mess of the code, and Python 2 should
    continue to work unless you were testing types (and badly). Please file a
    bug if this causes trouble for you.
  * Changed to the MIT License for better world domination.
  * Added Sphinx docs.

1.1
  * Added nicely named attributes for colors.
  * Introduced compound formatting.
  * Added wrapper behavior for styling and colors.
  * Let you force capabilities to be non-empty, even if the output stream is
    not a terminal.
  * Added :attr:`~.is_a_tty` to determine whether the output stream is a
    terminal.
  * Sugared the remaining interesting string capabilities.
  * Allow :meth:`~.location` to operate on just an x *or* y coordinate.

1.0
  * Extracted Blessed from `nose-progressive`_.


.. _`nose-progressive`: http://pypi.python.org/pypi/nose-progressive/
.. _`erikrose/blessings`: https://github.com/erikrose/blessings
.. _`jquast/blessed`: https://github.com/jquast/blessed
.. _`issue tracker`: https://github.com/jquast/blessed/issues/
.. _curses: https://docs.python.org/library/curses.html
.. _couleur: https://pypi.python.org/pypi/couleur
.. _colorama: https://pypi.python.org/pypi/colorama
.. _wcwidth: https://pypi.python.org/pypi/wcwidth
.. _`cbreak(3)`: http://www.openbsd.org/cgi-bin/man.cgi?query=cbreak&apropos=0&sektion=3
.. _`curs_getch(3)`: http://www.openbsd.org/cgi-bin/man.cgi?query=curs_getch&apropos=0&sektion=3
.. _`termios(4)`: http://www.openbsd.org/cgi-bin/man.cgi?query=termios&apropos=0&sektion=4
.. _`terminfo(5)`: http://www.openbsd.org/cgi-bin/man.cgi?query=terminfo&apropos=0&sektion=5
.. _tigetstr: http://www.openbsd.org/cgi-bin/man.cgi?query=tigetstr&sektion=3
.. _tparm: http://www.openbsd.org/cgi-bin/man.cgi?query=tparm&sektion=3
.. _SIGWINCH: https://en.wikipedia.org/wiki/SIGWINCH
.. _`API Documentation`: http://blessed.rtfd.org
.. _`PDCurses`: http://www.lfd.uci.edu/~gohlke/pythonlibs/#curses
.. _`ansi`: https://github.com/tehmaze/ansi


