summaryrefslogtreecommitdiffstats
path: root/README.rst
diff options
context:
space:
mode:
Diffstat (limited to 'README.rst')
-rw-r--r--README.rst157
1 files changed, 157 insertions, 0 deletions
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..d3b77b6
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,157 @@
+Python Prompt Toolkit
+=====================
+
+|Build Status| |AppVeyor| |PyPI| |RTD| |License| |Codecov|
+
+.. image :: https://github.com/prompt-toolkit/python-prompt-toolkit/raw/master/docs/images/logo_400px.png
+
+``prompt_toolkit`` *is a library for building powerful interactive command line applications in Python.*
+
+Read the `documentation on readthedocs
+<http://python-prompt-toolkit.readthedocs.io/en/stable/>`_.
+
+NOTICE: prompt_toolkit 3.0
+**************************
+
+Please notice that this branch is the ``prompt_toolkit`` **3.0** branch. For most
+users, it should be compatible with ``prompt_toolkit`` **2.0**, but it requires at
+least **Python 3.6**. On the plus side, ``prompt_toolkit`` **3.0** is completely type
+annotated and uses asyncio natively.
+
+
+Gallery
+*******
+
+`ptpython <http://github.com/prompt-toolkit/ptpython/>`_ is an interactive
+Python Shell, build on top of ``prompt_toolkit``.
+
+.. image :: https://github.com/prompt-toolkit/python-prompt-toolkit/raw/master/docs/images/ptpython.png
+
+`More examples <https://python-prompt-toolkit.readthedocs.io/en/stable/pages/gallery.html>`_
+
+
+prompt_toolkit features
+***********************
+
+``prompt_toolkit`` could be a replacement for `GNU readline
+<https://tiswww.case.edu/php/chet/readline/rltop.html>`_, but it can be much
+more than that.
+
+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.)
+- Even some advanced Vi functionality, like named registers and digraphs.
+- Reverse and forward incremental search.
+- Works well with Unicode double width characters. (Chinese input.)
+- Selecting text for copy/paste. (Both Emacs and Vi style.)
+- Support for `bracketed paste <https://cirw.in/blog/bracketed-paste>`_.
+- Mouse support for cursor positioning and scrolling.
+- Auto suggestions. (Like `fish shell <http://fishshell.com/>`_.)
+- Multiple input buffers.
+- No global state.
+- Lightweight, the only dependencies are Pygments and wcwidth.
+- Runs on Linux, OS X, FreeBSD, OpenBSD and Windows systems.
+- And much more...
+
+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.
+
+
+Installation
+************
+
+::
+
+ pip install prompt_toolkit
+
+For Conda, do:
+
+::
+
+ conda install -c https://conda.anaconda.org/conda-forge prompt_toolkit
+
+
+About Windows support
+*********************
+
+``prompt_toolkit`` is cross platform, and everything that you build on top
+should run fine on both Unix and Windows systems. Windows support is best on
+recent Windows 10 builds, for which the command line window supports vt100
+escape sequences. (If not supported, we fall back to using Win32 APIs for color
+and cursor movements).
+
+It's worth noting that the implementation is a "best effort of what is
+possible". Both Unix and Windows terminals have their limitations. But in
+general, the Unix experience will still be a little better.
+
+For Windows, it's recommended to use either `cmder
+<http://cmder.net/>`_ or `conemu <https://conemu.github.io/>`_.
+
+Getting started
+***************
+
+The most simple example of the library would look like this:
+
+.. code:: python
+
+ from prompt_toolkit import prompt
+
+ if __name__ == '__main__':
+ answer = prompt('Give me some input: ')
+ print('You said: %s' % answer)
+
+For more complex examples, have a look in the ``examples`` directory. All
+examples are chosen to demonstrate only one thing. Also, don't be afraid to
+look at the source code. The implementation of the ``prompt`` function could be
+a good start.
+
+Philosophy
+**********
+
+The source code of ``prompt_toolkit`` should be **readable**, **concise** and
+**efficient**. We prefer short functions focusing 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 initialization). 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.
+
+
+`Projects using prompt_toolkit <PROJECTS.rst>`_
+***********************************************
+
+Special thanks to
+*****************
+
+- `Pygments <http://pygments.org/>`_: Syntax highlighter.
+- `wcwidth <https://github.com/jquast/wcwidth>`_: Determine columns needed for a wide characters.
+
+.. |Build Status| image:: https://api.travis-ci.org/prompt-toolkit/python-prompt-toolkit.svg?branch=master
+ :target: https://travis-ci.org/prompt-toolkit/python-prompt-toolkit#
+
+.. |PyPI| image:: https://img.shields.io/pypi/v/prompt_toolkit.svg
+ :target: https://pypi.python.org/pypi/prompt-toolkit/
+ :alt: Latest Version
+
+.. |AppVeyor| image:: https://ci.appveyor.com/api/projects/status/32r7s2skrgm9ubva?svg=true
+ :target: https://ci.appveyor.com/project/prompt-toolkit/python-prompt-toolkit/
+
+.. |RTD| image:: https://readthedocs.org/projects/python-prompt-toolkit/badge/
+ :target: https://python-prompt-toolkit.readthedocs.io/en/master/
+
+.. |License| image:: https://img.shields.io/github/license/prompt-toolkit/python-prompt-toolkit.svg
+ :target: https://github.com/prompt-toolkit/python-prompt-toolkit/blob/master/LICENSE
+
+.. |Codecov| image:: https://codecov.io/gh/prompt-toolkit/python-prompt-toolkit/branch/master/graphs/badge.svg?style=flat
+ :target: https://codecov.io/gh/prompt-toolkit/python-prompt-toolkit/
+