1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
.. _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 realized that all the components for
full screen applications are there and `prompt_toolkit` is very capable of
handling many use situations. `Pyvim
<http://github.com/prompt-toolkit/pyvim>`_ and `pymux
<http://github.com/prompt-toolkit/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 as a readline replacement, (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 a custom layout ourselves.
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 prompt_toolkit import prompt
text = prompt("Give me some input: ")
print(f"You said: {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
<https://github.com/prompt-toolkit/python-prompt-toolkit/tree/master/examples>`_
in the repository.
- First, :ref:`learn how to print text <printing_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 <asking_for_input>` section.
This is useful for almost any use case, even for full screen applications.
It covers autocompletions, syntax highlighting, key bindings, and so on.
- Then, learn about :ref:`dialogs`, which is easy and fun.
- Finally, learn about :ref:`full screen applications
<full_screen_applications>` and read through :ref:`the advanced topics
<advanced_topics>`.
|
