Moving ptpython code out of the prompt-toolkit repository.

We have a separate ptpython repository now.

Author: jonathanslenders

README.rst

@@ -4,31 +4,51 @@ Python Prompt Toolkit
 |Build Status| |PyPI|
 
 ``prompt_toolkit`` is a Library for building powerful interactive command lines
-in Python. It ships with a nice interactive Python shell (called ``ptpython``)
-built on top of the library.
+in Python.
 
-``prompt_toolkit`` could be a replacement for ``readline``, but it can be much
+Looking for ptpython, the Python REPL?
+**************************************
+
+Are you looking for the interactive Python Shell? We moved the ``ptpython``
+source code in a separate repository This way we are sure not to pollute the
+``prompt_toolkit`` library with any ``ptpython`` specific stuff and
+``ptpython`` can be developed independently. You will now have to install it
+through::
+
+ pip install ptpython
+
+`Go to ptpython... <http://github.com/jonathanslenders/ptpython/>`_
+
+.. image :: docs/images/ptpython.png
+
+prompt-toolkit features
+***********************
+
+``prompt_toolkit`` could be a replacement for `GNU readline
+<http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html>`_, but it can be much
 more than that.
 
-Features:
+Some features:
 
 - Pure Python.
 - Syntax highlighting of the input while typing. (For instance, with a Pygments lexer.)
 - Multi-line input editing.
 - Advanced code completion.
 - Both Emacs and Vi key bindings. (Similar to readline.)
 - Reverse and forward incremental search.
-- Both Python 3 and Python 2.7 support.
+- Runs on all Python versions from 2.6 up to 3.4.
 - Works well with Unicode double width characters. (Chinese input.)
 - Selecting text for copy/paste. (Both Emacs and Vi style.)
+- Multiple input buffers.
 - No global state.
+- Lightweight, the only dependencies are Pygments, six and wcwidth.
 - Code written with love.
 - Runs on Linux, OS X, OpenBSD and Windows systems.
 
-
 Feel free to create tickets for bugs and feature requests, and create pull
 requests if you have nice patches that you would like to share with others.
 
+
 About Windows support
 *********************
 
@@ -38,11 +58,8 @@ different event loop (``WaitForMultipleObjects`` instead of ``select``), and
 another input and output system. (Win32 APIs instead of pseudo-terminals and
 VT100.)
 
-.. image :: docs/images/ptpython-windows.png
-
-
 That should work fine, however the library is currently much more tested on
-Linux and Mac os X systems. So, if you find any bugs in the Windows
+Linux and Mac OS X systems. So, if you find any bugs in the Windows
 implementation, or you have an idea how to make the experience better, please
 create a Github issue.
 
@@ -59,129 +76,57 @@ Installation
  pip install prompt-toolkit
 
 
-The Python repl
+Getting started
 ---------------
 
-Run ``ptpython`` to get an interactive Python prompt with syntax highlighting,
-code completion, etc...
-
-.. image :: docs/images/ptpython-screenshot.png
-
-If you prefer to have Vi key bindings (which currently are more completely
-implemented than the Emacs bindings), run ``ptpython --vi``.
-
-If you want to embed the REPL inside your application at one point, do:
+The most simple example of the library would look like this:
 
 .. code:: python
 
- from prompt_toolkit.contrib.repl import embed
- embed(globals(), locals(), vi_mode=False, history_filename=None)
-
-Autocompletion
-**************
-
-``Tab`` and ``shift+tab`` complete the input. (Thanks to the `Jedi
-<http://jedi.jedidjah.ch/en/latest/>`_ autocompletion library.)
-In Vi-mode, you can also use ``Ctrl+N`` and ``Ctrl+P``.
-
-.. image :: docs/images/ptpython-complete-menu.png
-
-
-Multiline editing
-*****************
-
-Usually, multi-line editing mode will automatically turn on when you press enter
-after a colon, however you can always turn it on by pressing ``F7``.
-
-To execute the input in multi-line mode, you can either press ``Alt+Enter``, or
-``Esc`` followed by ``Enter``. (If you want the first to work in the OS X
-terminal, you have to check the "Use option as meta key" checkbox in your
-terminal settings. For iTerm2, you have to check "Left option acts as +Esc" in
-the options.)
+ from prompt_toolkit.contrib.shortcuts import get_input
 
-Other features
-***************
-
-Running system commands: Press ``Meta-!`` in Emacs mode or just ``!`` in Vi
-navigation mode to see the "Shell command" prompt. There you can enter system
-commands without leaving the REPL.
-
-Selecting text: Press ``Control+Space`` in Emacs mode on ``V`` (major V) in Vi
-navigation mode.
-
-You love IPython?
-*****************
-
-Run ``ptipython`` (prompt_toolkit - IPython), to get a nice interactive shell
-with all the power that IPython has to offer, like magic functions and shell
-integration. Make sure that IPython has been installed. (``pip install
-ipython``)
-
-.. image :: docs/images/ipython-integration.png
-
-You are using Django?
-*********************
-
-`django-extensions <https://github.com/django-extensions/django-extensions>`_
-has a ``shell_plus`` management command. When ``prompt_toolkit`` has been
-installed, it will by default use ``ptpython`` or ``ptipython``.
-
-
-Using as a library
-------------------
-
-This is a library which allows you to build highly customizable input prompts.
-Every step (key bindings, layout, etc..) can be customized.
-
-Note that this is work in progress. Many things work, but code is still
-refactored a lot and APIs can change (they will become even better), so be
-prepared to handle these changes.
-
-Certainly look in the ``examples`` directory to see what is possible.
-
-A very simple example:
-
-.. code:: python
-
- from prompt_toolkit import CommandLineInterface, AbortAction
- from prompt_toolkit import Exit
+ if __name__ == '__main__':
+ answer = get_input('Give me some input: ')
+ print('You said: %s' % answer)
 
- def main():
- cli = CommandLineInterface()
+For more complex examples, have a look in the examples directory. All examples
+are choosen to demonstrate only one thing. Also, don't be afraid to look at the
+source code. The implementation of the ``get_input`` function could be a good
+start.
 
- try:
- while True:
- code_obj = cli.read_input(on_exit=AbortAction.RAISE_EXCEPTION)
- print('You said: ' + code_obj.text)
 
- except Exit: # Quit on Ctrl-D keypress
- return
+Projects using prompt-toolkit
+------------------------------
 
- if __name__ == '__main__':
- main()
+- `ptpython <http://github.com/jonathanslenders/ptpython/>`_: Python REPL
+- `ptpdb <http://github.com/jonathanslenders/ptpdb/>`_: Python debugger (pdb replacement)
+- `pgcli <http://pgcli.com/>`_: Postgres Shell
 
+(Want you own project to be listed here? Please create a GitHub issue.)
 
-FAQ
----
 
-Q
- The ``Ctrl-S`` forward search doesn't work and freezes my terminal.
-A
- Try to run ``stty -ixon`` in your terminal to disable flow control.
+Philosophy
+---------
 
-Q
- The ``Meta``-key doesn't work.
-A
- For some terminals you have to enable the Alt-key to act as meta key, but you
- can also type ``Escape`` before any key instead.
+The source code of ``prompt_toolkit`` should be readable, concise and
+efficient. We prefer short functions focussing each on one task and for which
+the input and output types are clearly specified. We mostly prefer composition
+over inheritance, because inheritance can result in too much functionality in
+the same object. We prefer immutable objects where possible (objects don't
+change after initialisation). Reusability is important. We absolutely refrain
+from having a changing global state, it should be possible to have multiple
+independent instances of the same code in the same process. The architecture
+should be layered: the lower levels operate on primitive operations and data
+structures giving -- when correctly combined -- all the possible flexibility;
+while at the higher level, there should be a simpler API, ready-to-use and
+sufficient for most use cases. Thinking about algorithms and efficiency is
+important, but avoid premature optimization.
 
 
 Special thanks to
 -----------------
 
 - `Pygments <http://pygments.org/>`_: Syntax highlighter.
-- `Jedi <http://jedi.jedidjah.ch/en/latest/>`_: Autocompletion library.
-- `Docopt <http://docopt.org/>`_: Command-line interface description language.
 - `wcwidth <https://github.com/jquast/wcwidth>`_: Determine columns needed for a wide characters.
 
 .. |Build Status| image:: https://api.travis-ci.org/jonathanslenders/python-prompt-toolkit.svg?branch=master