API Reference#

aprompt#

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:

SystemExit – User hit CTRL+C.
aprompt.exceptions.PromptExit – User hit CTRL+D. This is only raised when cancelable is set to True.
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.

aprompt.formatters#

Formatters take aprompt.widgets.Widgets 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:

list[str]

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.confirm(*, default: bool = True) → PromptEngine[bool]#

Prompts for a boolean value.

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.

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.

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#

display: str#

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) –

content: str#

class aprompt.widgets.Answer(content: Any)#

Method generated by attrs for class Answer.

Parameters:: content (Any) –

content: Any#

class aprompt.widgets.Error(content: BaseException)#

Method generated by attrs for class Error.

Parameters:: content (BaseException) –

content: BaseException#

class aprompt.widgets.Navigation(content: dict[str, str])#

Method generated by attrs for class Navigation.

Parameters:: content (dict[str, str]) –

content: dict[str, str]#

class aprompt.widgets.Text(content: str, *, placeholder: str | None, hide: bool)#

Method generated by attrs for class Text.

Parameters:

content (str) –
placeholder (str | None) –
hide (bool) –

content: str#

placeholder: str | None#

hide: bool#

class aprompt.widgets.Option(content: str, *, select: bool | None = None, hover: bool | None = None)#

Method generated by attrs for class Option.

Parameters:

content (str) –
select (bool | None) –
hover (bool | None) –

content: str#

select: bool | None#

hover: bool | None#

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) –

default: bool#

class aprompt.widgets.Integer(content: int)#

Method generated by attrs for class Integer.

Parameters:: content (int) –

content: int#

class aprompt.widgets.Code(content: list[Optional[int]])#

Method generated by attrs for class Code.

Parameters:: content (list[Optional[int]]) –

content: list[Optional[int]]#