API Reference

class questionary.Choice(title, value=None, disabled=None, checked=False, shortcut_key=True)[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. If this argument is None or unset, then the value of title is used.

  • 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 (Union[str, bool, None]) – 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: Union[str, List[Tuple[str, str]], List[Tuple[str, str, Callable[[Any], None]]], None]

Display 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().

Parameters:

form_fields (Sequence[FormField]) –

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).

Parameters:

application (Application[Any]) –

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 (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.

Parameters:

line (str) –

default_separator: str = '---------------'

The default separator used if none is specified

line: str

The string being used as a separator

class questionary.FormField(key, question)[source]

Represents a question within a form

Parameters:
  • key (str) – The name of the form field.

  • question (Question) – The question to ask in the form field.

key: str

Alias for field number 0

question: Question

Alias for field number 1

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 (Union[Dict[str, Any], 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 (Union[Dict[str, Any], 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