# API Reference

class questionary.Choice(title, value=None, disabled=None, checked=False, shortcut_key=True, description=None)

  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.

    - description (`Optional`[`str`]) – Optional description of the item that can be displayed.

  property auto_shortcut: bool

    Whether to assign a shortcut key to the choice

    Keys are assigned starting with numbers and proceeding through the ASCII alphabet.

  static build(c)

    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

  description: `Optional`[`str`]

    Choice description

  disabled: `Optional`[`str`]

    Whether the choice can be selected

  property shortcut_key: str | bool | None

    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)

  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='\\nCancelled by user\\n')

    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='\\nCancelled by user\\n')

    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)

    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)

    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)

  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='\\nCancelled by user\\n')

    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='\\nCancelled by user\\n')

    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)

    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)

    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)

    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)

  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)

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

  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='\\nCancelled by user\\n', **kwargs)

  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)

  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