API Reference¶

class questionary.Choice(title, value=None, disabled=None, checked=False, shortcut_key=None)[source]¶

One choice in a select(), rawselect() or checkbox().

Parameters

title (Union[str, List[Tuple[str, str]], List[Tuple[str, str, Callable[[Any], None]]], None]) – Text shown in the selection list.
value (Optional[Any]) – Value returned, when the choice is selected.
disabled (Optional[str]) – If set, the choice can not be selected by the user. The provided text is used to explain, why the selection is disabled.
checked (Optional[bool]) – Preselect this choice when displaying the options.
shortcut_key (Optional[str]) – Key shortcut used to select this item.

static build(c)[source]¶

Create a choice object from different representations.

Parameters: c (Union[str, Choice, Dict[str, Any]]) – Either a str, Choice or dict with name, value, disabled, checked and key properties.
Return type: Choice
Returns: An instance of the Choice object.

checked: Optional[bool]¶: Whether the choice is initially selected

disabled: Optional[str]¶: Whether the choice can be selected

shortcut_key: Optional[str]¶: A shortcut key for the choice

title: Optional[Union[str, List[Tuple[str, str]], List[Tuple[str, str, Callable[[Any], None]]]]]¶: Dispay string for the choice

value: Optional[Any]¶: Value of the choice

class questionary.Form(*form_fields)[source]¶

Multi question prompts. Questions are asked one after another.

All the answers are returned as a dict with one entry per question.

This class should not be invoked directly, instead use form().

ask(patch_stdout=False, kbi_msg='Cancelled by user')[source]¶

Ask the questions synchronously and return user response.

Parameters

patch_stdout (bool) – Ensure that the prompt renders correctly if other threads are printing to stdout.
kbi_msg (str) – The message to be printed on a keyboard interrupt.

Return type

Dict[str, Any]

Returns

The answers from the form.

async ask_async(patch_stdout=False, kbi_msg='Cancelled by user')[source]¶

Ask the questions using asyncio and return user response.

Parameters

patch_stdout (bool) – Ensure that the prompt renders correctly if other threads are printing to stdout.
kbi_msg (str) – The message to be printed on a keyboard interrupt.

Return type

Dict[str, Any]

Returns

The answers from the form.

unsafe_ask(patch_stdout=False)[source]¶

Ask the questions synchronously and return user response.

Does not catch keyboard interrupts.

Parameters: patch_stdout (bool) – Ensure that the prompt renders correctly if other threads are printing to stdout.
Return type: Dict[str, Any]
Returns: The answers from the form.

async unsafe_ask_async(patch_stdout=False)[source]¶

Ask the questions using asyncio and return user response.

Does not catch keyboard interrupts.

Parameters: patch_stdout (bool) – Ensure that the prompt renders correctly if other threads are printing to stdout.
Return type: Dict[str, Any]
Returns: The answers from the form.

class questionary.Question(application)[source]¶

A question to be prompted.

This is an internal class. Questions should be created using the predefined questions (e.g. text or password).

ask(patch_stdout=False, kbi_msg='Cancelled by user')[source]¶

Ask the question synchronously and return user response.

Parameters

patch_stdout (bool) – Ensure that the prompt renders correctly if other threads are printing to stdout.
kbi_msg (str) – The message to be printed on a keyboard interrupt.

Returns

The answer from the question.

Return type

Any

async ask_async(patch_stdout=False, kbi_msg='Cancelled by user')[source]¶

Ask the question using asyncio and return user response.

Parameters

patch_stdout (bool) – Ensure that the prompt renders correctly if other threads are printing to stdout.
kbi_msg (str) – The message to be printed on a keyboard interrupt.

Returns

The answer from the question.

Return type

Any

skip_if(condition, default=None)[source]¶

Skip the question if flag is set and return the default instead.

Parameters

condition (bool) – A conditional boolean value.
default (Optional[Any]) – The default value to return.

Returns

self.

Return type

Question

unsafe_ask(patch_stdout=False)[source]¶

Ask the question synchronously and return user response.

Does not catch keyboard interrupts.

Parameters: patch_stdout (bool) – Ensure that the prompt renders correctly if other threads are printing to stdout.
Returns: The answer from the question.
Return type: Any

async unsafe_ask_async(patch_stdout=False)[source]¶

Ask the question using asyncio and return user response.

Does not catch keyboard interrupts.

Parameters: patch_stdout (bool) – Ensure that the prompt renders correctly if other threads are printing to stdout.
Returns: The answer from the question.
Return type: Any

class questionary.Separator(line=None)[source]¶

Used to space/separate choices group.

default_separator: str = '---------------'¶: The default seperator used if none is specified

line: str¶: The string being used as a seperator

questionary.form()[source]¶

Create a form with multiple questions.

The parameter name of a question will be the key for the answer in the returned dict.

Parameters: kwargs (Question) – Questions to ask in the form.
Return type: Form

questionary.prompt(answers=None, patch_stdout=False, true_color=False, kbi_msg='Cancelled by user', **kwargs)[source]¶

Prompt the user for input on all the questions.

Catches keyboard interrupts and prints a message.

See unsafe_prompt() for possible question configurations.

Parameters

questions (Iterable[Mapping[str, Any]]) –
A list of question configs representing questions to ask. A question config may have the following options:
- type - The type of question.
- name - An ID for the question (to identify it in the answers dict).
- when - Callable to conditionally show the question. This function takes a dict representing the current answers.
- filter - Function that the answer is passed to. The return value of this function is saved as the answer.
Additional options correspond to the parameter names for particular question types.
answers (Optional[Mapping[str, Any]]) – Default answers.
patch_stdout (bool) – Ensure that the prompt renders correctly if other threads are printing to stdout.
kbi_msg (str) – The message to be printed on a keyboard interrupt.
true_color (bool) – Use true color output.
color_depth – Color depth to use. If true_color is set to true then this value is ignored.
type – Default type value to use in question config.
filter – Default filter value to use in question config.
name – Default name value to use in question config.
when – Default when value to use in question config.
default – Default default value to use in question config.
kwargs (Any) – Additional options passed to every question.

Return type

Dict[str, Any]

Returns

Dictionary of question answers.

questionary.unsafe_prompt(answers=None, patch_stdout=False, true_color=False, **kwargs)[source]¶

Prompt the user for input on all the questions.

Won’t catch keyboard interrupts.

Parameters

questions (Iterable[Mapping[str, Any]]) –
A list of question configs representing questions to ask. A question config may have the following options:
- type - The type of question.
- name - An ID for the question (to identify it in the answers dict).
- when - Callable to conditionally show the question. This function takes a dict representing the current answers.
- filter - Function that the answer is passed to. The return value of this function is saved as the answer.
Additional options correspond to the parameter names for particular question types.
answers (Optional[Mapping[str, Any]]) – Default answers.
patch_stdout (bool) – Ensure that the prompt renders correctly if other threads are printing to stdout.
true_color (bool) – Use true color output.
color_depth – Color depth to use. If true_color is set to true then this value is ignored.
type – Default type value to use in question config.
filter – Default filter value to use in question config.
name – Default name value to use in question config.
when – Default when value to use in question config.
default – Default default value to use in question config.
kwargs (Any) – Additional options passed to every question.

Return type

Dict[str, Any]

Returns

Dictionary of question answers.

Raises

KeyboardInterrupt – raised on keyboard interrupt