.. -*- mode: rst -*-

::

                       _
                      | |
         _ __   _   _ | |_  ___
        | '_ \ | | | || __|/ _ \
        | |_) || |_| || |_|  __/
        | .__/  \__, | \__|\___|
        | |      __/ |
        |_|     |___/      0.4.2

        -- chicks dig dudes with terminals (c) @samfoo


What is ``pyte``?
-----------------

What is ``pyte``? It's an in memory VTXXX-compatible terminal emulator.
*XXX* stands for a series video terminals, developed by
`DEC <http://en.wikipedia.org/wiki/Digital_Equipment_Corporation>`_ between
1970 and 1995. The first, and probably the most famous one, was VT100
terminal, which is now a de-facto standard for all virtual terminal
emulators. ``pyte`` follows the suit.

So, why would one need a terminal emulator library?

* To screen scrape terminal apps, for example ``htop`` or ``aptitude``.
* To write cross platform terminal emulators; either with a graphical
  (`xterm <http://invisible-island.net/xterm/>`_,
  `rxvt <http://www.rxvt.org/>`_) or a web interface, like
  `AjaxTerm <http://antony.lesuisse.org/software/ajaxterm/>`_.
* To have fun, hacking on the ancient, poorly documented technologies.

**Note**: ``pyte`` started as a fork of `vt102 <http://github.com/samfoo/vt102>`_,
which is an incomplete pure Python implementation of VT100 terminal.


Installation
------------

If you have `setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_
you can use ``easy_install -U pyte``. Otherwise, you can download the source
from `GitHub <http://github.com/selectel/pyte>`_ and run ``python setup.py install``.


Quick example
-------------

There are two important classes in ``pyte``: ``Screen`` and ``Stream``. The
``Screen`` is the terminal screen emulator. It maintains an in-memory
buffer of text and text-attributes to display on screen. The ``Stream``
is the stream processor. It manages the state of the input and dispatches
events to anything that's listening about things that are going on.
Events are things like ``LINEFEED``, ``DRAW "a"``, or ``CURSOR_POSITION 10 10``.
See the `API documentation` for more details.

In general, if you just want to know what's being displayed on screen you
can do something like the following:

    >>> import pyte
    >>> screen = pyte.Screen(80, 24)
    >>> stream = pyte.Stream()
    >>> stream.attach(screen)
    >>> stream.feed("Hello World!")
    >>> screen.display
        ['Hello World!                                                                    ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ',
         '                                                                                ']


Alternatives
------------

``pyte`` is not alone in the weird world of terminal emulator libraries,
here's a few other options worth checking out:
`Termemulator <http://sourceforge.net/projects/termemulator/>`_,
`pyqonsole <http://hg.logilab.org/pyqonsole/>`_,
`webtty <http://code.google.com/p/webtty/>`_
`AjaxTerm <http://antony.lesuisse.org/software/ajaxterm/>`_ and of course
`vt102 <http://github.com/samfoo/vt102>`_.
