API Reference#
aprompt#
- 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
.
aprompt.exceptions#
- exception aprompt.exceptions.PromptExit#
An exception raised when a prompt has been exited.
See also
- args#
- with_traceback()#
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception aprompt.exceptions.PromptFinishedTooEarlyError(message: str | None = None, left_keys: list[str] | None = None)#
An exception raised when not all pre-defined keys were consumed in a prompt.
See also
Method generated by attrs for class PromptFinishedTooEarlyError.
- args#
- with_traceback()#
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception aprompt.exceptions.PromptNeverFinishedError(message: str | None = None)#
An exception raised when there were more keys expected to finish the prompt.
See also
Method generated by attrs for class PromptNeverFinishedError.
- Parameters:
message (str | None) –
- Return type:
None
- args#
- with_traceback()#
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
aprompt.formatters#
Formatters take aprompt.widgets.Widget
s as input and return a
string representing it by using the widget’s data.
- aprompt.formatters.simple(tsize: terminal_size, widgets: list[Optional[aprompt.widgets.Widget]]) list[str] #
- Parameters:
tsize (terminal_size) –
widgets (list[Optional[aprompt.widgets.Widget]]) –
- Return type:
aprompt.prompts#
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
.
aprompt.result#
- class aprompt.result.Result(value: T, *, display: str = _Nothing.NOTHING)#
A class indicating the result of a prompt function. This is used instead of a return value for the case that a post-validation fails.
- Parameters:
value (aprompt.result.T) – The result of the prompt.
display (str) – A string displayed in the terminal represing the result. Defaults to
str(value)
.
Method generated by attrs for class Result.
- value: T#
aprompt.widgets#
- class aprompt.widgets.Widget#
A widget defines an item displayed on the terminal.
- class aprompt.widgets.Alert#
This widget does not display anything but rather indicates that the bell should be activated. This is commonly used when an invalid input is entered.
Method generated by attrs for class Alert.
- class aprompt.widgets.Question(content: str)#
Method generated by attrs for class Question.
- Parameters:
content (str) –
- class aprompt.widgets.Answer(content: Any)#
Method generated by attrs for class Answer.
- Parameters:
content (Any) –
- class aprompt.widgets.Error(content: BaseException)#
Method generated by attrs for class Error.
- Parameters:
content (BaseException) –
- content: BaseException#
- class aprompt.widgets.Text(content: str, *, placeholder: str | None, hide: bool)#
Method generated by attrs for class Text.
- class aprompt.widgets.Option(content: str, *, select: bool | None = None, hover: bool | None = None)#
Method generated by attrs for class Option.
- class aprompt.widgets.Options(content: list[aprompt.widgets.Option])#
Method generated by attrs for class Options.
- Parameters:
content (list[aprompt.widgets.Option]) –
- content: list[aprompt.widgets.Option]#
- class aprompt.widgets.SortableOptions(content: list[aprompt.widgets.Option])#
Method generated by attrs for class SortableOptions.
- Parameters:
content (list[aprompt.widgets.Option]) –
- content: list[aprompt.widgets.Option]#
- class aprompt.widgets.Confirm(default: bool)#
Method generated by attrs for class Confirm.
- Parameters:
default (bool) –