Using the form

Run a tuiify form, submit typed values, and read results or errors without leaving the terminal.

Submit a function

1. Call a function decorated with @interactive without arguments.
2. Enter values in the generated controls.
3. Press Ctrl+S to submit.

The form calls your function with the submitted values as keyword arguments. It displays repr() of the returned value in the result pane and returns that same value when the app exits.

flowchart TD
    Input[Enter form values] --> Submit[Press Ctrl+S]
    Submit --> Convert{Can tuiify convert values?}
    Convert -->|No| ConversionError[Show conversion traceback]
    Convert -->|Yes| Run[Call your function]
    Run --> Outcome{Did the function raise an exception?}
    Outcome -->|Yes| FunctionError[Show formatted traceback]
    Outcome -->|No| Result[Show repr of the result]

from tuiify import interactive


@interactive
def calculate_total(unit_price: float, quantity: int) -> float:
    """Calculate the cost for an order."""
    if quantity < 1:
        raise ValueError("quantity must be at least 1")
    return unit_price * quantity


if __name__ == "__main__":
    total = calculate_total()
    print(f"Total: {total:.2f}")

Submitting 19.99 for unit_price and 2 for quantity displays 39.98 in the app. After the app exits, the script prints:

Total: 39.98

Diagnose errors

tuiify catches conversion and function exceptions during submission and renders a formatted traceback in the result pane. Correct the value and submit again.

For example, submitting 0 for quantity in the preceding example produces a traceback containing:

ValueError: quantity must be at least 1

If you enter non-numeric text for an int or float parameter, conversion also fails before your function runs.

Optional: Add function help

Write a docstring on your decorated function to show its text in the form. Use it to explain what the form does and what users should enter.

@interactive
def calculate_total(unit_price: float, quantity: int) -> float:
    """Calculate the cost for an order. Quantity must be at least 1."""
    if quantity < 1:
        raise ValueError("quantity must be at least 1")
    return unit_price * quantity

See limitations and security for function signatures tuiify does not support. Open the Handle submission errors recipe to follow the success and failure paths in the terminal.