tmbo/questionary

Purpose and public entry points

Questionary is a Python library for interactive terminal prompts, built on prompt_toolkit. Consumers import questionary and construct a prompt such as text, select, or checkbox, then execute it with .ask() (sync) or async variants. The public facade and exported API are centered in questionary/__init__.py; generic prompt creation is also exposed through questionary/prompt.py.

Prompt construction layer

Each input modality is a dedicated factory/module that configures prompt-toolkit widgets, key bindings, validation, defaults, styling, and result transformation:

• Free-form inputs: questionary/prompts/text.py, questionary/prompts/password.py, questionary/prompts/path.py

• Single-choice inputs: questionary/prompts/select.py, questionary/prompts/rawselect.py, questionary/prompts/autocomplete.py

• Multi-choice and boolean flow: questionary/prompts/checkbox.py, questionary/prompts/confirm.py

• Utility interaction: questionary/prompts/press_any_key_to_continue.py

These factories return the shared question abstraction rather than immediately reading stdin.

Question execution boundary

questionary/question.py is the central lifecycle wrapper around a configured prompt-toolkit application. It owns execution semantics—interactive asking, asynchronous execution, handling interruption/cancellation, and returning a typed answer or a configured fallback. This isolates application-specific terminal behavior from prompt definitions and makes all prompt kinds present a uniform .ask() interface.

Shared prompt model and reusable behavior

questionary/prompts/common.py supplies cross-cutting choice/navigation/rendering behavior used by selection-style prompts. questionary/constants.py centralizes interaction constants, while questionary/styles.py establishes the style/theme boundary between library behavior and terminal presentation. questionary/utils.py contains shared transformations and compatibility-oriented support used across construction and execution.

Declarative multi-question workflows

questionary/form.py provides the higher-level form abstraction: a named collection of questions can be asked as a unit and returned as structured answers. questionary/prompt.py supports declarative question specifications and is the primary bridge from data-driven workflows into individual prompt factories. This is the main orchestration layer above a single Question.

Input/output and runtime dependencies

The runtime is a local Python CLI process; there is no server, database, or remote service in the library’s execution path. Terminal rendering, input events, completion, and async-compatible prompt execution are delegated to prompt_toolkit. User code supplies messages, choices, validators, callbacks, defaults, and styles; Questionary translates these into terminal applications and returns selected or entered Python values.

Packaging, documentation, and validation

Python package metadata and dependencies are defined in pyproject.toml; typed-package intent is marked by questionary/py.typed. Usage examples demonstrate the public API and workflow composition in examples/advanced_workflow.py and examples/readme.py. ReadTheDocs/Sphinx documentation is rooted at docs/index.rst, and CI is configured in .github/workflows/continuous-integration.yml.