# tmbo/questionary architecture

> Architecture diagram of the GitHub repository tmbo/questionary, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tmbo/questionary
- Repository: https://github.com/tmbo/questionary

## Overview

#### 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`.

Main entry points: [`questionary/__init__.py`](https://github.com/tmbo/questionary/blob/master/questionary/__init__.py) (questionary API), [`questionary/question.py`](https://github.com/tmbo/questionary/blob/master/questionary/question.py) (Question), [`questionary/prompt.py`](https://github.com/tmbo/questionary/blob/master/questionary/prompt.py) (Declarative prompt), [`questionary/prompts/select.py`](https://github.com/tmbo/questionary/blob/master/questionary/prompts/select.py) (Select, rawselect & autocomplete)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API & workflows"]
  node_package_api["questionary API<br/>public facade<br/>[__init__.py]"]
  node_prompt["Declarative prompt<br/>workflow bridge<br/>[prompt.py]"]
  node_form["Form<br/>multi-question workflow<br/>[form.py]"]
end

subgraph group_factories["Prompt factories"]
  node_text_inputs["Text, password &amp; path<br/>input factories<br/>[text.py]"]
  node_single_choice["Select, rawselect &amp; autocomplete<br/>choice factories<br/>[select.py]"]
  node_multi_boolean["Checkbox &amp; confirm<br/>choice factories<br/>[checkbox.py]"]
  node_continue_prompt["Continue prompt<br/>utility factory"]
end

subgraph group_runtime["Execution &amp; shared behavior"]
  node_question["Question<br/>execution wrapper<br/>[question.py]"]
  node_prompt_common["Prompt common<br/>shared selection model<br/>[common.py]"]
  node_styles["Styles<br/>presentation boundary<br/>[styles.py]"]
  node_shared_support["Constants &amp; utilities<br/>shared support<br/>[constants.py]"]
end

subgraph group_external["Terminal runtime"]
  node_prompt_toolkit{{"prompt_toolkit<br/>terminal framework"}}
  node_user_code["Consumer application<br/>library consumer"]
  node_terminal(("Local terminal<br/>interactive I/O"))
end

node_package_metadata["Package metadata<br/>distribution config<br/>[pyproject.toml]"]
node_examples["Usage examples<br/>documentation examples"]
node_docs["Sphinx documentation<br/>[index.rst]"]

node_user_code -->|"imports and calls"| node_package_api
node_package_api -->|"exports"| node_prompt
node_package_api -->|"exports"| node_form
node_package_api -->|"exports factories"| node_text_inputs
node_package_api -->|"exports factories"| node_single_choice
node_package_api -->|"exports factories"| node_multi_boolean
node_prompt -->|"dispatches specifications"| node_text_inputs
node_prompt -->|"dispatches specifications"| node_single_choice
node_prompt -->|"dispatches specifications"| node_multi_boolean
node_form -->|"asks collected questions"| node_question
node_text_inputs -->|"creates"| node_question
node_single_choice -->|"creates"| node_question
node_multi_boolean -->|"creates"| node_question
node_continue_prompt -->|"creates"| node_question
node_single_choice -->|"uses choice behavior"| node_prompt_common
node_multi_boolean -->|"uses choice behavior"| node_prompt_common
node_question -->|"runs application"| node_prompt_toolkit
node_styles -->|"configures presentation"| node_prompt_toolkit
node_prompt_toolkit -->|"renders and reads events"| node_terminal
node_question -->|"returns answer or fallback"| node_user_code
node_package_metadata -.->|"declares dependency"| node_prompt_toolkit
node_examples -.->|"demonstrates"| node_package_api
node_docs -.->|"documents"| node_package_api

click node_package_api "https://github.com/tmbo/questionary/blob/master/questionary/__init__.py"
click node_prompt "https://github.com/tmbo/questionary/blob/master/questionary/prompt.py"
click node_form "https://github.com/tmbo/questionary/blob/master/questionary/form.py"
click node_text_inputs "https://github.com/tmbo/questionary/blob/master/questionary/prompts/text.py"
click node_single_choice "https://github.com/tmbo/questionary/blob/master/questionary/prompts/select.py"
click node_multi_boolean "https://github.com/tmbo/questionary/blob/master/questionary/prompts/checkbox.py"
click node_continue_prompt "https://github.com/tmbo/questionary/blob/master/questionary/prompts/press_any_key_to_continue.py"
click node_question "https://github.com/tmbo/questionary/blob/master/questionary/question.py"
click node_prompt_common "https://github.com/tmbo/questionary/blob/master/questionary/prompts/common.py"
click node_styles "https://github.com/tmbo/questionary/blob/master/questionary/styles.py"
click node_shared_support "https://github.com/tmbo/questionary/blob/master/questionary/constants.py"
click node_package_metadata "https://github.com/tmbo/questionary/blob/master/pyproject.toml"
click node_examples "https://github.com/tmbo/questionary/blob/master/examples/advanced_workflow.py"
click node_docs "https://github.com/tmbo/questionary/blob/master/docs/index.rst"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package_api,node_prompt,node_form toneBlue
class node_text_inputs,node_single_choice,node_multi_boolean,node_continue_prompt toneAmber
class node_question,node_prompt_common,node_styles,node_shared_support toneMint
class node_prompt_toolkit,node_user_code,node_terminal toneRose
class node_package_metadata,node_examples,node_docs toneNeutral
```

## Components

### Public API & workflows

- [questionary API](https://github.com/tmbo/questionary/blob/master/questionary/__init__.py): public facade · Exports prompt factories and workflow APIs. · `questionary/__init__.py`
- [Declarative prompt](https://github.com/tmbo/questionary/blob/master/questionary/prompt.py): workflow bridge · Maps data-driven specifications to prompt factories. · `questionary/prompt.py`
- [Form](https://github.com/tmbo/questionary/blob/master/questionary/form.py): multi-question workflow · Asks named questions and returns structured answers. · `questionary/form.py`

### Prompt factories

- [Text, password & path](https://github.com/tmbo/questionary/blob/master/questionary/prompts/text.py): input factories · `questionary/prompts/text.py`
- [Select, rawselect & autocomplete](https://github.com/tmbo/questionary/blob/master/questionary/prompts/select.py): choice factories · `questionary/prompts/select.py`
- [Checkbox & confirm](https://github.com/tmbo/questionary/blob/master/questionary/prompts/checkbox.py): choice factories · `questionary/prompts/checkbox.py`
- [Continue prompt](https://github.com/tmbo/questionary/blob/master/questionary/prompts/press_any_key_to_continue.py): utility factory · `questionary/prompts/press_any_key_to_continue.py`

### Execution & shared behavior

- [Question](https://github.com/tmbo/questionary/blob/master/questionary/question.py): execution wrapper · Provides uniform sync and async ask lifecycle with cancellation handling. · `questionary/question.py`
- [Prompt common](https://github.com/tmbo/questionary/blob/master/questionary/prompts/common.py): shared selection model · Provides choice, navigation, and rendering behavior. · `questionary/prompts/common.py`
- [Styles](https://github.com/tmbo/questionary/blob/master/questionary/styles.py): presentation boundary · `questionary/styles.py`
- [Constants & utilities](https://github.com/tmbo/questionary/blob/master/questionary/constants.py): shared support · `questionary/constants.py`

### Terminal runtime

- **prompt_toolkit**: terminal framework · Renders terminal UI, processes input, completion, and async execution.
- **Consumer application**: library consumer · Supplies values, validators, callbacks, and styles; receives Python answers.
- **Local terminal**: interactive I/O

### Other components

- [Package metadata](https://github.com/tmbo/questionary/blob/master/pyproject.toml): distribution config · Defines Python package metadata and dependencies. · `pyproject.toml`
- [Usage examples](https://github.com/tmbo/questionary/blob/master/examples/advanced_workflow.py): documentation examples · `examples/advanced_workflow.py`
- [Sphinx documentation](https://github.com/tmbo/questionary/blob/master/docs/index.rst): documentation · `docs/index.rst`

## Connections

- Consumer application → questionary API: imports and calls
- questionary API → Declarative prompt: exports
- questionary API → Form: exports
- questionary API → Text, password & path: exports factories
- questionary API → Select, rawselect & autocomplete: exports factories
- questionary API → Checkbox & confirm: exports factories
- Declarative prompt → Text, password & path: dispatches specifications
- Declarative prompt → Select, rawselect & autocomplete: dispatches specifications
- Declarative prompt → Checkbox & confirm: dispatches specifications
- Form → Question: asks collected questions
- Text, password & path → Question: creates
- Select, rawselect & autocomplete → Question: creates
- Checkbox & confirm → Question: creates
- Continue prompt → Question: creates
- Select, rawselect & autocomplete → Prompt common: uses choice behavior
- Checkbox & confirm → Prompt common: uses choice behavior
- Question → prompt_toolkit: runs application
- Styles → prompt_toolkit: configures presentation
- prompt_toolkit → Local terminal: renders and reads events
- Question → Consumer application: returns answer or fallback
- Package metadata → prompt_toolkit: declares dependency
- Usage examples → questionary API: demonstrates
- Sphinx documentation → questionary API: documents