Prompt API Reference¶

def confirm(
    message: str,
    default: bool = True,
    style: Style | None = None,
    *,
    input_stream: TextIO | None = None,
    output_stream: TextIO | None = None,
) -> bool | None:
    """Ask a yes/no question.

    Args:
        message: The question to display.
        default: Pre-selected answer (``True`` → Yes).
        style: Optional ``Style`` for visual customisation.
        input_stream: Override for ``sys.stdin`` (useful in tests).
        output_stream: Override for ``sys.stdout`` (useful in tests).

    Returns:
        ``True`` for yes, ``False`` for no, or ``None`` if the user
        cancelled with Ctrl-C.

    Example::

        if confirm("Proceed with installation?"):
            install()
    """
    sty = style or _default_style()
    out = output_stream or sys.stdout
    inp = input_stream or sys.stdin

    hint = "(Y/n)" if default else "(y/N)"
    q_part = sty.apply("question", "? " + message)
    h_part = sty.apply("instruction", hint)
    prompt_str = f"{q_part} {h_part} "

    while True:
        try:
            out.write(prompt_str)
            out.flush()
            line = inp.readline()
            if not line:  # EOF
                return None
            result = _parse_confirm_input(line, default)
            if result is not None:
                answer_text = "Yes" if result else "No"
                out.write(f"{sty.apply('answer', answer_text)}\n")
                out.flush()
                return result
            # Unrecognised → re-prompt
            out.write("  Please answer y or n.\n")
            out.flush()
        except (KeyboardInterrupt, EOFError):
            out.write("\n")
            out.flush()
            return None

def select(
    message: str,
    choices: list[str] | list[dict[str, str]],
    default: str | None = None,
    style: Style | None = None,
    *,
    input_stream: TextIO | None = None,
    output_stream: TextIO | None = None,
) -> str | None:
    """Show a list of choices with arrow-key navigation.

    Args:
        message: The question to display above the list.
        choices: Either plain strings or ``{"name": …, "value": …}`` dicts.
        default: Value to pre-select.  Defaults to the first choice.
        style: Optional ``Style`` for visual customisation.
        input_stream: Override for ``sys.stdin`` (useful in tests).
        output_stream: Override for ``sys.stdout`` (useful in tests).

    Returns:
        The ``value`` of the selected choice, or ``None`` if cancelled.

    Example::

        lang = select("Language:", ["Python", "Rust", "Go"])
    """
    sty = style or _default_style()
    out: TextIO = output_stream or sys.stdout
    norm = _normalise_choices(choices)

    # Determine starting index
    index = 0
    if default is not None:
        for i, c in enumerate(norm):
            if c["value"] == default:
                index = i
                break

    use_tty = (
        input_stream is None
        and output_stream is None
        and _is_tty()
        and (not _IS_WINDOWS or msvcrt is not None)
        and (_IS_WINDOWS or termios is not None)
    )

    if not use_tty:
        return _select_fallback(message, norm, index, sty, input_stream, out)

    return _select_interactive(message, norm, index, sty, out)

def text(
    message: str,
    default: str = "",
    validate: Callable[[str], bool | str] | None = None,
    style: Style | None = None,
    *,
    input_stream: TextIO | None = None,
    output_stream: TextIO | None = None,
) -> str | None:
    """Prompt the user for free-form text input.

    Args:
        message: The question to display.
        default: Default value (used when the user presses Enter without
            typing anything).
        validate: Optional callable that receives the current input string.
            Return ``True`` to accept, or a string to show as an error
            message and re-prompt.
        style: Optional ``Style`` for visual customisation.
        input_stream: Override for ``sys.stdin`` (useful in tests).
        output_stream: Override for ``sys.stdout`` (useful in tests).

    Returns:
        The entered string, or ``None`` if cancelled with Ctrl-C.

    Example::

        name = text("Your name:", validate=lambda s: True if s else "Name required")
    """
    sty = style or _default_style()
    out = output_stream or sys.stdout
    inp = input_stream or sys.stdin

    default_hint = f" ({default})" if default else ""
    q_part = sty.apply("question", "? " + message)
    h_part = sty.apply("instruction", default_hint)
    prompt_str = f"{q_part}{h_part} "

    while True:
        try:
            out.write(prompt_str)
            out.flush()
            line = inp.readline()
            if not line:  # EOF
                return None
            value = line.rstrip("\n").rstrip("\r")
            if not value and default:
                value = default

            if validate is not None:
                result = validate(value)
                if result is True:
                    out.write(f"  {sty.apply('answer', value)}\n")
                    out.flush()
                    return value
                elif isinstance(result, str):
                    out.write(f"  {sty.apply('error', '✗ ' + result)}\n")
                    out.flush()
                    continue
                else:
                    # result is False or falsy but not a string → reject silently
                    out.write(f"  {sty.apply('error', '✗ Invalid input')}\n")
                    out.flush()
                    continue
            else:
                out.write(f"  {sty.apply('answer', value)}\n")
                out.flush()
                return value
        except (KeyboardInterrupt, EOFError):
            out.write("\n")
            out.flush()
            return None