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
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 realy 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.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 realy 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.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, style=None, only_directories=False, file_filter=None, complete_style=<CompleteStyle.MULTI_COLUMN: '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 realy basic example, the prompt can be customised 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
.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.only_directories (
bool
) – Only show directories in auto completionfile_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, **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 realy 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’.kwargs (Any) –
- Returns
Question instance, ready to be prompted (using .ask()).
- Return type
Select¶
-
questionary.
select
(choices, default=None, qmark='?', style=None, use_shortcuts=False, use_arrow_keys=True, use_indicator=False, use_pointer=True, 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 realy 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?
.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.use_arrow_keys (
bool
) – Allow usage of arrow keys to select item.use_pointer (
bool
) – Flag to enable the pointer in front of the currently highlighted element.kwargs (Any) –
- Returns
Question instance, ready to be prompted (using
.ask()
).- Return type
Raw Select¶
-
questionary.
rawselect
(choices, default=None, qmark='?', 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 realy 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?
.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='?', style=None, use_pointer=True, initial_choice=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 realy 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?
.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_pointer (
bool
) – Flag to enable the pointer in front of the currently highlighted element.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.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: '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 realy 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
.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 🦄
- Parameters
text (
str
) – Text to be printed.style (
Optional
[str
]) – Style used for printing. The style argument uses the prompt toolkit style strings.kwargs (Any) –
- Return type