Prompts#

The functions below are listed in the API section as well. This section exists to allow you to quickly view the prompt’s signature and documentation.

Main Prompt Function#

aprompt.prompt(ask: str, prompt_fn: PromptEngine[T], *, validate: None | Callable[[T], bool] | Callable[[T], BaseException | None] = None, formatter: formatters.Formatter | None = None, file: TextIO | None = None, cancelable: bool = False, test_with: Iterator[str] | None = None) T

Displays and formats the prompt, reads keys and handles validation.

Note

The prompt engine will be closed before an exception is raised or a value is returned.

Example

from aprompt import prompt
from aprompt.prompts import confirm

username = prompt(
    "Please enter a username.",
    text(placeholder="funkydog12"),
    validate=lambda name: bool(name)
)
Parameters:
  • ask (str) – The question to ask / The prompt text.

  • prompt_fn (PromptEngine[T]) – The prompt engine.

  • validate (None | Callable[[T], bool] | Callable[[T], BaseException | None]) –

    A callable returning True/False or an instance of BaseException/None depending on the reult.

    If the validation fails, the prompt will continue.

  • formatter (Optional[formatters.Formatter]) – Defaults to aprompt.formatters.simple().

  • file (Optional[TextIO]) – The file to write to. Defaults to standard output.

  • cancelable (bool) –

    If this is set to True, aprompt.exceptions.PromptExit is raised when the user hits CTRL+D. Only use this if you need to perform clean-up code for a single prompt. The program should not terminate so catching the exception with a try-except-block is required.

    If this is set to False (default) nothing happens and CTRL+D is sent to the prompt engine as a key.

    See also

    The Perfrom Clean-Ups section describes how to handle CTRL+C and CTRL+D..

  • test_with (Optional[Iterator[str]]) –

    Optional iterator of strings simulating keys to be pressed.

    See also

    The tests directory in the repository contains tests using this parameter: https://github.com/phoenixr-codes/aprompt/tree/main/tests

    See also

    The Test API section describes how to use this parameter for tests in detail.

Raises:
Return type:

The (unwrapped) result of prompt_fn.

Built-in Prompt Engines#

A collection of prompts to use within the main aprompt.prompt() function.

While the prompts are documented to return something they internally yield the final result. The documented result is actually returned by aprompt.prompt().

aprompt.prompts.confirm(*, default: bool = True) PromptEngine[bool]

Prompts for a boolean value.

_images/prompt-confirm.gif
Parameters:

default (bool) – The default is used when neither yes or no are typed.

Return type:

PromptEngine[bool]

aprompt.prompts.text(*, hide: bool = False, default: str = '', placeholder: str | None = None, validate: Callable[[str], bool] | None = None, double_enter: bool = False) PromptEngine[str]

Prompts a text input.

Parameters:
  • hide (bool) – Hides the entered text from the terminal.

  • default (str) – A string that is returned when no text has been entered.

  • placeholder (Optional[str]) – A string giving the user an idea of what is expected.

  • validate (Optional[Callable[[str], bool]]) – A callable taking the entered character as input and returning a boolean deciding whether to add it to the result. By default any character is accepted.

  • double_enter (bool) – Requires hitting the enter key twice to indicate that the text is done. This is useful for texts that contains newlines.

Return type:

PromptEngine[str]

aprompt.prompts.number(*, minimum: int | None = None, maximum: int | None = None, default: int | None = None) PromptEngine[int]

Prompts for an integer.

Parameters:
  • minimum (Optional[int]) – Optional minimum value. This must be less than or equal to default.

  • maximum (Optional[int]) – Optional maximum value. This must be less than or equal to default.

  • default (Optional[int]) – The number to begin from. Defaults to minimum if specified, otherwise 0 or maximum if maximmum is greater than or equal to 0.

Return type:

PromptEngine[int]

aprompt.prompts.choice(*choices: str, multiple: Literal[True], require: Callable[[int], bool] | int | None = None) PromptEngine[list[str]]
aprompt.prompts.choice(*choices: str, multiple: Literal[False] = False, require: None = None) PromptEngine[str]

Prompts for options.

_images/prompt-choice.gif
Parameters:
  • choices – Options to choose from.

  • multiple – Makes selecting multiple options possible.

  • require

    Note

    This parameter only has an effect when multiple is set to True.

    (int) bool

    A callable taking the amount of selected prompts as an integer as a single argument and returning a boolean whether to pass or deny the resut.

    int

    An integer specifying the amount of options that are required to be selected.

    This parameter can be used as a shorthand for the validate parameter of the aprompt.prompt() function:

    prompt("¿Que?", choice(..., multiple=True), validate=lambda choices: len(choices) == 5)
    
    # same as:
    
    prompt("¿Que?", choice(..., multiple=True, require=5))
    

Returns:

  • A list of the options chosen if multiple is True.

  • The selected option if multiple is False.

aprompt.prompts.sort(*choices: str) PromptEngine[list[str]]
Parameters:

choices (str) –

Return type:

PromptEngine[list[str]]

aprompt.prompts.pin(length: int, *, require_enter: bool = False) PromptEngine[list[int]]
Parameters:
  • length (int) – The length of the PIN code.

  • require_enter (bool) – By default, the prompt finishes when the last digit is entered. Setting this parameter to True will enforce hitting ENTER to finish the prompt.

Return type:

Each digit of the entered PIN code.