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 ofBaseException
/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 atry-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/testsSee also
The Test API section describes how to use this parameter for tests in detail.
- Raises:
SystemExit – User hit CTRL+C.
aprompt.exceptions.PromptExit – User hit CTRL+D. This is only raised when
cancelable
is set toTrue
.aprompt.exceptions.PromptNeverFinishedError – The prompt has never finished.
aprompt.exceptions.PromptFinishedTooEarlyError – Not all keys from
test_with
were consumed from.
- 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.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, otherwise0
ormaximum
ifmaximmum
is greater than or equal to0
.
- 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.
- Parameters:
choices – Options to choose from.
multiple – Makes selecting multiple options possible.
require –
Note
This parameter only has an effect when
multiple
is set toTrue
.(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 theaprompt.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
isTrue
.The selected option if
multiple
isFalse
.