Input types

Choose Python annotations and defaults that tuiify can convert into terminal form controls.

Define typed parameters

Annotate each parameter in the function you decorate with @interactive. tuiify uses the annotation to select a control and uses a default value to prepopulate that control.

See type-to-control mapping

flowchart LR
    String[str] --> Text[Text input]
    Integer[int] --> Number[Numeric input]
    Float[float] --> Number
    Boolean[bool] --> Checkbox[Checkbox]
    Literal[Literal choices] --> Select[Select dropdown]

Build a typed form

Create a function using the supported annotations:

from typing import Literal

from tuiify import interactive


@interactive
def create_report(
    title: str,
    retries: int = 3,
    threshold: float = 0.75,
    include_summary: bool = True,
    format: Literal["text", "json"] = "text",
) -> dict:
    """Configure and create a report."""
    return {
        "title": title,
        "retries": retries,
        "threshold": threshold,
        "include_summary": include_summary,
        "format": format,
    }


if __name__ == "__main__":
    print(create_report())

Run the script, complete the form, and press Ctrl+S. For example, entering Weekly status and accepting the defaults displays and prints:

{'title': 'Weekly status', 'retries': 3, 'threshold': 0.75, 'include_summary': True, 'format': 'text'}

Required values and numeric values

Omit a default to make a parameter required. tuiify reports an error if you submit a required field without a value.

For int and float, tuiify converts the submitted text to the annotated numeric type. Invalid numeric input produces an error in the result pane instead of calling your function.

Optional: Use literal choices

Use Literal when users must choose from a fixed set of values:

from typing import Literal

from tuiify import interactive


@interactive
def set_environment(environment: Literal["development", "staging", "production"]) -> str:
    return f"Selected: {environment}"


if __name__ == "__main__":
    print(set_environment())

The form renders environment as a dropdown. Submitting staging produces:

Selected: staging

Review limitations and security before using annotations outside this table. Open the Configure a typed report form recipe to walk through the report example one step at a time.