0
# InquirerPy
1

2
A comprehensive Python library that provides interactive command-line user interfaces, serving as a modern port of the popular Inquirer.js library. InquirerPy offers a rich collection of customizable prompts built on top of prompt-toolkit, providing cross-platform compatibility with extensive customization options for styling, key bindings, and modern Python type hinting.
3

4
## Package Information
5

6
- **Package Name**: InquirerPy
7
- **Language**: Python
8
- **Installation**: `pip install InquirerPy`
9
- **Python Requirements**: >= 3.7
10

11
## Core Imports
12

13
Classic syntax (PyInquirer compatible):
14

15
```python
16
from InquirerPy import prompt
17
```
18

19
Alternate syntax with type hints:
20

21
```python
22
from InquirerPy import inquirer
23
```
24

25
Individual prompt classes:
26

27
```python
28
from InquirerPy.prompts import InputPrompt, ConfirmPrompt, ListPrompt
29
```
30

31
## Basic Usage
32

33
### Classic Syntax
34

35
```python
36
from InquirerPy import prompt
37

38
questions = [
39
    {"type": "input", "message": "What's your name:", "name": "name"},
40
    {"type": "confirm", "message": "Confirm?", "name": "confirm", "default": True},
41
    {"type": "list", "message": "Choose option:", "choices": ["Option 1", "Option 2"], "name": "choice"}
42
]
43

44
result = prompt(questions)
45
print(f"Hello {result['name']}, you chose {result['choice']}")
46
```
47

48
### Alternate Syntax
49

50
```python
51
from InquirerPy import inquirer
52

53
name = inquirer.text(message="What's your name:").execute()
54
confirm = inquirer.confirm(message="Confirm?", default=True).execute()
55
choice = inquirer.select(message="Choose option:", choices=["Option 1", "Option 2"]).execute()
56

57
print(f"Hello {name}, you chose {choice}")
58
```
59

60
## Architecture
61

62
InquirerPy is built on a hierarchical architecture:
63

64
- **Entry Points**: Two main APIs - classic `prompt()` function and alternate `inquirer` module
65
- **Prompt Classes**: Specialized classes for different input types inheriting from base classes
66
- **Base Classes**: BaseSimplePrompt, BaseComplexPrompt, and BaseListPrompt providing common functionality
67
- **Components**: Validators, separators, styling utilities, and UI containers
68
- **Integration**: Built on prompt-toolkit for cross-platform terminal handling
69

70
## Capabilities
71

72
### Text Input Prompts
73

74
Basic text input, password/secret input, and file path selection with auto-completion and validation support.
75

76
```python { .api }
77
def text(message, default="", validate=None, **kwargs): ...
78
def secret(message, default="", validate=None, **kwargs): ...  
79
def filepath(message, default="", only_files=False, only_directories=False, **kwargs): ...
80
```
81

82
[Text Input](./text-input.md)
83

84
### Confirmation Prompts
85

86
Yes/no confirmation prompts with customizable confirm/reject letters and single keypress operation.
87

88
```python { .api }
89
def confirm(message, default=False, confirm_letter="y", reject_letter="n", **kwargs): ...
90
```
91

92
[Confirmation](./confirmation.md)
93

94
### Selection Prompts
95

96
Single and multi-selection list prompts with navigation, searching, and customizable display options.
97

98
```python { .api }
99
def select(message, choices, default=None, **kwargs): ...
100
def checkbox(message, choices, default=None, **kwargs): ...
101
def rawlist(message, choices, default=None, separator=") ", **kwargs): ...
102
```
103

104
[Selection](./selection.md)
105

106
### Advanced Prompts
107

108
Specialized prompts including fuzzy search, expandable choices, and numeric input with validation.
109

110
```python { .api }
111
def fuzzy(message, choices, default="", match_exact=False, **kwargs): ...
112
def expand(message, choices, default="", help_msg="Help, list all choices", **kwargs): ...
113
def number(message, default=0, float_allowed=False, min_allowed=None, max_allowed=None, **kwargs): ...
114
```
115

116
[Advanced Prompts](./advanced-prompts.md)
117

118
### Classic API Functions
119

120
PyInquirer-compatible prompt functions supporting question dictionaries and async operations.
121

122
```python { .api }
123
def prompt(questions, style=None, vi_mode=False, keybindings=None, **kwargs): ...
124
def prompt_async(questions, style=None, vi_mode=False, keybindings=None, **kwargs): ...
125
```
126

127
[Classic API](./classic-api.md)
128

129
### Utilities and Customization
130

131
Styling, validation, separators, and utility functions for prompt customization and enhanced functionality.
132

133
```python { .api }
134
def get_style(style=None, style_override=True): ...
135
class Separator(line="---------------"): ...
136
class NumberValidator(message="Input should be a number", float_allowed=False): ...
137
```
138

139
[Utilities](./utilities.md)
140

141
## Common Types
142

143
```python { .api }
144
# Session result type
145
InquirerPySessionResult = Dict[Union[str, int], Optional[Union[str, bool, List[Any]]]]
146

147
# Type aliases for flexible parameter types
148
InquirerPyMessage = Union[str, Callable[[InquirerPySessionResult], str]]
149
InquirerPyDefault = Union[Any, Callable[[InquirerPySessionResult], Any]]
150
InquirerPyChoice = Union[List[Any], List["Choice"], List[Dict[str, Any]]]
151
InquirerPyListChoices = Union[
152
    Callable[[InquirerPySessionResult], InquirerPyChoice], 
153
    InquirerPyChoice
154
]
155
InquirerPyValidate = Union[Callable[[Any], bool], "Validator"]
156
InquirerPyKeybindings = Dict[str, List[Dict[str, Union[str, "FilterOrBool", List[str]]]]]
157
InquirerPyQuestions = Union[List[Dict[str, Any]], Dict[str, Any]]
158

159
# Style configuration
160
class InquirerPyStyle(NamedTuple):
161
    dict: Dict[str, str]
162

163
# Choice classes for prompts
164
@dataclass
165
class Choice:
166
    value: Any
167
    name: Optional[str] = None
168
    enabled: bool = False
169

170
@dataclass  
171
class ExpandChoice(Choice):
172
    key: Optional[str] = None
173

174
@dataclass
175
class ExpandHelp:
176
    key: str = "h"
177
    message: str = "Help, list all choices"
178
```