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