Questionary Documentation

Questionary provides several question types to handle different user input scenarios. Use the following mapping to choose the right method for your use case:

• Free text input: questionary.text()
• Hidden text (passwords): questionary.password()
• File or directory paths (with autocompletion): questionary.path()
• Yes/No questions: questionary.confirm()
• Single item selection (styled list): questionary.select()
• Single item selection (unformatted list): questionary.rawselect()
• Multiple item selection: questionary.checkbox()
• Free text with autocomplete suggestions: questionary.autocomplete()
• Wait for user input: questionary.press_any_key_to_continue()

Additionally, you can use questionary.print() to display formatted text to the terminal.

Questionary provides two ways to handle Ctrl+C (KeyboardInterrupt):

Safe Mode (Captures Interrupts)

In safe mode, Questionary catches the interrupt, displays a message (e.g., "Cancelled by user"), and returns None. Safe methods include:

• questionary.prompt()
• Form.ask()
• Question.ask() (returned by functions like text(), checkbox(), etc.)

Unsafe Mode (Does NOT capture Interrupts)

In unsafe mode, the interrupt is raised to the caller. You must wrap these calls in a try/except KeyboardInterrupt block. Unsafe methods include:

• questionary.unsafe_prompt()
• Form.unsafe_ask()
• Question.unsafe_ask()

Questionary operates on two primary mental models:

1. Single Questions: Individual prompts created via specific type methods (e.g., questionary.text()) that are executed via .ask().
2. Collections of Questions:
   • Forms: Created via questionary.form(), using keyword arguments to define field names and Question objects. This is a programmatic, object-oriented way to build flows.
   • Prompts: Created via questionary.prompt(), using a list of configuration dictionaries. This is a data-driven way to define flows, where each dictionary specifies a type, name, and message.

To contribute to Questionary, follow these steps to configure your local environment:

1. Fork the repository on GitHub.
2. Install Poetry.
3. Run make develop to configure the development environment.
4. Write tests for your changes.
5. Run quality checks using the following commands:
   • Linting: make lint
   • Unit tests: make test
   • Type checks: make types
6. Submit a pull request.

make develop
$ make lint
$ make test
$ make types

Use questionary.form() to ask a collection of questions sequentially. You pass the questions as keyword arguments where the key is the name of the field and the value is a Question instance. The .ask() method returns a dictionary containing the answers, mapped to the keys provided in the form.

import questionary

answers = questionary.form(
    first = questionary.confirm("Would you like the next question?", default=True),
    second = questionary.select("Select item", choices=["item1", "item2", "item3"])
).ask()

print(answers)
# Output format: {'first': True, 'second': 'item2'}

The questionary.prompt() function allows you to ask a collection of questions by passing a list of dictionaries. Each dictionary defines the question's configuration. This is an alternative to questionary.form() when you prefer a data-driven approach rather than using Question instances. The returned answers are a dictionary mapping the name key from each dictionary to the user's response.

import questionary

questions = [
  {
    "type": "confirm",
    "name": "first",
    "message": "Would you like the next question?",
    "default": True,
  },
  {
    "type": "select",
    "name": "second",
    "message": "Select item",
    "choices": ["item1", "item2", "item3"],
  },
]

answers = questionary.prompt(questions)
print(answers)
# Output format: {'first': True, 'second': 'item2'}

To release a new version of Questionary, perform the following steps:

1. Update the version number in both questionary/version.py and pyproject.toml.
2. Add a new section for the release in the changelog.
3. Commit the changes.
4. Tag the commit with the release version number using git tag.

Note: GitHub Actions will automatically build and push the updated library to PyPI once the release is processed.

To create a GIF recording of a command line interaction, use asciinema and asciicast2gif.

1. Install the required tools:
   • macOS: brew install asciinema
   • Global npm: npm install --global asciicast2gif
2. Start recording with asciinema rec.
3. Perform the actions you wish to record.
4. Convert the recording to a GIF using asciicast2gif with the following command structure: asciicast2gif -h <height> -w <width> -s <speed> <recording_file> <output_file>

$ brew install asciinema
$ npm install --global asciicast2gif
$ asciinema rec
$ asciicast2gif -h 7 -w 120 -s 2 <recording> output.gif

Use pip to install the questionary package to start building command line interfaces.

pip install questionary