More documentation.

Author: jonathanslenders

CHANGELOG

@@ -134,6 +134,8 @@ Changes:
  passed to the `Window` class and applied to the content as well.
  * Alignment of the content is now done in the `Window` class, not in the
  user control.
+ * The continuation function of `PromptMargin` now takes `line_number` and
+ * `is_soft_wrap` as input.
 
 - Changes to `BufferControl`:
 
@@ -178,6 +180,11 @@ Changes:
  wait for all the completions to be generated, before displaying the first
  one. The completion menus are updated as soon as new completions arrive.
 
+- Changes regarding the `History` classes:
+
+ * The `History` base class has a different interface. This was needed for
+ asynchronous loading of the history. `ThreadedHistory` was added for this.
+
 - Changes related to `shortcuts.prompt`:
 
  * There is now a class `Prompt` which also has a method `prompt`. Both the

docs/pages/advanced_topics/filters.rst

@@ -166,3 +166,4 @@ instance, and always returns a :class:`~prompt_toolkit.filters.Filter`.
  f = to_filter(True)
  f = to_filter(False)
  f = to_filter(Condition(lambda: True))
+ f = to_filter(has_search | has_selection)

docs/pages/asking_for_input.rst

@@ -457,14 +457,15 @@ Auto suggestion is a way to propose some input completions to the user like the
 
 Usually, the input is compared to the history and when there is another entry
 starting with the given text, the completion will be shown as gray text behind
-the current input. Pressing the right arrow :kbd:`→` will insert this suggestion.
+the current input. Pressing the right arrow :kbd:`→` or :kbd:`c-e` will insert
+this suggestion, :kbd:`alt-f` will insert the first word of the suggestion.
 
 .. note::
 
  When suggestions are based on the history, don't forget to share one
  :class:`~prompt_toolkit.history.History` object between consecutive
  :func:`~prompt_toolkit.shortcuts.prompt` calls. Using a
- :class:`~prompt_toolkit.prompt.PromptSession` does this for you.
+ :class:`~prompt_toolkit.shortcuts.PromptSession` does this for you.
 
 Example:
 
@@ -489,12 +490,15 @@ passed as an argument.
 Adding a bottom toolbar
 -----------------------
 
-Adding a bottom toolbar is as easy as passing a ``bottom_toolbar`` function to
-:func:`~prompt_toolkit.shortcuts.prompt`. The function is called every time the
-prompt is rendered (at least on every key stroke), so the bottom toolbar can be
-used to display dynamic information. It should return formatted text or a list
-of ``(style, text)`` tuples. The toolbar is always erased when the prompt
-returns.
+Adding a bottom toolbar is as easy as passing a ``bottom_toolbar`` argument to
+:func:`~prompt_toolkit.shortcuts.prompt`. This argument be either plain text,
+:ref:`formatted text <formatted_text>` or a callable that returns plain or
+formatted text.
+
+When a function is given, it will be called every time the prompt is rendered,
+so the bottom toolbar can be used to display dynamic information.
+
+The toolbar is always erased when the prompt returns.
 
 .. code:: python
 
@@ -516,14 +520,17 @@ the background of the toolbar.
 
 .. image:: ../images/bottom-toolbar.png
 
+
 Adding a right prompt
 ---------------------
 
 The :func:`~prompt_toolkit.shortcuts.prompt` function has out of the box
 support for right prompts as well. People familiar to ZSH could recognise this
 as the `RPROMPT` option.
 
-So, similar to adding a bottom toolbar, we can pass a ``get_rprompt`` callable.
+So, similar to adding a bottom toolbar, we can pass an ``rprompt`` argument.
+This can be either plain text, :ref:`formatted text <formatted_text>` or a
+callable which returns either.
 
 .. code:: python
 
@@ -585,17 +592,25 @@ An example of a prompt that prints ``'hello world'`` when :kbd:`Control-T` is pr
 
  @bindings.add('c-t')
  def _(event):
+ " Say 'hello' when `c-t` is pressed. "
  def print_hello():
  print('hello world')
  run_in_terminal(print_hello)
 
+ @bindings.add('c-x')
+ def _(event):
+ " Exit when `c-x` is pressed. "
+ event.app.exit()
+
  text = prompt('> ', key_bindings=bindings)
  print('You said: %s' % text)
 
 
 Note that we use
-:meth:`~prompt_toolkit.application.run_in_terminal`. This
-ensures that the output of the print-statement and the prompt don't mix up.
+:meth:`~prompt_toolkit.application.run_in_terminal` for the first key binding.
+This ensures that the output of the print-statement and the prompt don't mix
+up. If the key bindings doesn't print anything, then it can be handled directly
+without nesting functions.
 
 
 Enable key bindings according to a condition

docs/pages/example.rst

@@ -67,17 +67,17 @@ I/O objects
 Every :class:`~prompt_toolkit.application.Application` instance requires an I/O
 objects for input and output:
 
- - An :class:`~prompt_toolkit.input.base.Input` instance, which is an
- abstraction of the input stream (stdin).
- - An :class:`~prompt_toolkit.output.base.Output` instance, which is an
+ - An :class:`~prompt_toolkit.input.Input` instance, which is an abstraction
+ of the input stream (stdin).
+ - An :class:`~prompt_toolkit.output.Output` instance, which is an
  abstraction of the output stream, and is called by the renderer.
 
 Both are optional and normally not needed to pass explicitly. Usually, the
 default works fine.
 
 There is a third I/O object which is also required by the application, but not
 passed inside. This is the event loop, an
-:class:`~prompt_toolkit.eventloop.base.EventLoop` instance. This is basically a
+:class:`~prompt_toolkit.eventloop.EventLoop` instance. This is basically a
 while-true loop that waits for user input, and when it receives something (like
 a key press), it will send that to the the appropriate handler, like for
 instance, a key binding.
@@ -343,9 +343,9 @@ As said earlier, a :class:`~prompt_toolkit.layout.Window` is a
  Basically, windows are the leafs in the tree structure that represent the UI.
 
 A :class:`~prompt_toolkit.layout.Window` provides a "view" on the
-:class:`~prompt_toolkit.layout.controls.UIControl`, which provides lines of
-content. The window is in the first place responsible for the line wrapping and
-scrolling of the content, but there are much more options.
+:class:`~prompt_toolkit.layout.UIControl`, which provides lines of content. The
+window is in the first place responsible for the line wrapping and scrolling of
+the content, but there are much more options.
 
 - Adding left or right margins. These are used for displaying scroll bars or
  line numbers.

docs/pages/full_screen_apps.rst

@@ -59,7 +59,7 @@ You can replace the built in ``print`` function as follows, if you want to.
 Formatted text
 --------------
 
-There are several ways to print colors:
+There are several ways to display colors:
 
 - By creating an :class:`~prompt_toolkit.formatted_text.HTML` object.
 - By creating an :class:`~prompt_toolkit.formatted_text.ANSI` object that

docs/pages/printing_text.rst

@@ -152,21 +152,6 @@ Controls
  FormattedTextControl, UIControl, UIContent
 
 
-Widgets
-^^^^^^^
-
-.. automodule:: prompt_toolkit.widgets
- :members: TextArea, Label, Button, Frame, Shadow, Box, VerticalLine,
- HorizontalLine, RadioList, Checkbox, ProgressBar
-
-.. automodule:: prompt_toolkit.widgets
- :members: ArgToolbar, CompletionsToolbar, FormattedTextToolbar,
- SearchToolbar, SystemToolbar, ValidationToolbar
-
-.. automodule:: prompt_toolkit.widgets
- :members: Dialog, MenuContainer, MenuItem
-
-
 Other
 ^^^^^
 
@@ -185,6 +170,16 @@ Other
  :members:
 
 
+Widgets
+-------
+
+.. automodule:: prompt_toolkit.widgets
+ :members: TextArea, Label, Button, Frame, Shadow, Box, VerticalLine,
+ HorizontalLine, RadioList, Checkbox, ProgressBar, CompletionsToolbar,
+ FormattedTextToolbar, SearchToolbar, SystemToolbar, ValidationToolbar,
+ MenuContainer, MenuItem
+
+
 Filters
 -------
 
@@ -221,8 +216,12 @@ Key binding
 Eventloop
 ---------
 
-.. automodule:: prompt_toolkit.eventloop.base
- :members:
+.. automodule:: prompt_toolkit.eventloop
+ :members: EventLoop, get_traceback_from_context, From, Return,
+ ensure_future, create_event_loop, create_asyncio_event_loop,
+ use_asyncio_event_loop, get_event_loop, set_event_loop,
+ run_in_executor, call_from_executor, run_until_complete, Future,
+ InvalidStateError
 
 .. automodule:: prompt_toolkit.eventloop.posix
  :members:
@@ -236,21 +235,12 @@ Eventloop
 .. automodule:: prompt_toolkit.eventloop.asyncio_posix
  :members:
 
-.. automodule:: prompt_toolkit.eventloop.coroutine
- :members:
-
-.. automodule:: prompt_toolkit.eventloop.future
- :members:
-
 
 Input
 -----
 
 .. automodule:: prompt_toolkit.input
- :members:
-
-.. automodule:: prompt_toolkit.input.defaults
- :members:
+ :members: Input, DummyInput, create_input, get_default_input, set_default_input
 
 .. automodule:: prompt_toolkit.input.vt100
  :members:
@@ -262,10 +252,8 @@ Output
 ------
 
 .. automodule:: prompt_toolkit.output
- :members:
-
-.. automodule:: prompt_toolkit.output.defaults
- :members:
+ :members: Output, DummyOutput, ColorDepth, create_output,
+ get_default_output, set_default_output
 
 .. automodule:: prompt_toolkit.output.vt100
  :members:

docs/pages/reference.rst

@@ -202,6 +202,8 @@ class PromptSession(object):
  :param history: :class:`~prompt_toolkit.history.History` instance.
  :param clipboard: :class:`~prompt_toolkit.clipboard.Clipboard` instance.
  (e.g. :class:`~prompt_toolkit.clipboard.InMemoryClipboard`)
+ :param rprompt: Text or formatted text to be displayed on the right side.
+ This can also be a callable that returns (formatted) text.
  :param bottom_toolbar: Formatted text or callable which is supposed to
  return formatted text.
  :param prompt_continuation: Text that needs to be displayed for a multiline