0
# Inquirer
1

2
A comprehensive Python library for creating interactive command line user interfaces, based on Inquirer.js. Inquirer enables developers to create sophisticated CLI prompts including text input, password fields, single and multiple choice lists, checkboxes, file path selectors, and external editor integration with built-in validation, custom themes, and cross-platform compatibility.
3

4
## Package Information
5

6
- **Package Name**: inquirer
7
- **Language**: Python
8
- **Installation**: `pip install inquirer`
9
- **Requires**: Python >= 3.9.2
10

11
## Core Imports
12

13
```python
14
import inquirer
15
```
16

17
For direct access to question types:
18

19
```python
20
from inquirer import Text, Password, List, Checkbox, Confirm, Editor, Path
21
```
22

23
For shortcut functions:
24

25
```python
26
from inquirer import text, password, list_input, checkbox, confirm, editor, path
27
```
28

29
For themes:
30

31
```python
32
from inquirer.themes import Default, GreenPassion, RedSolace, BlueComposure
33
```
34

35
## Basic Usage
36

37
```python
38
import inquirer
39

40
# Define questions
41
questions = [
42
    inquirer.Text('name', message="What's your name?"),
43
    inquirer.List('size',
44
                  message="What size do you need?",
45
                  choices=['Large', 'Medium', 'Small']),
46
    inquirer.Checkbox('features',
47
                      message="What features do you want?",
48
                      choices=['Feature A', 'Feature B', 'Feature C']),
49
    inquirer.Confirm('proceed', message="Do you want to proceed?", default=True)
50
]
51

52
# Get answers
53
answers = inquirer.prompt(questions)
54
print(answers)  # {'name': 'John', 'size': 'Medium', 'features': ['Feature A'], 'proceed': True}
55

56
# Using shortcuts for single questions
57
name = inquirer.text(message="Enter your name")
58
confirmed = inquirer.confirm("Are you sure?")
59
```
60

61
## Architecture
62

63
Inquirer follows a modular architecture:
64

65
- **Question Classes**: Seven question types (Text, Password, Editor, Confirm, List, Checkbox, Path) each handling specific input scenarios
66
- **Prompt System**: Central `prompt()` function processes question lists and manages interaction flow
67
- **Render Engine**: Console-based UI rendering with terminal control and event handling
68
- **Theme System**: Customizable color schemes and visual styling
69
- **Validation Framework**: Built-in and custom validation support with error handling
70
- **Shortcut Interface**: Simplified single-question functions for quick interactions
71

72
## Capabilities
73

74
### Question Types
75

76
Core question classes for different input scenarios including text, passwords, selections, confirmations, file paths, and multi-line editing. Each question type provides specific validation and interaction patterns optimized for its use case.
77

78
```python { .api }
79
class Text(name, message="", default=None, autocomplete=None, **kwargs): ...
80
class Password(name, echo="*", **kwargs): ...
81
class List(name, message="", choices=None, default=None, carousel=False, **kwargs): ...
82
class Checkbox(name, message="", choices=None, locked=None, carousel=False, **kwargs): ...
83
class Confirm(name, default=False, **kwargs): ...
84
class Editor(name, **kwargs): ...
85
class Path(name, default=None, path_type="any", exists=None, **kwargs): ...
86
```
87

88
[Question Types](./question-types.md)
89

90
### Prompt System
91

92
Main prompt function and question loading utilities for processing question lists, managing state, and handling user interactions with comprehensive error handling and validation.
93

94
```python { .api }
95
def prompt(questions, render=None, answers=None, theme=themes.Default(), raise_keyboard_interrupt=False): ...
96
def load_from_dict(question_dict): ...
97
def load_from_list(question_list): ...
98
def load_from_json(question_json): ...
99
```
100

101
[Prompt System](./prompt-system.md)
102

103
### Shortcut Functions
104

105
Simplified interface for single questions without creating question objects. These functions provide immediate input collection for quick interactions and scripting scenarios.
106

107
```python { .api }
108
def text(message, autocomplete=None, **kwargs): ...
109
def password(message, **kwargs): ...
110
def list_input(message, **kwargs): ...
111
def checkbox(message, **kwargs): ...
112
def confirm(message, **kwargs): ...
113
def editor(message, **kwargs): ...
114
def path(message, **kwargs): ...
115
```
116

117
[Shortcuts](./shortcuts.md)
118

119
### Themes and Customization
120

121
Theme system providing visual customization including colors, icons, and styling. Includes built-in themes and support for custom theme creation from JSON or dictionaries.
122

123
```python { .api }
124
class Default(): ...
125
class GreenPassion(): ...
126
class RedSolace(): ...
127
class BlueComposure(): ...
128
def load_theme_from_json(json_theme): ...
129
def load_theme_from_dict(dict_theme): ...
130
```
131

132
[Themes](./themes.md)
133

134
### Render System
135

136
Console-based rendering engine providing terminal UI control, event handling, and visual presentation for interactive prompts with customizable themes and cross-platform terminal compatibility.
137

138
```python { .api }
139
class ConsoleRender:
140
    def __init__(self, theme=None): ...
141
    def render(self, question, answers=None): ...
142

143
class Render:
144
    def __init__(self, impl=ConsoleRender): ...
145
    def render(self, question, answers): ...
146
```
147

148
[Render System](./render-system.md)
149

150
## Types and Constants
151

152
```python { .api }
153
class TaggedValue:
154
    """Tagged value for complex choice handling with display/value separation."""
155
    def __init__(self, tag: str, value: any): ...
156
    def __str__(self) -> str: ...
157
    def __repr__(self) -> str: ...
158
    def __eq__(self, other) -> bool: ...
159
    def __ne__(self, other) -> bool: ...
160
    def __hash__(self) -> int: ...
161
    
162
    @property
163
    def tag(self) -> str: ...
164
    
165
    @property
166
    def value(self) -> any: ...
167
    
168
    @property
169
    def tuple(self) -> tuple: ...
170

171
# Path type constants
172
Path.ANY = "any"
173
Path.FILE = "file" 
174
Path.DIRECTORY = "directory"
175

176
# Exception classes
177
class ValidationError(Exception):
178
    """Raised when input validation fails."""
179
    def __init__(self, value, reason: str | None = None): ...
180
    
181
    @property
182
    def value(self): ...
183
    
184
    @property  
185
    def reason(self) -> str | None: ...
186

187
class UnknownQuestionTypeError(Exception):
188
    """Raised when question factory receives unknown question type."""
189

190
class ThemeError(AttributeError):
191
    """Raised when theme configuration is invalid."""
192

193
class EndOfInput(Exception):
194
    """Raised when input stream ends unexpectedly."""
195
    def __init__(self, selection, *args): ...
196
    
197
    @property
198
    def selection(self): ...
199
```