path: root/docs/pages/asking_for_input.rst

.. _asking_for_input:

Asking for input (prompts)
==========================

This page is about building prompts. Pieces of code that we can embed in a
program for asking the user for input. Even if you want to use `prompt_toolkit`
for building full screen terminal applications, it is probably still a good
idea to read this first, before heading to the :ref:`building full screen
applications <full_screen_applications>` page.

In this page, we will cover autocompletion, syntax highlighting, key bindings,
and so on.


Hello world
-----------

The following snippet is the most simple example, it uses the
:func:`~prompt_toolkit.shortcuts.prompt` function to ask the user for input
and returns the text. Just like ``(raw_)input``.

.. code:: python

    from prompt_toolkit import prompt

    text = prompt('Give me some input: ')
    print('You said: %s' % text)

.. image:: ../images/hello-world-prompt.png

What we get here is a simple prompt that supports the Emacs key bindings like
readline, but further nothing special. However,
:func:`~prompt_toolkit.shortcuts.prompt` has a lot of configuration options.
In the following sections, we will discover all these parameters.


The `PromptSession` object
--------------------------

Instead of calling the :func:`~prompt_toolkit.shortcuts.prompt` function, it's
also possible to create a :class:`~prompt_toolkit.shortcuts.PromptSession`
instance followed by calling its
:meth:`~prompt_toolkit.shortcuts.PromptSession.prompt` method for every input
call. This creates a kind of an input session.

.. code:: python

    from prompt_toolkit import PromptSession

    # Create prompt object.
    session = PromptSession()

    # Do multiple input calls.
    text1 = session.prompt()
    text2 = session.prompt()

This has mainly two advantages:

- The input history will be kept between consecutive
  :meth:`~prompt_toolkit.shortcuts.PromptSession.prompt` calls.

- The :func:`~prompt_toolkit.shortcuts.PromptSession` instance and its
  :meth:`~prompt_toolkit.shortcuts.PromptSession.prompt` method take about the
  same arguments, like all the options described below (highlighting,
  completion, etc...). So if you want to ask for multiple inputs, but each
  input call needs about the same arguments, they can be passed to the
  :func:`~prompt_toolkit.shortcuts.PromptSession` instance as well, and they
  can be overridden by passing values to the
  :meth:`~prompt_toolkit.shortcuts.PromptSession.prompt` method.


Syntax highlighting
-------------------

Adding syntax highlighting is as simple as adding a lexer. All of the `Pygments
<http://pygments.org/>`_ lexers can be used after wrapping them in a
:class:`~prompt_toolkit.lexers.PygmentsLexer`. It is also possible to create a
custom lexer by implementing the :class:`~prompt_toolkit.lexers.Lexer` abstract
base class.

.. code:: python

    from pygments.lexers.html import HtmlLexer
    from prompt_toolkit.shortcuts import prompt
    from prompt_toolkit.lexers import PygmentsLexer

    text = prompt('Enter HTML: ', lexer=PygmentsLexer(HtmlLexer))
    print('You said: %s' % text)

.. image:: ../images/html-input.png

The default Pygments colorscheme is included as part of the default style in
prompt_toolkit. If you want to use another Pygments style along with the lexer,
you can do the following:

.. code:: python

    from pygments.lexers.html import HtmlLexer
    from pygments.styles import get_style_by_name
    from prompt_toolkit.shortcuts import prompt
    from prompt_toolkit.lexers import PygmentsLexer
    from prompt_toolkit.styles.pygments import style_from_pygments_cls

    style = style_from_pygments_cls(get_style_by_name('monokai'))
    text = prompt('Enter HTML: ', lexer=PygmentsLexer(HtmlLexer), style=style,
                  include_default_pygments_style=False)
    print('You said: %s' % text)

We pass ``include_default_pygments_style=False``, because otherwise, both
styles will be merged, possibly giving slightly different colors in the outcome
for cases where where our custom Pygments style doesn't specify a color.

.. _colors:

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
: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:

.. code:: python

    from pygments.lexers.html import HtmlLexer
    from prompt_toolkit.shortcuts import prompt
    from prompt_toolkit.styles import Style
    from prompt_toolkit.lexers import PygmentsLexer

    our_style = Style.from_dict({
        'pygments.comment':   '#888888 bold',
        'pygments.keyword':   '#ff88ff bold',
    })

    text = prompt('Enter HTML: ', lexer=PygmentsLexer(HtmlLexer),
                  style=our_style)


The style dictionary is very similar to the Pygments ``styles`` dictionary,
with a few differences:

- 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.

:ref:`Read more about styling <styling>`.


Using a Pygments style
^^^^^^^^^^^^^^^^^^^^^^

All Pygments style classes can be used as well, when they are wrapped through
:func:`~prompt_toolkit.styles.style_from_pygments_cls`.

Suppose we'd like to use a Pygments style, for instance
``pygments.styles.tango.TangoStyle``, that is possible like this:

.. code:: python

    from prompt_toolkit.shortcuts import prompt
    from prompt_toolkit.styles import style_from_pygments_cls
    from prompt_toolkit.lexers import PygmentsLexer
    from pygments.styles.tango import TangoStyle
    from pygments.lexers.html import HtmlLexer
    
    tango_style = style_from_pygments_cls (TangoStyle)
    
    text = prompt ('Enter HTML: ', 
      lexer=PygmentsLexer(HtmlLexer),
      style=tango_style)

Creating a custom style could be done like this:

.. code:: python

    from prompt_toolkit.shortcuts import prompt
    from prompt_toolkit.styles import Style, style_from_pygments_cls, merge_styles
    from prompt_toolkit.lexers import PygmentsLexer

    from pygments.styles.tango import TangoStyle
    from pygments.lexers.html import HtmlLexer

    our_style = merge_styles([
        style_from_pygments_cls(TangoStyle),
        Style.from_dict({
            'pygments.comment': '#888888 bold',
            'pygments.keyword': '#ff88ff bold',
        })
    ])

    text = prompt('Enter HTML: ', lexer=PygmentsLexer(HtmlLexer),
                  style=our_style)


Coloring the prompt itself
^^^^^^^^^^^^^^^^^^^^^^^^^^

It is possible to add some colors to the prompt itself. For this, we need to
build some :ref:`formatted text <formatted_text>`. One way of doing this is by
creating a list of style/text tuples. In the following example, we use class
names to refer to the style.

.. code:: python

    from prompt_toolkit.shortcuts import prompt
    from prompt_toolkit.styles import Style

    style = Style.from_dict({
        # User input (default text).
        '':          '#ff0066',

        # Prompt.
        'username': '#884444',
        'at':       '#00aa00',
        'colon':    '#0000aa',
        'pound':    '#00aa00',
        'host':     '#00ffff bg:#444400',
        'path':     'ansicyan underline',
    })

    message = [
        ('class:username', 'john'),
        ('class:at',       '@'),
        ('class:host',     'localhost'),
        ('class:colon',    ':'),
        ('class:path',     '/user/john'),
        ('class:pound',    '# '),
    ]

    text = prompt(message, style=style)

.. image:: ../images/colored-prompt.png

The `message` can be any kind of formatted text, as discussed :ref:`here
<formatted_text>`. It can also be a callable that returns some formatted text.

By default, colors are taken from the 256 color palette. If you want to have
24bit true color, this is possible by adding the
``color_depth=ColorDepth.TRUE_COLOR`` option to the
:func:`~prompt_toolkit.shortcuts.prompt.prompt` function.

.. code:: python

    from prompt_toolkit.output import ColorDepth

    text = prompt(message, style=style, color_depth=ColorDepth.TRUE_COLOR)


Autocompletion
--------------

Autocompletion can be added by passing a ``completer`` parameter. This should
be an instance of the :class:`~prompt_toolkit.completion.Completer` abstract
base class. :class:`~prompt_toolkit.completion.WordCompleter` is an example of
a completer that implements that interface.

.. code:: python

    from prompt_toolkit import prompt
    from prompt_toolkit.completion import WordCompleter

    html_completer = WordCompleter(['<html>', '<body>', '<head>', '<title>'])
    text = prompt('Enter HTML: ', completer=html_completer)
    print('You said: %s' % text)

:class:`~prompt_toolkit.completion.WordCompleter` is a simple completer that
completes the last word before the cursor with any of the given words.

.. image:: ../images/html-completion.png

.. note::

    Note that in prompt_toolkit 2.0, the auto completion became synchronous. This
    means that if it takes a long time to compute the completions, that this
    will block the event loop and the input processing.

    For heavy completion algorithms, it is recommended to wrap the completer in
    a :class:`~prompt_toolkit.completion.ThreadedCompleter` in order to run it
    in a background thread.


Nested completion
^^^^^^^^^^^^^^^^^

Sometimes you have a command line interface where the completion depends on the
previous words from the input. Examples are the CLIs from routers and switches.
A simple :class:`~prompt_toolkit.completion.WordCompleter` is not enough in
that case. We want to to be able to define completions at multiple hierarchical
levels. :class:`~prompt_toolkit.completion.NestedCompleter` solves this issue:

.. code:: python

    from prompt_toolkit import prompt
    from prompt_toolkit.completion import NestedCompleter

    completer = NestedCompleter.from_nested_dict({
        'show': {
            'version': None,
            'clock': None,
            'ip': {
                'interface': {'brief'}
            }
        },
        'exit': None,
    })

    text = prompt('# ', completer=completer)
    print('You said: %s' % text)

Whenever there is a ``None`` value in the dictionary, it means that there is no
further nested completion at that point. When all values of a dictionary would
be ``None``, it can also be replaced with a set.


A custom completer
^^^^^^^^^^^^^^^^^^

For more complex examples, it makes sense to create a custom completer. For
instance:

.. code:: python

    from prompt_toolkit import prompt
    from prompt_toolkit.completion import Completer, Completion

    class MyCustomCompleter(Completer):
        def get_completions(self, document, complete_event):
            yield Completion('completion', start_position=0)

    text = prompt('> ', completer=MyCustomCompleter())

A :class:`~prompt_toolkit.completion.Completer` class has to implement a
generator named :meth:`~prompt_toolkit.completion.Completer.get_completions`
that takes a :class:`~prompt_toolkit.document.Document` and yields the current
:class:`~prompt_toolkit.completion.Completion` instances. Each completion
contains a portion of text, and a position.

The position is used for fixing text before the cursor. Pressing the tab key
could for instance turn parts of the input from lowercase to uppercase. This
makes sense for a case insensitive completer. Or in case of a fuzzy completion,
it could fix typos. When ``start_position`` is something negative, this amount
of characters will be deleted and replaced.


Styling individual completions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Each completion can provide a custom style, which is used when it is rendered
in the completion menu or toolbar. This is possible by passing a style to each
:class:`~prompt_toolkit.completion.Completion` instance.

.. code:: python

    from prompt_toolkit.completion import Completer, Completion

    class MyCustomCompleter(Completer):
        def get_completions(self, document, complete_event):
            # Display this completion, black on yellow.
            yield Completion('completion1', start_position=0,
                             style='bg:ansiyellow fg:ansiblack')

            # Underline completion.
            yield Completion('completion2', start_position=0,
                             style='underline')

            # Specify class name, which will be looked up in the style sheet.
            yield Completion('completion3', start_position=0,
                             style='class:special-completion')

The "colorful-prompts.py" example uses completion styling:

.. image:: ../images/colorful-completions.png

Finally, it is possible to pass :ref:`formatted text <formatted_text>` for the
``display`` attribute of a :class:`~prompt_toolkit.completion.Completion`. This
provides all the freedom you need to display the text in any possible way. It
can also be combined with the ``style`` attribute. For instance:

.. code:: python


    from prompt_toolkit.completion import Completer, Completion
    from prompt_toolkit.formatted_text import HTML

    class MyCustomCompleter(Completer):
        def get_completions(self, document, complete_event):
            yield Completion(
                'completion1', start_position=0,
                display=HTML('<b>completion</b><ansired>1</ansired>'),
                style='bg:ansiyellow')


Fuzzy completion
^^^^^^^^^^^^^^^^

If one possible completions is "django_migrations", a fuzzy completer would
allow you to get this by typing "djm" only, a subset of characters for this
string.

Prompt_toolkit ships with a :class:`~prompt_toolkit.completion.FuzzyCompleter`
and :class:`~prompt_toolkit.completion.FuzzyWordCompleter` class. These provide
the means for doing this kind of "fuzzy completion". The first one can take any
completer instance and wrap it so that it becomes a fuzzy completer. The second
one behaves like a :class:`~prompt_toolkit.completion.WordCompleter` wrapped
into a :class:`~prompt_toolkit.completion.FuzzyCompleter`.


Complete while typing
^^^^^^^^^^^^^^^^^^^^^

Autcompletions can be generated automatically while typing or when the user
presses the tab key. This can be configured with the ``complete_while_typing``
option:

.. code:: python

    text = prompt('Enter HTML: ', completer=my_completer,
                  complete_while_typing=True)

Notice that this setting is incompatible with the ``enable_history_search``
option. The reason for this is that the up and down key bindings would conflict
otherwise. So, make sure to disable history search for this.


Asynchronous completion
^^^^^^^^^^^^^^^^^^^^^^^

When generating the completions takes a lot of time, it's better to do this in
a background thread. This is possible by wrapping the completer in a
:class:`~prompt_toolkit.completion.ThreadedCompleter`, but also by passing the
`complete_in_thread=True` argument.


.. code:: python

    text = prompt('> ', completer=MyCustomCompleter(), complete_in_thread=True)


Input validation
----------------

A prompt can have a validator attached. This is some code that will check
whether the given input is acceptable and it will only return it if that's the
case. Otherwise it will show an error message and move the cursor to a given
position.

A validator should implements the :class:`~prompt_toolkit.validation.Validator`
abstract base class. This requires only one method, named ``validate`` that
takes a :class:`~prompt_toolkit.document.Document` as input and raises
:class:`~prompt_toolkit.validation.ValidationError` when the validation fails.

.. code:: python

    from prompt_toolkit.validation import Validator, ValidationError
    from prompt_toolkit import prompt

    class NumberValidator(Validator):
        def validate(self, document):
            text = document.text

            if text and not text.isdigit():
                i = 0

                # Get index of first non numeric character.
                # We want to move the cursor here.
                for i, c in enumerate(text):
                    if not c.isdigit():
                        break

                raise ValidationError(message='This input contains non-numeric characters',
                                      cursor_position=i)

    number = int(prompt('Give a number: ', validator=NumberValidator()))
    print('You said: %i' % number)

.. image:: ../images/number-validator.png

By default, the input is validated in real-time while the user is typing, but
prompt_toolkit can also validate after the user presses the enter key:

.. code:: python

    prompt('Give a number: ', validator=NumberValidator(),
           validate_while_typing=False)

If the input validation contains some heavy CPU intensive code, but you don't
want to block the event loop, then it's recommended to wrap the validator class
in a :class:`~prompt_toolkit.validation.ThreadedValidator`.

Validator from a callable
^^^^^^^^^^^^^^^^^^^^^^^^^

Instead of implementing the :class:`~prompt_toolkit.validation.Validator`
abstract base class, it is also possible to start from a simple function and
use the :meth:`~prompt_toolkit.validation.Validator.from_callable` classmethod.
This is easier and sufficient for probably 90% of the validators. It looks as
follows:

.. code:: python

    from prompt_toolkit.validation import Validator
    from prompt_toolkit import prompt

    def is_number(text):
        return text.isdigit()

    validator = Validator.from_callable(
        is_number,
        error_message='This input contains non-numeric characters',
        move_cursor_to_end=True)

    number = int(prompt('Give a number: ', validator=validator))
    print('You said: %i' % number)

We define a function that takes a string, and tells whether it's valid input or
not by returning a boolean.
:meth:`~prompt_toolkit.validation.Validator.from_callable` turns that into a
:class:`~prompt_toolkit.validation.Validator` instance. Notice that setting the
cursor position is not possible this way.


History
-------

A :class:`~prompt_toolkit.history.History` object keeps track of all the
previously entered strings, so that the up-arrow can reveal previously entered
items.

The recommended way is to use a
:class:`~prompt_toolkit.shortcuts.PromptSession`, which uses an
:class:`~prompt_toolkit.history.InMemoryHistory` for the entire session by
default. The following example has a history out of the box:

.. code:: python

   from prompt_toolkit import PromptSession

   session = PromptSession()

   while True:
       session.prompt()

To persist a history to disk, use a :class:`~prompt_toolkit.history.FileHistory`
instead of the default
:class:`~prompt_toolkit.history.InMemoryHistory`. This history object can be
passed either to a :class:`~prompt_toolkit.shortcuts.PromptSession` or to the
:meth:`~prompt_toolkit.shortcuts.prompt` function. For instance:

.. code:: python

   from prompt_toolkit import PromptSession
   from prompt_toolkit.history import FileHistory

   session = PromptSession(history=FileHistory('~/.myhistory'))

   while True:
       session.prompt()


Auto suggestion
---------------

Auto suggestion is a way to propose some input completions to the user like the
`fish shell <http://fishshell.com/>`_.

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:`→` 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.shortcuts.PromptSession` does this for you.

Example:

.. code:: python

    from prompt_toolkit import PromptSession
    from prompt_toolkit.history import InMemoryHistory
    from prompt_toolkit.auto_suggest import AutoSuggestFromHistory

    session = PromptSession()

    while True:
        text = session.prompt('> ', auto_suggest=AutoSuggestFromHistory())
        print('You said: %s' % text)

.. image:: ../images/auto-suggestion.png

A suggestion does not have to come from the history. Any implementation of the
:class:`~prompt_toolkit.auto_suggest.AutoSuggest` abstract base class can be
passed as an argument.


Adding a bottom toolbar
-----------------------

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.
Here we have an example of a callable that returns an
:class:`~prompt_toolkit.formatted_text.HTML` object. By default, the toolbar
has the **reversed style**, which is why we are setting the background instead
of the foreground.

.. code:: python

    from prompt_toolkit import prompt
    from prompt_toolkit.formatted_text import HTML

    def bottom_toolbar():
        return HTML('This is a <b><style bg="ansired">Toolbar</style></b>!')

    text = prompt('> ', bottom_toolbar=bottom_toolbar)
    print('You said: %s' % text)

.. image:: ../images/bottom-toolbar.png

Similar, we could use a list of style/text tuples.

.. code:: python

    from prompt_toolkit import prompt
    from prompt_toolkit.styles import Style

    def bottom_toolbar():
        return [('class:bottom-toolbar', ' This is a toolbar. ')]

    style = Style.from_dict({
        'bottom-toolbar': '#ffffff bg:#333333',
    })

    text = prompt('> ', bottom_toolbar=bottom_toolbar, style=style)
    print('You said: %s' % text)

The default class name is ``bottom-toolbar`` and that will also be used to fill
the background of the toolbar.


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 recognize this
as the `RPROMPT` option.

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

    from prompt_toolkit import prompt
    from prompt_toolkit.styles import Style

    example_style = Style.from_dict({
        'rprompt': 'bg:#ff0066 #ffffff',
    })

    def get_rprompt():
        return '<rprompt>'

    answer = prompt('> ', rprompt=get_rprompt, style=example_style)

.. image:: ../images/rprompt.png

The ``get_rprompt`` function can return any kind of formatted text such as
:class:`~prompt_toolkit.formatted_text.HTML`. it is also possible to pass text
directly to the ``rprompt`` argument of the
:func:`~prompt_toolkit.shortcuts.prompt` function. It does not have to be a
callable.


Vi input mode
-------------

Prompt-toolkit supports both Emacs and Vi key bindings, similar to Readline.
The :func:`~prompt_toolkit.shortcuts.prompt` function will use Emacs bindings by
default. This is done because on most operating systems, also the Bash shell
uses Emacs bindings by default, and that is more intuitive. If however, Vi
binding are required, just pass ``vi_mode=True``.

.. code:: python

    from prompt_toolkit import prompt

    prompt('> ', vi_mode=True)


Adding custom key bindings
--------------------------

By default, every prompt already has a set of key bindings which implements the
usual Vi or Emacs behavior. We can extend this by passing another
:class:`~prompt_toolkit.key_binding.KeyBindings` instance to the
``key_bindings`` argument of the :func:`~prompt_toolkit.shortcuts.prompt`
function or the :class:`~prompt_toolkit.shortcuts.PromptSession` class.

An example of a prompt that prints ``'hello world'`` when :kbd:`Control-T` is pressed.

.. code:: python

    from prompt_toolkit import prompt
    from prompt_toolkit.application import run_in_terminal
    from prompt_toolkit.key_binding import KeyBindings

    bindings = KeyBindings()

    @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` 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Often, some key bindings can be enabled or disabled according to a certain
condition. For instance, the Emacs and Vi bindings will never be active at the
same time, but it is possible to switch between Emacs and Vi bindings at run
time.

In order to enable a key binding according to a certain condition, we have to
pass it a :class:`~prompt_toolkit.filters.Filter`, usually a
:class:`~prompt_toolkit.filters.Condition` instance. (:ref:`Read more about
filters <filters>`.)

.. code:: python

    from prompt_toolkit import prompt
    from prompt_toolkit.filters import Condition
    from prompt_toolkit.key_binding import KeyBindings

    bindings = KeyBindings()

    @Condition
    def is_active():
        " Only activate key binding on the second half of each minute. "
        return datetime.datetime.now().second > 30

    @bindings.add('c-t', filter=is_active)
    def _(event):
        # ...
        pass

    prompt('> ', key_bindings=bindings)


Dynamically switch between Emacs and Vi mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The :class:`~prompt_toolkit.application.Application` has an ``editing_mode``
attribute. We can change the key bindings by changing this attribute from
``EditingMode.VI`` to ``EditingMode.EMACS``.

.. code:: python

    from prompt_toolkit import prompt
    from prompt_toolkit.application.current import get_app
    from prompt_toolkit.enums import EditingMode
    from prompt_toolkit.key_binding import KeyBindings

    def run():
        # Create a set of key bindings.
        bindings = KeyBindings()

        # Add an additional key binding for toggling this flag.
        @bindings.add('f4')
        def _(event):
            " Toggle between Emacs and Vi mode. "
            app = event.app

            if app.editing_mode == EditingMode.VI:
                app.editing_mode = EditingMode.EMACS
            else:
                app.editing_mode = EditingMode.VI

        # Add a toolbar at the bottom to display the current input mode.
        def bottom_toolbar():
            " Display the current input mode. "
            text = 'Vi' if get_app().editing_mode == EditingMode.VI else 'Emacs'
            return [
                ('class:toolbar', ' [F4] %s ' % text)
            ]

        prompt('> ', key_bindings=bindings, bottom_toolbar=bottom_toolbar)

    run()

:ref:`Read more about key bindings ...<key_bindings>`

Using control-space for completion
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

An popular short cut that people sometimes use it to use control-space for
opening the autocompletion menu instead of the tab key. This can be done with
the following key binding.

.. code:: python

    kb = KeyBindings()

    @kb.add('c-space')
    def _(event):
        " Initialize autocompletion, or select the next completion. "
        buff = event.app.current_buffer
        if buff.complete_state:
            buff.complete_next()
        else:
            buff.start_completion(select_first=False)


Other prompt options
--------------------

Multiline input
^^^^^^^^^^^^^^^

Reading multiline input is as easy as passing the ``multiline=True`` parameter.

.. code:: python

    from prompt_toolkit import prompt

    prompt('> ', multiline=True)

A side effect of this is that the enter key will now insert a newline instead
of accepting and returning the input. The user will now have to press
:kbd:`Meta+Enter` in order to accept the input. (Or :kbd:`Escape` followed by
:kbd:`Enter`.)

It is possible to specify a continuation prompt. This works by passing a
``prompt_continuation`` callable to :func:`~prompt_toolkit.shortcuts.prompt`.
This function is supposed to return :ref:`formatted text <formatted_text>`, or
a list of ``(style, text)`` tuples. The width of the returned text should not
exceed the given width. (The width of the prompt margin is defined by the
prompt.)

.. code:: python

    from prompt_toolkit import prompt

    def prompt_continuation(width, line_number, is_soft_wrap):
        return '.' * width
        # Or: return [('', '.' * width)]

    prompt('multiline input> ', multiline=True,
           prompt_continuation=prompt_continuation)

.. image:: ../images/multiline-input.png


Passing a default
^^^^^^^^^^^^^^^^^

A default value can be given:

.. code:: python

    from prompt_toolkit import prompt
    import getpass

    prompt('What is your name: ', default='%s' % getpass.getuser())


Mouse support
^^^^^^^^^^^^^

There is limited mouse support for positioning the cursor, for scrolling (in
case of large multiline inputs) and for clicking in the autocompletion menu.

Enabling can be done by passing the ``mouse_support=True`` option.

.. code:: python

    from prompt_toolkit import prompt

    prompt('What is your name: ', mouse_support=True)


Line wrapping
^^^^^^^^^^^^^

Line wrapping is enabled by default. This is what most people are used to and
this is what GNU Readline does. When it is disabled, the input string will
scroll horizontally.

.. code:: python

    from prompt_toolkit import prompt

    prompt('What is your name: ', wrap_lines=False)


Password input
^^^^^^^^^^^^^^

When the ``is_password=True`` flag has been given, the input is replaced by
asterisks (``*`` characters).

.. code:: python

    from prompt_toolkit import prompt

    prompt('Enter password: ', is_password=True)


Cursor shapes
-------------

Many terminals support displaying different types of cursor shapes. The most
common are block, beam or underscore. Either blinking or not. It is possible to
decide which cursor to display while asking for input, or in case of Vi input
mode, have a modal prompt for which its cursor shape changes according to the
input mode.

.. code:: python

    from prompt_toolkit import prompt
    from prompt_toolkit.cursor_shapes import CursorShape, ModalCursorShapeConfig

    # Several possible values for the `cursor_shape_config` parameter:
    prompt('>', cursor=CursorShape.BLOCK)
    prompt('>', cursor=CursorShape.UNDERLINE)
    prompt('>', cursor=CursorShape.BEAM)
    prompt('>', cursor=CursorShape.BLINKING_BLOCK)
    prompt('>', cursor=CursorShape.BLINKING_UNDERLINE)
    prompt('>', cursor=CursorShape.BLINKING_BEAM)
    prompt('>', cursor=ModalCursorShapeConfig())


Prompt in an `asyncio` application
----------------------------------

.. note::

    New in prompt_toolkit 3.0. (In prompt_toolkit 2.0 this was possible using a
    work-around).

For `asyncio <https://docs.python.org/3/library/asyncio.html>`_ applications,
it's very important to never block the eventloop. However,
:func:`~prompt_toolkit.shortcuts.prompt` is blocking, and calling this would
freeze the whole application. Asyncio actually won't even allow us to run that
function within a coroutine.

The answer is to call
:meth:`~prompt_toolkit.shortcuts.PromptSession.prompt_async` instead of
:meth:`~prompt_toolkit.shortcuts.PromptSession.prompt`. The async variation
returns a coroutines and is awaitable.

.. code:: python

    from prompt_toolkit import PromptSession
    from prompt_toolkit.patch_stdout import patch_stdout

    async def my_coroutine():
        session = PromptSession()
        while True:
            with patch_stdout():
                result = await session.prompt_async('Say something: ')
            print('You said: %s' % result)

The :func:`~prompt_toolkit.patch_stdout.patch_stdout` context manager is
optional, but it's recommended, because other coroutines could print to stdout.
This ensures that other output won't destroy the prompt.


Reading keys from stdin, one key at a time, but without a prompt
----------------------------------------------------------------

Suppose that you want to use prompt_toolkit to read the keys from stdin, one
key at a time, but not render a prompt to the output, that is also possible:

.. code:: python

    import asyncio

    from prompt_toolkit.input import create_input
    from prompt_toolkit.keys import Keys


    async def main() -> None:
        done = asyncio.Event()
        input = create_input()

        def keys_ready():
            for key_press in input.read_keys():
                print(key_press)

                if key_press.key == Keys.ControlC:
                    done.set()

        with input.raw_mode():
            with input.attach(keys_ready):
                await done.wait()


    if __name__ == "__main__":
        asyncio.run(main())

The above snippet will print the `KeyPress` object whenever a key is pressed.
This is also cross platform, and should work on Windows.