Options and Data in ItsPrompt

ItsPrompt has a number of ways to display and check options and data.

Option Parameter

The option parameter is always a tuple with the type annotation OptionsList.

Option as a String

Options can be given as a str. In this case, the string is displayed as the option and returned as the selected option, if the user selects it.

Note

In case of expand(), the first character of the str will be used as the key.

Options as a Tuple of OptionWithId

Options can be given as a tuple with the type annotation OptionWithId.

For all prompts excluding expand(), the tuple is structured as follows

The first element is the displayed option
The second element is the id of the option

For the expand() prompt, the tuple is structured as follows:

The first element is the key of the option
The second element is the displayed option
The third element is the id of the option

Separators

Options can be separated using a Separator. A Separator name can be given using the label parameter.

Separators are available in the prompt types:

Note

The separator cannot be selected as an option. It is purely for cosmetic purposes.

Example:

from ItsPrompt.prompt import Prompt
from ItsPrompt.objects.prompts.separator import Separator

ans = Prompt.select(
    'What food would you like?',
    (Separator('The veggies'), 'Salad', Separator('The meaties'), 'Pizza', 'Burger'),
    default='Pizza',
)

Data Parameter

The table() prompt has a data parameter instead of the option parameter. The data parameter has to be one of the following types:

Note

The type pandas.DataFrame is only available if the pandas library is installed.

The data is used as the content of the table. The user may change the fields of the table. The output of the table prompt is of the same type, as the input data is represented, with the user given values.

Note

Currently, all fields are represented as strings and every field is editable by the user. This may be changed in the future.

Data as a TablePromptList

A TablePromptList is a list of list with each cell represented by a str.

Every sub-list represents a column in the table.

data = [
    ["field 1", "field 2"],
    ["field 3", "field 4"]
]

will be rendered:

0	1
field 1	field 3
field 2	field 4

Data as a TablePromptDict

A TablePromptDict is a dict with the keys as the column names and the values as a list of str, where each list represents a column in the table.

data = {
    "column 1": ["field 1", "field 2"],
    "column 2": ["field 3", "field 4"]
}

column 1	column 2
field 1	field 3
field 2	field 4

Data as a DataFrame

A pandas.DataFrame can be used as well. Read more about them in the pandas documentation.

DataFrame(["field 1", "field 2"])

0
field 1
field 2

Note

Currently, the table prompt cannot display styling in the DataFrame fields. All styling tags will be displayed as-is, so a <u>…</u> will not be underlined, but rather displayed as its shown.

Input Prompt Parameters

The input() prompt has many options to check and complete the input. The following parameters are available:

default: The default value of the input. If the user does not enter anything, the default value is returned.
multiline: If set to True, the user can enter multiple lines of text.
show_symbol: Can be set to a str to show this symbol instead of the characters entered by the user. This is useful for password prompts.
validate: A function that validates the input. Read more about this in the Prompt Validation section.
completions: A list of completions that the user can select from. Read more about this in the Prompt Completion section.
completer: A function that returns a list of completions. Read more about this in the Prompt Completion section.

Note

Only the validate, completions, and completer parameters are described here in detail. The other parameters can be found in the input() API documentation.

Prompt Validation

The validate parameter can be used to validate the input. For every character entered by the user, the validate function is called with the current input as a str. The function should return either

a str to show the string as an error message
False to show a default error message
None (or True) to accept the input

# define a validation function
def input_not_empty(input: str) -> str | None:
    if len(input) == 0:
        return 'Address can not be empty!'


# using a function
Prompt.input(
    ...,
    validate=input_not_empty,
    ...,
)

# using lambda
Prompt.input(
    ...,
    validate=lambda x: "test" in x,
    ...,
)

The str given to the function is the current input of the user. It cannot be changed.

If you want to show that the validation succeeded, return None (or nothing, or True). This will not trigger any errors.

If you want to show an error, return a str with the errors text or False. If you return a str, your text will be shown in the toolbar. If you return False, a general error message will be shown. As long as the validation returns a str or False, the user may not submit the input.

Prompt Completion

The completions and completer parameters can be used to give the user a list of completions to choose from.

Note

If you use completions or completer, you are unable to use show_symbol.

Note

completions and completer are mutually exclusive!. You may only use one of them at a time.

There are three ways to give completions to the user:

A list of str (read more about this in the Completions as a List section)
A nested dict (read more about this in the Completions as a Dict section)
A Completer given by prompt_toolkit (read more about this in the Completions as a Completer section)

Completions as a List

input() takes a list[str] to use as simple word completions. Each str in the list is a possible value to complete.

prompt.input(
    ...,
    completions=['Mainstreet 4', 'Fifth way'],
    ...,
)

Completions as a Dict

You can use a dict for nested completions. Each “layer” will be a completion, after the first was accepted. The type annotation for the dict can be found here: CompletionDict.

Example:

completions = {
    '1': {
        '1.1': None,
        '1.2': {
            '1.2.1', '1.2.2'
        }
    },
    '2': {
        '2.1': {'2.1.1'}
    }
}

prompt.input(
    ...,
    completions=completions,
    ...,
)

In this example, the user can select 1 or 2 as the first completion. If the user selects 1, they can select 1.1 or 1.2, then 1.2.1 and so on.

The key of each entry is the completion that will be shown. The key is either None if there are no further completions or a new dict, where the key is the completion and the value is the next “layer”, and so on.

Completions as a Completer

In the background your completions will be mapped to a Completer, provided by prompt_toolkit.

If you need more customization, you can use a Completer given by prompt-toolkit or create your own completer. For more information on this process, read here: Completions in prompt-toolkit.

There are a number of completers available, for example:

PathCompleter
- automatically complete file system paths
ExecutableCompleter
- automatically complete executables in a file system
WordCompleter
- As simple as it can get. Just completes the letters of the word, that are actually present (the FuzzyCompleter which completions uses in background completes based on a probability, and may show matches which are not exact).
…

To add your own completer to an input() field, you can use the completer parameter:

prompt.input(
    ...,
    completer=my_completer,
    ...,
)

Note

completions and completer are mutually exclusive!. You may only use one of them at a time.