yera.runtime.handlers.form._prompts

Ask for form fields one at a time in text-based environments.

Symbols

def collect_form_values — Ask for a form's fields and return the answers as a JSON object.
class FormPrompter — Asks single questions in a text-based environment.

collect_form_values

collect_form_values(
    data: FormData,
    prompter: FormPrompter,
) → dict[str, JsonValue]

Ask for a form's fields and return the answers as a JSON object.

On a re-presented form, only fields with errors and fields holding secrets are asked again; every other value is kept as submitted.

Parameters

data
type: FormData

The form request, including any values and errors to re-present.

prompter
type: FormPrompter

Asks each question in the current environment.

Returns

type: dict[str, JsonValue]

The answers keyed by field name, ready to submit as form input.

FormPrompter

Inherits: Protocol

Asks single questions in a text-based environment.

Methods

heading — Introduce a group of related questions.
error — Report a problem found in a rejected submission.
text — Ask for free text, repeating while validation fails.
secret — Ask for text without displaying the entered value.
confirm — Ask a yes-or-no question.
select — Ask the user to choose one value.
checkbox — Ask the user to choose any number of values.

FormPrompter.heading

heading(
    text: str,
) → None

Introduce a group of related questions.

Parameters

text
type: str

Plain-text heading to present.

FormPrompter.error

error(
    text: str,
) → None

Report a problem found in a rejected submission.

Parameters

text
type: str

Plain-text validation message to present.

FormPrompter.text

text(
    message: str,
    default: str,
    validate: Validator | None = None,
) → str

Ask for free text, repeating while validation fails.

Parameters

message
type: str

Plain-text prompt shown to the user.

default
type: str

Value used when the user submits an empty response.

validate
type: Validator | None = None

Optional callback returning a validation message for an unacceptable answer, or None when the answer is valid.

Returns

type: str

The accepted text response.

FormPrompter.secret

secret(
    message: str,
) → str

Ask for text without displaying the entered value.

Parameters

message
type: str

Plain-text prompt shown to the user.

Returns

type: str

The entered secret value.

FormPrompter.confirm

confirm(
    message: str,
    default: bool,
) → bool

Ask a yes-or-no question.

Parameters

message
type: str

Plain-text question shown to the user.

default
type: bool

Answer used when the user accepts the default.

Returns

type: bool

Whether the user answered yes.

FormPrompter.select

select(
    message: str,
    choices: list[str],
    default: str | None,
) → str

Ask the user to choose one value.

Parameters

message
type: str

Plain-text prompt shown to the user.

choices
type: list[str]

Labels available for selection.

default
type: str | None

Choice selected by default, or None for no default.

Returns

type: str

The selected choice label.

FormPrompter.checkbox

checkbox(
    message: str,
    choices: list[str],
    selected: list[str],
) → list[str]

Ask the user to choose any number of values.

Parameters

message
type: str

Plain-text prompt shown to the user.

choices
type: list[str]

Labels available for selection.

selected
type: list[str]

Choices selected by default.

Returns

type: list[str]

The selected choice labels in their presentation order.