This page is about building prompts. Pieces of code that we can embed in a program for asking the user for input. 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 building full screen applications
<full_screen_applications> page.
The following snippet is the most simple example, it uses the ~prompt_toolkit.shortcuts.prompt function to asks the user for input and returns the text. Just like (raw_)input.
from __future__ import unicode_literals
from prompt_toolkit import prompt
text = prompt('Give me some input: ')
print('You said: %s' % text)What we get here is a simple prompt that supports the Emacs key bindings like readline, but further nothing special. However, ~prompt_toolkit.shortcuts.prompt has a lot of configuration options. 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 are unicode strings (and not bytes). Either use from __future__ import unicode_literals or explicitely put a small 'u' in front of every string.
Adding syntax highlighting is as simple as adding a lexer. All of the Pygments lexers can be used after wrapping them in a ~prompt_toolkit.layout.lexers.PygmentsLexer. It is also possible to create a custom lexer by implementing the ~prompt_toolkit.layout.lexers.Lexer abstract base class.
from pygments.lexers import HtmlLexer
from prompt_toolkit.shortcuts import prompt
from prompt_toolkit.layout.lexers import PygmentsLexer
text = prompt('Enter HTML', lexer=PygmentsLexer(HtmlLexer))
print('You said: %s' % text)
The colors for syntax highlighting are defined by a ~prompt_toolkit.styles.Style instance. By default, a neutral built-in style is used, but any style instance can be passed to the ~prompt_toolkit.shortcuts.prompt function. A simple way to create a style, is by using the ~prompt_toolkit.styles.Style.from_dict function:
from pygments.lexers import HtmlLexer
from prompt_toolkit.shortcuts import prompt
from prompt_toolkit.styles import Style
from prompt_toolkit.layout.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,reverseandnoreverse. - Colors can be in the
#ff0000format, 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.
All Pygments style classes can be used as well, when they are wrapped through ~prompt_toolkit.styles.style_from_pygments.
Suppose we'd like to use a Pygments style, for instance pygments.styles.tango.TangoStyle, that is possible like this:
Creating a custom style could be done like this:
from prompt_toolkit.shortcuts import prompt
from prompt_toolkit.styles import style_from_pygments, merge_style
from prompt_toolkit.layout.lexers import PygmentsLexer
from pygments.styles.tango import TangoStyle
from pygments.lexers import HtmlLexer
our_style = merge_style([
style_from_pygments(TangoStyle),
Style.from_dict({
'pygments.comment': '#888888 bold',
'pygments.keyword': '#ff88ff bold',
})
])
text = prompt('Enter HTML: ', lexer=PygmentsLexer(HtmlLexer),
style=our_style)It is possible to add some colors to the prompt itself. For this, we need a get_prompt function. This is a function that can return a string, but also a list of (style, text) tuples.
from prompt_toolkit.shortcuts import prompt
from prompt_toolkit.styles import Style
style = Style.from_dict({
# User input.
'': '#ff0066',
# Prompt.
'username': '#884444',
'at': '#00aa00',
'colon': '#00aa00',
'pound': '#00aa00',
'host': '#000088 bg:#aaaaff',
'path': '#884444 underline',
})
def get_prompt():
return [
('class:username', 'john'),
('class:at', '@'),
('class:host', 'localhost'),
('class:colon', ':'),
('class:path', '/user/john'),
('class:pound', '# '),
]
text = prompt(get_prompt, style=style)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_toolkit.shortcuts.prompt.prompt` function.
text = prompt(get_prompt, style=style, true_color=True)Autocompletion can be added by passing a completer parameter. This should be an instance of the ~prompt_toolkit.completion.Completer abstract base class. WordCompleter is an example of a completer that implements that interface.
from prompt_toolkit import prompt
from prompt_toolkit.contrib.completers import WordCompleter
html_completer = WordCompleter(['<html>', '<body>', '<head>', '<title>'])
text = prompt('Enter HTML: ', completer=html_completer)
print('You said: %s' % text)WordCompleter is a simple completer that completes the last word before the cursor with any of the given words.
For more complex examples, it makes sense to create a custom completer. For instance:
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 ~prompt_toolkit.completion.Completer class has to implement a generator named ~prompt_toolkit.completion.Completer.get_completions that takes a ~prompt_toolkit.document.Document and yields the current ~prompt_toolkit.completion.Completion instances. Each completion contains a portion of text, and a position.
The position is used in 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.
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 possition.
A validator should implements the ~prompt_toolkit.validation.Validator abstract base class. This requires only one method, named validate that takes a ~prompt_toolkit.document.Document as input and raises ~prompt_toolkit.validation.ValidationError when the validation fails.
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 fist 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)A ~prompt_toolkit.history.History object keeps track of all the previously entered strings. When nothing is passed into the ~prompt_toolkit.shortcuts.prompt function, it will start with an empty history each time again. Usually, however, for a REPL, you want to keep the same history between several calls to ~prompt_toolkit.shortcuts.prompt. This is possible by instantiating a ~prompt_toolkit.history.History object and passing that to each prompt call.
from prompt_toolkit.history import InMemoryHistory
from prompt_toolkit import prompt
history = InMemoryHistory()
while True:
prompt(history=history)To persist a history to disk, use ~prompt_toolkit.history.FileHistory instead instead of ~prompt_toolkit.history.InMemoryHistory.
Auto suggestion is a way to propose some input completions to the user like the fish shell.
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 → will insert this suggestion.
Note
When suggestions are based on the history, don't forget to share one ~prompt_toolkit.history.History object between consecutive ~prompt_toolkit.shortcuts.prompt calls.
Example:
from prompt_toolkit import prompt
from prompt_toolkit.history import InMemoryHistory
from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
history = InMemoryHistory()
while True:
text = prompt('> ', history=history, auto_suggest=AutoSuggestFromHistory())
print('You said: %s' % text)A suggestion does not have to come from the history. Any implementation of the ~prompt_toolkit.auto_suggest.AutoSuggest abstract base class can be passed as an argument.
Adding a bottom toolbar is as easy as passing a get_bottom_toolbar_tokens function to ~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.
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({
'class: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.
The ~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_tokens callable.
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)
Prompt-toolkit supports both Emacs and Vi key bindings, similar to Readline. The ~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.
from prompt_toolkit import prompt
prompt('> ', vi_mode=True)The ~prompt_toolkit.shortcuts.prompt function accepts an optional key_bindings_registry argument. This should be a ~prompt_toolkit.key_binding.registry.Registry instance which hold all of the key bindings.
It would be possible to create such a ~prompt_toolkit.key_binding.registry.Registry class ourself, but usually, for a prompt, we would like to have at least the basic (Emacs/Vi) bindings and start from there. That's what the ~prompt_toolkit.key_binding.manager.KeyBindingManager class does.
An example of a prompt that prints 'hello world' when Control-T is pressed.
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):
def print_hello():
print('hello world')
run_in_terminal(print_hello)
text = prompt('> ', key_bindings=bindings)
print('You said: %s' % text)Note that we use ~prompt_toolkit.application.run_in_terminal. This ensures that the output of the print-statement and the prompt don't mix up.
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 ~prompt_toolkit.filters.CLIFilter, usually a ~prompt_toolkit.filters.Condition instance. (Read more about
filters <filters>.)
from prompt_toolkit import prompt
from prompt_toolkit.filters import Condition
from prompt_toolkit.key_binding import KeyBindings
bindings = KeyBindings()
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=Condition(is_active))
def _(event):
# ...
pass
prompt('> ', key_bindings=bindings)The ~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.
from prompt_toolkit import prompt
from prompt_toolkit.application.current import get_app
from prompt_toolkit.filters import Condition
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()Reading multiline input is as easy as passing the multiline=True parameter.
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 Meta+Enter in order to accept the input. (Or Escape followed by Enter.)
It is possible to specify a continuation prompt. This works by passing a get_continuation_tokens callable to prompt. This function can return 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.)
def prompt_continuation(width):
return [('', '.' * width)]
prompt('> ', multiline=True, prompt_continuation=prompt_continuation)A default value can be given:
from prompt_toolkit import prompt
import getpass
prompt('What is your name: ', default='%s' % getpass.getuser())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.
from prompt_toolkit import prompt
import getpass
prompt('What is your name: ', mouse_support=True)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.
from prompt_toolkit import prompt
import getpass
prompt('What is your name: ', wrap_lines=False)When the is_password=True flag has been given, the input is replaced by asterisks (* characters).
from prompt_toolkit import prompt
import getpass
prompt('Enter password: ', is_password=True)For asyncio applications, it's very important to never block the eventloop. However, ~prompt_toolkit.shortcuts.prompt is blocking, and calling this would freeze the whole application. A quick fix is to call this function via the asyncio eventloop.run_in_executor, but that would cause the user interface to run in another thread. (If we have custom key bindings for instance, it would be better to run them in the same thread as the other code.)
The answer is to run the prompt_toolkit interface on top of the asyncio event loop. Prompting the user for input is as simple as calling ~prompt_toolkit.shortcuts.prompt with the async_=True argument.
from prompt_toolkit import prompt
async def my_coroutine():
while True:
result = await prompt('Say something: ', patch_stdout=True, async_=True)
print('You said: %s' % result)The patch_stdout=True parameter is optional, but it's recommended, because other coroutines could print to stdout. This option ensures that other output won't destroy the prompt.