0
# Questionary
1
2
Questionary is a Python library for effortlessly building interactive command line interfaces with beautiful prompts. It provides a comprehensive collection of input prompt types including text input, selections, confirmations, file paths, and multi-question forms, all built on top of prompt_toolkit for cross-platform compatibility and rich styling.
3
4
## Package Information
5
6
- **Package Name**: questionary
7
- **Language**: Python
8
- **Installation**: `pip install questionary`
9
- **Version**: 2.1.0
10
11
## Core Imports
12
13
```python
14
import questionary
15
```
16
17
For specific prompt types:
18
19
```python
20
from questionary import text, select, confirm, checkbox, form
21
```
22
23
For advanced usage:
24
25
```python
26
from questionary import Question, Choice, Separator, Style, Validator
27
```
28
29
## Basic Usage
30
31
```python
32
import questionary
33
34
# Simple text input
35
name = questionary.text("What's your name?").ask()
36
37
# Password input (hidden text)
38
secret = questionary.password("Enter password:").ask()
39
40
# Yes/no confirmation
41
confirmed = questionary.confirm("Are you sure?").ask()
42
43
# Single selection from list
44
choice = questionary.select(
45
"Choose an option:",
46
choices=["Option 1", "Option 2", "Option 3"]
47
).ask()
48
49
# Multiple selection with checkboxes
50
selected = questionary.checkbox(
51
"Select multiple:",
52
choices=["Item A", "Item B", "Item C"]
53
).ask()
54
55
# File path input with completion
56
path = questionary.path("Enter file path:").ask()
57
```
58
59
## Architecture
60
61
Questionary follows a prompt-centric architecture:
62
63
- **Question**: Core class representing individual prompts with execution methods
64
- **Prompt Functions**: Factory functions (text, select, etc.) that create configured Question instances
65
- **Form**: Container for multi-question workflows with shared execution
66
- **Choice/Separator**: Configuration objects for selection-based prompts
67
- **Validation**: Input validation through Validator classes and custom functions
68
69
This design enables both simple single-question prompts and complex multi-step forms while maintaining consistent styling and behavior patterns across all prompt types.
70
71
## Capabilities
72
73
### Text Input Prompts
74
75
Basic text input functionality including single-line text, password input, and multiline text with optional validation and custom styling.
76
77
```python { .api }
78
def text(message: str, default: str = "", validate: Any = None, qmark: str = "?",
79
style: Optional[Style] = None, multiline: bool = False,
80
instruction: Optional[str] = None, lexer: Optional[Lexer] = None,
81
**kwargs) -> Question: ...
82
83
def password(message: str, default: str = "", validate: Any = None,
84
qmark: str = "?", style: Optional[Style] = None,
85
**kwargs) -> Question: ...
86
```
87
88
[Text Input](./text-input.md)
89
90
### Selection Prompts
91
92
Single and multiple choice selection prompts with keyboard navigation, search filtering, and customizable display options.
93
94
```python { .api }
95
def select(message: str, choices: Sequence[Union[str, Choice, Dict]],
96
default: Optional[Union[str, Choice, Dict]] = None, qmark: str = "?",
97
pointer: Optional[str] = "»", style: Optional[Style] = None,
98
use_shortcuts: bool = False, use_arrow_keys: bool = True,
99
**kwargs) -> Question: ...
100
101
def checkbox(message: str, choices: Sequence[Union[str, Choice, Dict]],
102
default: Optional[str] = None,
103
validate: Callable[[List[str]], Union[bool, str]] = lambda a: True,
104
**kwargs) -> Question: ...
105
106
def rawselect(message: str, choices: Sequence[Union[str, Choice, Dict]],
107
default: Optional[str] = None, qmark: str = "?",
108
**kwargs) -> Question: ...
109
```
110
111
[Selection Prompts](./selection-prompts.md)
112
113
### Confirmation Prompts
114
115
Yes/no confirmation dialogs with customizable default responses and automatic key handling.
116
117
```python { .api }
118
def confirm(message: str, default: bool = True, qmark: str = "?",
119
style: Optional[Style] = None, auto_enter: bool = True,
120
instruction: Optional[str] = None, **kwargs) -> Question: ...
121
```
122
123
### Autocomplete and Path Input
124
125
Text input with intelligent completion including word completion for predefined choices and file system path completion.
126
127
```python { .api }
128
def autocomplete(message: str, choices: List[str], default: str = "",
129
qmark: str = "?", completer: Optional[Completer] = None,
130
meta_information: Optional[Dict[str, Any]] = None,
131
ignore_case: bool = True, match_middle: bool = True,
132
**kwargs) -> Question: ...
133
134
def path(message: str, default: Union[Path, str] = "", qmark: str = "?",
135
validate: Any = None, completer: Optional[Completer] = None,
136
only_directories: bool = False, **kwargs) -> Question: ...
137
```
138
139
[Autocomplete and Paths](./autocomplete-paths.md)
140
141
### Forms and Multi-Question Workflows
142
143
Multi-question forms that execute a series of prompts and return consolidated results, supporting conditional logic and field validation.
144
145
```python { .api }
146
def form(**kwargs: Question) -> Form: ...
147
148
class Form:
149
def ask(self, patch_stdout: bool = False,
150
kbi_msg: str = DEFAULT_KBI_MESSAGE) -> Dict[str, Any]: ...
151
def ask_async(self, patch_stdout: bool = False,
152
kbi_msg: str = DEFAULT_KBI_MESSAGE) -> Dict[str, Any]: ...
153
```
154
155
[Forms](./forms.md)
156
157
### Prompt Execution and Control
158
159
Comprehensive prompt execution methods supporting both synchronous and asynchronous operation, with error handling and batch processing capabilities.
160
161
```python { .api }
162
def prompt(questions: Union[Dict, Iterable[Mapping]],
163
answers: Optional[Mapping] = None, patch_stdout: bool = False,
164
true_color: bool = False, kbi_msg: str = DEFAULT_KBI_MESSAGE,
165
**kwargs) -> Dict[str, Any]: ...
166
167
def prompt_async(questions: Union[Dict, Iterable[Mapping]],
168
answers: Optional[Mapping] = None, **kwargs) -> Dict[str, Any]: ...
169
```
170
171
[Execution Control](./execution-control.md)
172
173
### Core Classes and Configuration
174
175
Essential classes for building and customizing prompts, including choice configuration, styling, validation, and conditional logic.
176
177
```python { .api }
178
class Question:
179
def ask(self, patch_stdout: bool = False,
180
kbi_msg: str = DEFAULT_KBI_MESSAGE) -> Any: ...
181
def ask_async(self, patch_stdout: bool = False,
182
kbi_msg: str = DEFAULT_KBI_MESSAGE) -> Any: ...
183
def skip_if(self, condition: bool, default: Any = None) -> Question: ...
184
185
class Choice:
186
def __init__(self, title: FormattedText, value: Optional[Any] = None,
187
disabled: Optional[str] = None, checked: Optional[bool] = False,
188
shortcut_key: Optional[Union[str, bool]] = True,
189
description: Optional[str] = None) -> None: ...
190
191
class Separator(Choice):
192
def __init__(self, line: Optional[str] = None) -> None: ...
193
```
194
195
[Core Classes](./core-classes.md)
196
197
## Utility Functions
198
199
Additional utility functions for formatted output and prompt toolkit integration.
200
201
```python { .api }
202
def print(text: str, style: Optional[str] = None, **kwargs) -> None: ...
203
204
def press_any_key_to_continue(message: Optional[str] = None,
205
style: Optional[Style] = None,
206
**kwargs) -> Question: ...
207
```
208
209
## Type Definitions
210
211
```python { .api }
212
# Core types
213
FormattedText = Union[str, List[Tuple[str, str]], List[Tuple[str, str, Callable]], None]
214
215
# Form field definition
216
class FormField(NamedTuple):
217
key: str
218
question: Question
219
220
# Re-exported from prompt_toolkit
221
class Style: ...
222
class Validator: ...
223
class ValidationError(Exception): ...
224
```