Prompt API Reference

This is the API reference for the Prompt class. The Prompt class is the main class of the ItsPrompt package. It is used to create and display prompts to the user.

To use any of the given methods, you must first import the Prompt class from the ItsPrompt package. Here is an example of how to import the Prompt class:

from ItsPrompt.prompt import Prompt
classmethod Prompt.select(question: str, options: tuple[str | tuple[str, str, str | None] | Separator, ...], default: str | None = None, disabled: tuple[str, ...] | None = None, style: PromptStyle | None = None) → str[source]

Ask the user for selecting one of the given options.

This method shows the question alongside the options as a nice list. The user has the ability to use the up, down and enter keys to navigate between the options and select the one that is right.

The options are either a string, which is used as the display value and the id, or a tuple[str, str], where the first string is the display value and the second is the option’s id.

Parameters:

  • question – The question to display

  • options – A list of possible options

  • default – The id of the default option to select (empty or None if the first should be default), defaults to None

  • disabled – A list of ids, which should be disabled by default (empty if None)

  • style – A separate style to style the prompt (empty or None for default style), defaults to None

Raises:

KeyboardInterrupt – When the user presses ctrl-c, KeyboardInterrupt will be raised

Returns:

The id of the selected option

Return type:

str

classmethod Prompt.raw_select(question: str, options: tuple[str | tuple[str, str, str | None] | Separator, ...], default: str | None = None, disabled: tuple[str, ...] | None = None, allow_keyboard: bool = False, style: PromptStyle | None = None) → str[source]

Ask the user for selecting one of the given options.

This method shows the question alongside the options as a nice list. The user needs to type the index of the answer. If allow_keyboard is given, the user may use the keyboard as in the select() method.

The options are either a string, which is used as the display value and the id, or a tuple[str, str], where the first string is the display value and the second is the option’s id.

Parameters:

  • question – The question to display

  • options – A list of possible options

  • default – The id of the default option to select (empty or None if the first should be default), defaults to None

  • disabled – A list of ids, which should be disabled by default (empty if None)

  • allow_keyboard – Whether the user should be able to select the answer with up and down, defaults to False

  • style – A separate style to style the prompt (empty or None for default style), defaults to None

Raises:

KeyboardInterrupt – When the user presses ctrl-c, KeyboardInterrupt will be raised

Returns:

The id of the selected option

Return type:

str

classmethod Prompt.expand(question: str, options: tuple[str | tuple[str, str, str | None] | Separator, ...], default: str | None = None, disabled: tuple[str, ...] | None = None, allow_keyboard: bool = False, style: PromptStyle | None = None) → str[source]

Ask the user for selecting one of the given options.

The user needs to type the key of the option. If the user types h, all options will be shown.

The options are either a string, where s[0] will be the key to select and the string will be used as name and id, or a tuple[str, str, str] where t[0] will be the key, t[1] the name and t[2] the id of the option.

Every key must be a unique ascii character and of length 1, and there may not be a key assigned to h.

Parameters:

  • question – The question to display

  • options – A list of possible options

  • default – The id of the default option to select (empty or None if h should be default), defaults to None

  • disabled – A list of ids, which should be disabled by default (empty if None)

  • allow_keyboard – Whether the user should be able to select the answer with up and down, defaults to False

  • style – A separate style to style the prompt (empty or None for default style), defaults to None

Raises:

KeyboardInterrupt – When the user presses ctrl-c, KeyboardInterrupt will be raised

Returns:

The id of the selected option

Return type:

str

classmethod Prompt.checkbox(question: str, options: tuple[str | tuple[str, str, str | None] | Separator, ...], pointer_at: int | None = None, default_checked: tuple[str, ...] | None = None, disabled: tuple[str, ...] | None = None, min_selections: int = 0, style: PromptStyle | None = None) → list[str][source]

Ask the user for selecting multiple of the given options.

The options will be shown as a nice list. The user may navigate with up and down, select or deselect with space and submit with enter.

The options are either a string, which is used as the display value and the id, or a tuple[str, str], where the first string is the display value and the second is the option’s id.

Parameters:

  • question – The question to display

  • options – A list of possible options

  • pointer_at – A 0-indexed value, where the pointer should start (0 if None), defaults to None

  • default_checked – A list of ids, which should be checked by default (empty if None)

  • disabled – A list of ids, which should be disabled by default (empty if None)

  • min_selections – A minimum amount of options that need to be checked before submitting (prohibits the user of submitting, if not enough are checked; 0 if None)

  • style – A separate style to style the prompt (empty or None for default style), defaults to None

Raises:

KeyboardInterrupt – When the user presses ctrl-c, KeyboardInterrupt will be raised

Returns:

The ids of the selected options

Return type:

list[str]

classmethod Prompt.confirm(question: str, default: bool | None = None, style: PromptStyle | None = None) → bool[source]

Ask the user for confirming or denying your prompt.

The user needs to type “y”, “n” or enter (only if default is given).

If default is True, the prompt will be in the style of (Y/n).

If default is False, the prompt will be in the style of (n/Y).

If default is None (or not given), the prompt will be in the style of (y/n). In this case, the user may not use enter to submit the default, as there is no default given.

Parameters:

  • question (str) – The question to display

  • default (bool | None, optional) – The default answer to select when pressing enter, defaults to None

  • style (PromptStyle | None, optional) – A separate style to style the prompt (empty or None for default style), defaults to None

Raises:

KeyboardInterrupt – When the user presses ctrl-c, KeyboardInterrupt will be raised

Returns:

Whether the user selected “y” or “n”

Return type:

bool

classmethod Prompt.input(question: str, default: str | None = None, multiline: bool = False, show_symbol: str | None = None, validate: Callable[[str], str | bool | None] | None = None, completions: list[str] | dict[str, dict[str, CompletionDict | None] | None] | None = None, completer: Completer | None = None, completion_show_multicolumn: bool = False, style: PromptStyle | None = None) → str[source]

Ask the user for typing an input.

If default is given, it will be returned if enter was pressed and no input was given by the user. If the user writes an input, the default will be overwritten.

If multiline is activated, enter will not submit, but rather create a newline. Use alt+enter to submit.

If show_symbol is given, all chars (except newlines) will be replaced with this character in the interface. The result will still be the input the user typed, it just will not appear in the CLI. This is useful for password inputs.

validate takes a function which receives a str (the current input of the user) and may return None, a str or simply a boolean value.

If the function returns None (or True), the prompt may assume that the input is valid.

If it returns a str, this will be the error shown to the user. If it returns False, the error shown will simply be a general error statement without additional information. The user will not be able to submit the input, if validate returns an error.

completions may be a list of possible completion strings or a nested dictionary where the key is a completion string and the value is a new dict in the same style (more in the README.md).

You can use your own Completer as well (more in the README.md).

completions and completer are mutually exclusive! You may not use both. If you use a completer, you can not use show_symbol!

Parameters:

  • question (str) – The question to display

  • default (str | None, optional) – The default value to fill in, defaults to None

  • multiline (bool, optional) – Whether to allow the user to type multiple lines, defaults to False

  • show_symbol (str | None, optional) – A symbol to show instead of the users input, defaults to None

  • validate (Callable[[str], str | bool | None] | None, optional) – A function to check the users input in real-time, defaults to None

  • completions (list[str] | CompletionDict | None, optional) – The completions to use, defaults to None

  • completer (Completer | None, optional) – A completer to use, defaults to None

  • completion_show_multicolumn (bool, optional) – if True, shows completions as multiple columns, defaults to False

  • style (PromptStyle | None, optional) – A separate style to style the prompt (empty or None for default style), defaults to None

Raises:

KeyboardInterrupt – When the user presses ctrl-c, KeyboardInterrupt will be raised

Returns:

The input of the user

Return type:

str

classmethod Prompt.table(question: str, data: DataFrame | dict[str, list[str]] | list[list[str]], style: PromptStyle | None = None) → DataFrame | dict[str, list[str]] | list[list[str]][source]

Ask the user for filling out the displayed table.

This method shows the question alongside a table, which the user may navigate with the arrow keys. The user can use the up, down and enter keys to navigate between the options and change the text in each cell.

The data is either a pandas.DataFrame, a list or a dict (more in the README.md).

Parameters:

  • question (str) – The question to display

  • data (DataFrame | TablePromptDict | TablePromptList) – The data to display

  • style (PromptStyle | None, optional) – A separate style to style the prompt (empty or None for default style), defaults to None

Raises:

KeyboardInterrupt – When the user presses ctrl-c, KeyboardInterrupt will be raised

Returns:

The id of the selected option

Return type:

DataFrame | TablePromptDict | TablePromptList