diff --git a/docs/index.rst b/docs/index.rst index 1fadaf9af..9b5b6e4b3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,13 +1,15 @@ Python Prompt Toolkit ===================== -`prompt_toolkit` is a library for building powerful interactive command lines +`prompt_toolkit` is a library for building powerful interactive command line and terminal applications in Python. -It can be a pure Python replacement for `GNU readline -`_, but it can be much -more than that. +It can be a very advanced pure Python replacement for `GNU readline +`_, but it can also be +used for building full screen applications. + +.. image:: images/ptpython.png Some features: @@ -34,73 +36,18 @@ Works everywhere: also run in a telnet/ssh server or an `asyncio `_ process. - -Two use cases: prompts versus full screen terminal applications ---------------------------------------------------------------- - -``prompt_toolkit`` was in the first place meant to be a replacement for -readline. However, when it became more mature, we realised that all the -components for full screen applications are there and ``prompt_toolkit`` is -very capable of handling many use cases. `Pyvim -`_ and `pymux -`_ are examples of full screen -applications. - -.. image:: images/pyvim.png - -Basically, at the core, ``prompt_toolkit`` has a layout engine, that supports -horizontal and vertical splits as well as floats, where each "window" can -display a user control. The API for user controls is simple yet powerful. - -When ``prompt_toolkit`` is used to simply read some input from the user, it -uses a rather simple built-in layout. One that displays the default input -buffer and the prompt, a float for the autocompletions and a toolbar for input -validation which is hidden by default. - -For full screen applications, usually we build the layout ourself, because it's -very custom. - -Further, there is a very flexible key binding system that can be programmed for -all the needs of full screen applications. - - -Installation ------------- - -:: - - pip install prompt_toolkit - -For Conda, do: - -:: - - conda install -c https://conda.anaconda.org/conda-forge prompt_toolkit - +Have a look at :ref:`the gallery ` to get an idea of what is possible. Getting started --------------- -The following snippet is the most simple example, it uses the -:func:`~prompt_toolkit.prompt` function to asks the user for input -and returns the text. Just like ``(raw_)input``. - -.. code:: python - - from __future__ import unicode_literals - from prompt_toolkit import prompt - - text = prompt('Give me some input: ') - print('You said: %s' % text) - -For more information, start reading the :ref:`building prompts -` section. +Go to :ref:`getting started ` and build your first prompt. Thanks to: ---------- -Thanks to `all the contributors +A special thanks to `all the contributors `_ for making prompt_toolkit possible. @@ -115,8 +62,9 @@ Table of contents :maxdepth: 3 pages/gallery + pages/getting_started pages/printing_text - pages/building_prompts + pages/asking_for_input pages/dialogs pages/full_screen_apps pages/architecture diff --git a/docs/pages/building_prompts.rst b/docs/pages/asking_for_input.rst similarity index 96% rename from docs/pages/building_prompts.rst rename to docs/pages/asking_for_input.rst index a905e63e1..c04a6f69f 100644 --- a/docs/pages/building_prompts.rst +++ b/docs/pages/asking_for_input.rst @@ -1,4 +1,4 @@ -.. _building_prompts: +.. _asking_for_input: Asking for input (prompts) ========================== @@ -32,8 +32,8 @@ In the following sections, we will discover all these parameters. .. note:: - ``prompt_toolkit`` expects unicode strings everywhere. If you are using - Python 2, make sure that all strings which are passed to ``prompt_toolkit`` + `prompt_toolkit` expects unicode strings everywhere. If you are using + Python 2, make sure that all strings which are passed to `prompt_toolkit` are unicode strings (and not bytes). Either use ``from __future__ import unicode_literals`` or explicitely put a small ``'u'`` in front of every string. @@ -65,8 +65,8 @@ Colors ------ The colors for syntax highlighting are defined by a -:class:`~prompt_toolkit.styles.Style` instance. By default, a neutral built-in -style is used, but any style instance can be passed to the +:class:`~prompt_toolkit.styles.Style` instance. By default, a neutral +built-in style is used, but any style instance can be passed to the :func:`~prompt_toolkit.shortcuts.prompt` function. A simple way to create a style, is by using the :meth:`~prompt_toolkit.styles.Style.from_dict` function: @@ -90,9 +90,9 @@ function: The style dictionary is very similar to the Pygments ``styles`` dictionary, with a few differences: -- The `roman`, `sans`, `mono` and `border` options are not ignored. -- The style has a few additions: `blink`, `noblink`, `reverse` and `noreverse`. -- Colors can be in the `#ff0000` format, but they can be one of the built-in +- The `roman`, `sans`, `mono` and `border` options are ignored. +- The style has a few additions: ``blink``, ``noblink``, ``reverse`` and ``noreverse``. +- Colors can be in the ``#ff0000`` format, but they can be one of the built-in ANSI color names as well. In that case, they map directly to the 16 color palette of the terminal. @@ -167,7 +167,7 @@ a list of ``(style, text)`` tuples. By default, colors are taking from the 256 color palette. If you want to have 24bit true color, this is possible by adding the ``true_color=True`` option to -the ``prompt`` function. +the :func:`~prompt_toolkit.shortcuts.prompt.prompt`` function. .. code:: python diff --git a/docs/pages/dialogs.rst b/docs/pages/dialogs.rst index 1c08c9e87..892103112 100644 --- a/docs/pages/dialogs.rst +++ b/docs/pages/dialogs.rst @@ -1,4 +1,4 @@ -.. _building_prompts: +.. _dialogs: Dialogs ======= diff --git a/docs/pages/getting_started.rst b/docs/pages/getting_started.rst new file mode 100644 index 000000000..c29421a9c --- /dev/null +++ b/docs/pages/getting_started.rst @@ -0,0 +1,82 @@ +.. _getting_started: + +Getting started +=============== + +Installation +------------ + +:: + + pip install prompt_toolkit + +For Conda, do: + +:: + + conda install -c https://conda.anaconda.org/conda-forge prompt_toolkit + + +Several use cases: prompts versus full screen terminal applications +-------------------------------------------------------------------- + +`prompt_toolkit` was in the first place meant to be a replacement for readline. +However, when it became more mature, we realised that all the components for +full screen applications are there and `prompt_toolkit` is very capable of +handling many use situations. `Pyvim +`_ and `pymux +`_ are examples of full screen +applications. + +.. image:: ../images/pyvim.png + +Basically, at the core, `prompt_toolkit` has a layout engine, that supports +horizontal and vertical splits as well as floats, where each "window" can +display a user control. The API for user controls is simple yet powerful. + +When `prompt_toolkit` is used to simply read some input from the user, it uses +a rather simple built-in layout. One that displays the default input buffer and +the prompt, a float for the autocompletions and a toolbar for input validation +which is hidden by default. + +For full screen applications, usually we build the layout ourself, because +that's very custom. + +Further, there is a very flexible key binding system that can be programmed for +all the needs of full screen applications. + +A simple prompt +--------------- + +The following snippet is the most simple example, it uses the +:func:`~prompt_toolkit.shortcuts.prompt` function to asks the user for input +and returns the text. Just like ``(raw_)input``. + +.. code:: python + + from __future__ import unicode_literals + from prompt_toolkit import prompt + + text = prompt('Give me some input: ') + print('You said: %s' % text) + + +Learning `prompt_toolkit` +------------------------- + +In order to learn and understand `prompt_toolkit`, it is best to go through the +all sections in the order below. Also don't forget to have a look at all the +examples `examples +`_ +in the repository. + +- First, :ref:`learn how to print text `. This is important, + because it covers how to use "formatted text", which is something you'll use + whenever you want to use colors anywhere. + +- Secondly, go through the :ref:`asking for input ` section. + This is useful for almost any use case, even for full screen applications. + +- Then, learn about :ref:`dialogs`, which is easy and fun. + +- Finally, learn about :ref:`full_screen_applications`. diff --git a/docs/pages/printing_text.rst b/docs/pages/printing_text.rst index beb5f3a34..b4b77e93d 100644 --- a/docs/pages/printing_text.rst +++ b/docs/pages/printing_text.rst @@ -35,8 +35,9 @@ Formatted text There are three ways to print colors: -- By creating an HTML object. -- By creating an ANSI object that contains ANSI escape sequences. +- By creating an :class:`~prompt_toolkit.formatted_text.HTML` object. +- By creating an :class:`~prompt_toolkit.formatted_text.ANSI` object that + contains ANSI escape sequences. - By creating a list of ``(style, text)`` tuples. An instance of any of these three kinds of objects is called "formatted text". @@ -46,9 +47,9 @@ There are various places in prompt toolkit, where we accept not just plain text HTML ^^^^ -``prompt_toolkit.HTML`` can be used to indicate that a string contains -HTML-like formatting. It supports the basic tags for bold, italic and -underline: ````, ```` and ````. +:class:`~prompt_toolkit.formatted_text.HTML` can be used to indicate that a +string contains HTML-like formatting. It supports the basic tags for bold, +italic and underline: ````, ```` and ````. .. code:: python @@ -104,7 +105,8 @@ ANSI Some people like to use the VT100 ANSI escape squences to generate output. Natively, this is however only supported on VT100 terminals, but prompt_toolkit can parse these, and map them to a formatted text instances. This means that they -will work on Windows as well. +will work on Windows as well. The :class:`~prompt_toolkit.formatted.ANSI` class +takes care of that. .. code:: python @@ -117,10 +119,11 @@ will work on Windows as well. Style/text tuples ^^^^^^^^^^^^^^^^^ -Internally, both `HTML` and `ANSI` objects are mapped to a list of ``(style, -text)`` tuples. It is however also possible to create such a list manually. -This is a little more verbose, but it's probably the most powerful way of -expressing formatted text. +Internally, both :class:`~prompt_toolkit.formatted_text.HTML` and +:class:`~prompt_toolkit.formatted_text.ANSI` objects are mapped to a list of +``(style, text)`` tuples. It is however also possible to create such a list +manually. This is a little more verbose, but it's probably the most powerful +way of expressing formatted text. .. code:: python @@ -136,8 +139,8 @@ expressing formatted text. print(text, style=style) -Similar to the `HTML` example, it's also possible to use class names, and -separate the styling in a style sheet. +Similar to the :class:`~prompt_toolkit.formatted_text.HTML` example, it is also +possible to use class names, and separate the styling in a style sheet. .. code:: python @@ -145,12 +148,14 @@ separate the styling in a style sheet. from prompt_toolkit import print from prompt_toolkit.styles import Style + # The text. text = [ ('class:aaa', 'Hello'), ('', ' '), ('class:bbb', 'World'), ] + # The style sheet. style = Style.from_dict({ 'aaa': '#ff0066', 'bbb': '#44ff00 italic', diff --git a/docs/pages/reference.rst b/docs/pages/reference.rst index 4f56024d1..a140d3547 100644 --- a/docs/pages/reference.rst +++ b/docs/pages/reference.rst @@ -7,6 +7,12 @@ Application .. automodule:: prompt_toolkit.application :members: +Formatted text +-------------- + +.. automodule:: prompt_toolkit.formatted_text + :members: + Buffer ------ @@ -70,7 +76,25 @@ Keys Style ----- -.. automodule:: prompt_toolkit.styles +.. automodule:: prompt_toolkit.styles.base + :members: + +.. automodule:: prompt_toolkit.styles.style + :members: + +.. automodule:: prompt_toolkit.styles.defaults + :members: + +.. automodule:: prompt_toolkit.styles.from_dict + :members: + +.. automodule:: prompt_toolkit.styles.from_pygments + :members: + +.. automodule:: prompt_toolkit.styles.named_colors + :members: + +.. automodule:: prompt_toolkit.styles.utils :members: Reactive @@ -82,7 +106,10 @@ Reactive Shortcuts --------- -.. automodule:: prompt_toolkit.shortcuts +.. automodule:: prompt_toolkit.shortcuts.prompt + :members: + +.. automodule:: prompt_toolkit.shortcuts.dialogs :members: Validation diff --git a/prompt_toolkit/formatted_text.py b/prompt_toolkit/formatted_text.py index 1cf4d8f89..577387d6c 100644 --- a/prompt_toolkit/formatted_text.py +++ b/prompt_toolkit/formatted_text.py @@ -93,7 +93,7 @@ def is_formatted_text(value): class FormattedText(object): """ - A list of (style, text) tuples. + A list of ``(style, text)`` tuples. """ def __init__(self, data): self.data = data @@ -163,16 +163,16 @@ class HTML(object): :: - - + # Turn something into red. + HTML('') - - ... - ... - ... + # Italic, bold and underline. + HTML('...') + HTML('...') + HTML('...') All HTML elements become available as a "class" in the style sheet. - E.g. ``...`` can be styles, by setting a style for + E.g. ``...`` can be styled, by setting a style for ``username``. """ def __init__(self, value): @@ -270,7 +270,11 @@ def html_escape(text): class ANSI(object): """ ANSI formatted text. - Take something ANSI escaped text, for use as a formatted string. + Take something ANSI escaped text, for use as a formatted string. E.g. + + :: + + ANSI('\x1b[31mhello \x1b[32mworld') Characters between \001 and \002 are supposed to have a zero width when printed, but these are literally sent to the terminal output. This can be