Question Types
The different question types are meant to cover different use cases. The parameters and configuration options are explained in detail for each type. But before we get into to many details, here is a cheatsheet with the available question types:
use Text to ask for free text input
use Password to ask for free text where the text is hidden
use File Path to ask for a file or directory path with autocompletion
use Confirmation to ask a yes or no question
use Select to ask the user to select one item from a beautiful list
use Raw Select to ask the user to select one item from a list
use Checkbox to ask the user to select any number of items from a list
use Autocomplete to ask for free text with autocomplete help
use Press Any Key To Continue to ask the user to press any key to continue
Text
- questionary.text(default='', validate=None, qmark='?', style=None, multiline=False, instruction=None, lexer=None, **kwargs)[source]
Prompt the user to enter a free text message.
This question type can be used to prompt the user for some text input.
Example
>>> import questionary >>> questionary.text("What's your first name?").ask() ? What's your first name? Tom 'Tom'
This is just a really basic example, the prompt can be customised using the parameters.
- Parameters:
message (
str
) – Question text.default (
str
) – Default value will be returned if the user just hits enter.validate (
Any
) –Require the entered value to pass a validation. The value can not be submitted until the validator accepts it (e.g. to check minimum password length).
This can either be a function accepting the input and returning a boolean, or an class reference to a subclass of the prompt toolkit Validator class.
qmark (
str
) – Question prefix displayed in front of the question. By default this is a?
.style (
Optional
[Style
]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.multiline (
bool
) – IfTrue
, multiline input will be enabled.instruction (
Optional
[str
]) – Write instructions for the user if needed. IfNone
andmultiline=True
, some instructions will appear.lexer (
Optional
[Lexer
]) – Supply a valid lexer to style the answer. Leave empty to use a simple one by default.kwargs (
Any
) – Additional arguments, they will be passed to prompt toolkit.
- Returns:
Question instance, ready to be prompted (using
.ask()
).- Return type:
Password
- questionary.password(default='', validate=None, qmark='?', style=None, **kwargs)[source]
A text input where a user can enter a secret which won’t be displayed on the CLI.
This question type can be used to prompt the user for information that should not be shown in the command line. The typed text will be replaced with
*
.Example
>>> import questionary >>> questionary.password("What's your secret?").ask() ? What's your secret? ******** 'secret42'
This is just a really basic example, the prompt can be customised using the parameters.
- Parameters:
message (
str
) – Question text.default (
str
) – Default value will be returned if the user just hits enter.validate (
Any
) –Require the entered value to pass a validation. The value can not be submitted until the validator accepts it (e.g. to check minimum password length).
This can either be a function accepting the input and returning a boolean, or an class reference to a subclass of the prompt toolkit Validator class.
qmark (
str
) – Question prefix displayed in front of the question. By default this is a?
.style (
Optional
[Style
]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.kwargs (Any) –
- Returns:
Question instance, ready to be prompted (using
.ask()
).- Return type:
File Path
- questionary.path(default='', qmark='?', validate=None, completer=None, style=None, only_directories=False, get_paths=None, file_filter=None, complete_style=CompleteStyle.MULTI_COLUMN, **kwargs)[source]
A text input for a file or directory path with autocompletion enabled.
Example
>>> import questionary >>> questionary.path( >>> "What's the path to the projects version file?" >>> ).ask() ? What's the path to the projects version file? ./pyproject.toml './pyproject.toml'
This is just a really basic example, the prompt can be customized using the parameters.
- Parameters:
message (
str
) – Question text.default (
str
) – Default return value (single value).qmark (
str
) – Question prefix displayed in front of the question. By default this is a?
.complete_style (
CompleteStyle
) – How autocomplete menu would be shown, it could beCOLUMN
MULTI_COLUMN
orREADLINE_LIKE
fromprompt_toolkit.shortcuts.CompleteStyle
.validate (
Any
) –Require the entered value to pass a validation. The value can not be submitted until the validator accepts it (e.g. to check minimum password length).
This can either be a function accepting the input and returning a boolean, or an class reference to a subclass of the prompt toolkit Validator class.
completer (
Optional
[Completer
]) – A custom completer to use in the prompt. For more information, see this.style (
Optional
[Style
]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.only_directories (
bool
) – Only show directories in auto completion. This option does not do anything if a customcompleter
is passed.get_paths (
Optional
[Callable
[[],List
[str
]]]) – Set a callable to generate paths to traverse for suggestions. This option does not do anything if a customcompleter
is passed.file_filter (
Optional
[Callable
[[str
],bool
]]) – Optional callable to filter suggested paths. Only paths where the passed callable evaluates toTrue
will show up in the suggested paths. This does not validate the typed path, e.g. it is still possible for the user to enter a path manually, even though this filter evaluates toFalse
. If in addition to filtering suggestions you also want to validate the result, usevalidate
in combination with thefile_filter
.kwargs (Any) –
- Returns:
Question instance, ready to be prompted (using
.ask()
).- Return type:
Confirmation
- questionary.confirm(default=True, qmark='?', style=None, auto_enter=True, instruction=None, **kwargs)[source]
A yes or no question. The user can either confirm or deny.
This question type can be used to prompt the user for a confirmation of a yes-or-no question. If the user just hits enter, the default value will be returned.
Example
>>> import questionary >>> questionary.confirm("Are you amazed?").ask() ? Are you amazed? Yes True
This is just a really basic example, the prompt can be customised using the parameters.
- Parameters:
message (
str
) – Question text.default (
bool
) – Default value will be returned if the user just hits enter.qmark (
str
) – Question prefix displayed in front of the question. By default this is a?
.style (
Optional
[Style
]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.auto_enter (
bool
) – If set to False, the user needs to press the ‘enter’ key to accept their answer. If set to True, a valid input will be accepted without the need to press ‘Enter’.instruction (
Optional
[str
]) – A message describing how to proceed through the confirmation prompt.kwargs (Any) –
- Returns:
Question instance, ready to be prompted (using .ask()).
- Return type:
Select
- questionary.select(choices, default=None, qmark='?', pointer='»', style=None, use_shortcuts=False, use_arrow_keys=True, use_indicator=False, use_jk_keys=True, use_emacs_keys=True, show_selected=False, instruction=None, **kwargs)[source]
A list of items to select one option from.
The user can pick one option and confirm it (if you want to allow the user to select multiple options, use
questionary.checkbox()
instead).Example
>>> import questionary >>> questionary.select( ... "What do you want to do?", ... choices=[ ... "Order a pizza", ... "Make a reservation", ... "Ask for opening hours" ... ]).ask() ? What do you want to do? Order a pizza 'Order a pizza'
This is just a really basic example, the prompt can be customised using the parameters.
- Parameters:
message (
str
) – Question textchoices (
Sequence
[Union
[str
,Choice
,Dict
[str
,Any
]]]) – Items shown in the selection, this can containChoice
or orSeparator
objects or simple items as strings. PassingChoice
objects, allows you to configure the item more (e.g. preselecting it or disabling it).default (
Union
[str
,Choice
,Dict
[str
,Any
],None
]) – A value corresponding to a selectable item in the choices, to initially set the pointer position to.qmark (
str
) – Question prefix displayed in front of the question. By default this is a?
.pointer (
Optional
[str
]) – Pointer symbol in front of the currently highlighted element. By default this is a»
. UseNone
to disable it.instruction (
Optional
[str
]) – A hint on how to navigate the menu. It’s(Use shortcuts)
if onlyuse_shortcuts
is set to True,(Use arrow keys or shortcuts)
ifuse_arrow_keys
&use_shortcuts
are set and(Use arrow keys)
by default.style (
Optional
[Style
]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.use_indicator (
bool
) – Flag to enable the small indicator in front of the list highlighting the current location of the selection cursor.use_shortcuts (
bool
) – Allow the user to select items from the list using shortcuts. The shortcuts will be displayed in front of the list items. Arrow keys, j/k keys and shortcuts are not mutually exclusive.use_arrow_keys (
bool
) – Allow the user to select items from the list using arrow keys. Arrow keys, j/k keys and shortcuts are not mutually exclusive.use_jk_keys (
bool
) – Allow the user to select items from the list using j (down) and k (up) keys. Arrow keys, j/k keys and shortcuts are not mutually exclusive.use_emacs_keys (
bool
) – Allow the user to select items from the list using Ctrl+N (down) and Ctrl+P (up) keys. Arrow keys, j/k keys, emacs keys and shortcuts are not mutually exclusive.show_selected (
bool
) – Display current selection choice at the bottom of list.kwargs (Any) –
- Returns:
Question instance, ready to be prompted (using
.ask()
).- Return type:
Raw Select
- questionary.rawselect(choices, default=None, qmark='?', pointer='»', style=None, **kwargs)[source]
Ask the user to select one item from a list of choices using shortcuts.
The user can only select one option.
Example
>>> import questionary >>> questionary.rawselect( ... "What do you want to do?", ... choices=[ ... "Order a pizza", ... "Make a reservation", ... "Ask for opening hours" ... ]).ask() ? What do you want to do? Order a pizza 'Order a pizza'
This is just a really basic example, the prompt can be customised using the parameters.
- Parameters:
message (
str
) – Question text.choices (
Sequence
[Union
[str
,Choice
,Dict
[str
,Any
]]]) – Items shown in the selection, this can containChoice
or orSeparator
objects or simple items as strings. PassingChoice
objects, allows you to configure the item more (e.g. preselecting it or disabling it).default (
Optional
[str
]) – Default return value (single value).qmark (
str
) – Question prefix displayed in front of the question. By default this is a?
.pointer (
Optional
[str
]) – Pointer symbol in front of the currently highlighted element. By default this is a»
. UseNone
to disable it.style (
Optional
[Style
]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.kwargs (Any) –
- Returns:
Question instance, ready to be prompted (using
.ask()
).- Return type:
Checkbox
- questionary.checkbox(choices, default=None, validate=<function <lambda>>, qmark='?', pointer='»', style=None, initial_choice=None, use_arrow_keys=True, use_jk_keys=True, use_emacs_keys=True, instruction=None, **kwargs)[source]
Ask the user to select from a list of items.
This is a multiselect, the user can choose one, none or many of the items.
Example
>>> import questionary >>> questionary.checkbox( ... 'Select toppings', ... choices=[ ... "Cheese", ... "Tomato", ... "Pineapple", ... ]).ask() ? Select toppings done (2 selections) ['Cheese', 'Pineapple']
This is just a really basic example, the prompt can be customised using the parameters.
- Parameters:
message (
str
) – Question textchoices (
Sequence
[Union
[str
,Choice
,Dict
[str
,Any
]]]) – Items shown in the selection, this can containChoice
or orSeparator
objects or simple items as strings. PassingChoice
objects, allows you to configure the item more (e.g. preselecting it or disabling it).default (
Optional
[str
]) – Default return value (single value). If you want to preselect multiple items, useChoice("foo", checked=True)
instead.validate (
Callable
[[List
[str
]],Union
[bool
,str
]]) –Require the entered value to pass a validation. The value can not be submitted until the validator accepts it (e.g. to check minimum password length).
This should be a function accepting the input and returning a boolean. Alternatively, the return value may be a string (indicating failure), which contains the error message to be displayed.
qmark (
str
) – Question prefix displayed in front of the question. By default this is a?
.pointer (
Optional
[str
]) – Pointer symbol in front of the currently highlighted element. By default this is a»
. UseNone
to disable it.style (
Optional
[Style
]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.initial_choice (
Union
[str
,Choice
,Dict
[str
,Any
],None
]) – A value corresponding to a selectable item in the choices, to initially set the pointer position to.use_arrow_keys (
bool
) – Allow the user to select items from the list using arrow keys.use_jk_keys (
bool
) – Allow the user to select items from the list using j (down) and k (up) keys.use_emacs_keys (
bool
) – Allow the user to select items from the list using Ctrl+N (down) and Ctrl+P (up) keys.instruction (
Optional
[str
]) – A message describing how to navigate the menu.kwargs (Any) –
- Returns:
Question instance, ready to be prompted (using
.ask()
).- Return type:
Autocomplete
- questionary.autocomplete(choices, default='', qmark='?', completer=None, meta_information=None, ignore_case=True, match_middle=True, complete_style=CompleteStyle.COLUMN, validate=None, style=None, **kwargs)[source]
Prompt the user to enter a message with autocomplete help.
Example
>>> import questionary >>> questionary.autocomplete( ... 'Choose ant specie', ... choices=[ ... 'Camponotus pennsylvanicus', ... 'Linepithema humile', ... 'Eciton burchellii', ... "Atta colombica", ... 'Polyergus lucidus', ... 'Polyergus rufescens', ... ]).ask() ? Choose ant specie Atta colombica 'Atta colombica'
This is just a really basic example, the prompt can be customised using the parameters.
- Parameters:
message (
str
) – Question textchoices (
List
[str
]) – Items shown in the selection, this contains items as stringsdefault (
str
) – Default return value (single value).qmark (
str
) – Question prefix displayed in front of the question. By default this is a?
completer (
Optional
[Completer
]) – A prompt_toolkitprompt_toolkit.completion.Completion
implementation. If not set, a questionary completer implementation will be used.meta_information (
Optional
[Dict
[str
,Any
]]) – A dictionary with information/anything about choices.ignore_case (
bool
) – If true autocomplete would ignore case.match_middle (
bool
) – If true autocomplete would search in every string position not only in string begin.complete_style (
CompleteStyle
) – How autocomplete menu would be shown, it could beCOLUMN
MULTI_COLUMN
orREADLINE_LIKE
fromprompt_toolkit.shortcuts.CompleteStyle
.validate (
Any
) –Require the entered value to pass a validation. The value can not be submitted until the validator accepts it (e.g. to check minimum password length).
This can either be a function accepting the input and returning a boolean, or an class reference to a subclass of the prompt toolkit Validator class.
style (
Optional
[Style
]) – A custom color and style for the question parts. You can configure colors as well as font types for different elements.kwargs (Any) –
- Returns:
Question instance, ready to be prompted (using
.ask()
).- Return type:
Printing Formatted Text
- questionary.print(style=None, **kwargs)
Print formatted text.
Sometimes you want to spice up your printed messages a bit,
questionary.print()
is a helper to do just that.Example
>>> import questionary >>> questionary.print("Hello World 🦄", style="bold italic fg:darkred") Hello World 🦄
Press Any Key To Continue
- questionary.press_any_key_to_continue(style=None, **kwargs)[source]
Wait until user presses any key to continue.
Example
>>> import questionary >>> questionary.press_any_key_to_continue().ask() Press any key to continue... ''
- Parameters:
- Returns:
Question instance, ready to be prompted (using
.ask()
).- Return type: