expand

A compact prompt with the ability to expand and select available choices.

Example

Classic Syntax (PyInquirer)

from InquirerPy import prompt
from InquirerPy.prompts.expand import ExpandChoice
from InquirerPy.separator import Separator


def question1_choice(_):
    return [
        ExpandChoice(key="a", name="Apple", value="Apple"),
        ExpandChoice(key="c", name="Cherry", value="Cherry"),
        ExpandChoice(key="o", name="Orange", value="Orange"),
        ExpandChoice(key="p", name="Peach", value="Peach"),
        ExpandChoice(key="m", name="Melon", value="Melon"),
        ExpandChoice(key="s", name="Strawberry", value="Strawberry"),
        ExpandChoice(key="g", name="Grapes", value="Grapes"),
    ]


def question2_choice(_):
    return [
        ExpandChoice(key="d", name="Delivery", value="dl"),
        ExpandChoice(key="p", name="Pick Up", value="pk"),
        Separator(line=15 * "*"),
        ExpandChoice(key="c", name="Car Park", value="cp"),
        ExpandChoice(key="t", name="Third Party", value="tp"),
    ]


def main():
    questions = [
        {
            "type": "expand",
            "choices": question1_choice,
            "message": "Pick your favourite:",
            "default": "o",
            "cycle": False,
        },
        {
            "type": "expand",
            "choices": question2_choice,
            "message": "Select your preferred method:",
        },
    ]

    result = prompt(questions)


if __name__ == "__main__":
    main()

Alternate Syntax

from InquirerPy import inquirer
from InquirerPy.prompts.expand import ExpandChoice
from InquirerPy.separator import Separator

question1_choice = [
    ExpandChoice(key="a", name="Apple", value="Apple"),
    ExpandChoice(key="c", name="Cherry", value="Cherry"),
    ExpandChoice(key="o", name="Orange", value="Orange"),
    ExpandChoice(key="p", name="Peach", value="Peach"),
    ExpandChoice(key="m", name="Melon", value="Melon"),
    ExpandChoice(key="s", name="Strawberry", value="Strawberry"),
    ExpandChoice(key="g", name="Grapes", value="Grapes"),
]


def question2_choice(_):
    return [
        ExpandChoice(key="d", name="Delivery", value="dl"),
        ExpandChoice(key="p", name="Pick Up", value="pk"),
        Separator(line=15 * "*"),
        ExpandChoice(key="c", name="Car Park", value="cp"),
        ExpandChoice(key="t", name="Third Party", value="tp"),
    ]


def main():
    fruit = inquirer.expand(
        message="Pick your favourite:", choices=question1_choice, default="o"
    ).execute()
    method = inquirer.expand(
        message="Select your preferred method:", choices=question2_choice
    ).execute()


if __name__ == "__main__":
    main()

Choices

See also

choices

Tip

Avoid using character such as h, j and k as the key of choices since they are already taken and used as the default expansion key or navigation key.

Tip

It is recommended to use ExpandChoice to create choices for expand prompt.

However if you prefer dict chocies, in addition to the 2 required keys name and value, an additional key called key is also required. The value from key should be a single char and will be binded to the choice. Pressing the value will jump to the choice.

For this specific prompt, a dedicated class ExpandChoice is created.

class InquirerPy.prompts.expand.ExpandChoice(value, name=None, enabled=False, key=None)

Choice class for ExpandPrompt.

See also

Choice

Parameters

• value (Any) – The value of the choice when user selects this choice.

• name (Optional[str]) – The value that should be presented to the user prior/after selection of the choice. This value is optional, if not provided, it will fallback to the string representation of value.

• enabled (bool) – Indicates if the choice should be pre-selected. This only has effects when the prompt has multiselect enabled.

• key (Optional[str]) – Char to bind to the choice. Pressing this value will jump to the choice, If this value is missing, the first char of the str(value) will be used as the key.

Return type

None

from InquirerPy.prompts.expand import ExpandChoice

choices = [
    ExpandChoice("Apple", key="a"),
    ExpandChoice("Cherry", key="c"),
    ExpandChoice("Orange", key="o"),
    ExpandChoice("Peach", key="p"),
    ExpandChoice("Melon", key="m"),
    ExpandChoice("Strawberry", key="s"),
    ExpandChoice("Grapes", key="g"),
]

Keybindings

See also

keybindings

Hint

In addition to the keybindings mentioned below, keybindings are created for all the key specified for each choice which you can use to jump to the target choce.

{
    "answer": [{"key": "enter"}],   # answer the prompt
    "interrupt": [{"key": "c-c"}],  # raise KeyboardInterrupt
    "skip": [{"key": "c-z"}],   # skip the prompt
}

The following dictionary contains the additional keybindings created by this prompt.

{
    "down": [
        {"key": "down"},
        {"key": "c-n"},   # move down
    ],
    "up": [
        {"key": "up"},
        {"key": "c-p"},   # move up
    ],
    "toggle": [
        {"key": "space"},   # toggle choices
    ],
    "toggle-down": [
        {"key": "c-i"},   # toggle choice and move down (tab)
    ],
    "toggle-up": [
        {"key": "s-tab"},   # toggle choice and move up (shift+tab)
    ],
    "toggle-all": [
        {"key": "alt-r"},   # toggle all choices
        {"key": "c-r"},
    ],
    "toggle-all-true": [
        {"key": "alt-a"},   # toggle all choices true
        {"key": "c-a"}.
    ],
    "toggle-all-false": [],   # toggle all choices false
}

When vi_mode is True, the “up” and “down” navigation key will be changed.

{
    "down": [
        {"key": "down"},
        {"key": "j"},
    ],
    "up": [
        {"key": "up"},
        {"key": "k"},
    ],
}

Multiple Selection

See also

Multiple Selection

Default Value

See also

Default Value

The default parameter for expand prompt can be two types of values:

• shortcut char (str): one of the key assigned to the choice.

• choice value (Any): default value could the value of one of the choices.

Expand and Help

By default, the expand shortcut is bonded to h char and the help message is Help, List all choices..

If you would like to have a different key for expansion or help message, you can change this behavior via expand_help parameter.

The expand_help parameter accepts value that’s an instance of ExpandHelp.

class InquirerPy.prompts.expand.ExpandHelp(key='h', message='Help, list all choices')

Help choice for the ExpandPrompt.

Parameters

• key (str) – The key to bind to toggle the expansion of the prompt.

• message (str) – The help message.

Return type

None

The following example will change the expansion key to o and the help message to Help.

Classic Syntax (PyInquirer)

from InquirerPy import prompt
from InquirerPy.prompts.expand import ExpandHelp

questions = [
    {
        "type": "expand",
        "message": "Select one:",
        "choices": [{"key": "a", "value": "1", "name": "1"}],
        "expand_help": ExpandHelp(key="o", message="Help"),
    }
]

result = prompt(questions=questions)

Alternate Syntax

from InquirerPy import inquirer
from InquirerPy.prompts.expand import ExpandHelp

result = inquirer.expand(
    message="Select one:",
    choices=[{"key": "a", "value": "1", "name": "1"}],
    expand_help=ExpandHelp(key="o", message="Help"),
).execute()

Reference

class InquirerPy.prompts.expand.ExpandPrompt(message, choices, default='', style=None, vi_mode=False, qmark='?', amark='?', pointer=' ', separator=') ', help_msg='Help, list all choices', expand_help=None, expand_pointer='❯ ', instruction='', long_instruction='', transformer=None, filter=None, height=None, max_height=None, multiselect=False, marker='❯', marker_pl=' ', border=False, validate=None, invalid_message='Invalid input', keybindings=None, show_cursor=True, cycle=True, wrap_lines=True, raise_keyboard_interrupt=True, mandatory=True, mandatory_message='Mandatory prompt', session_result=None)

Create a compact prompt with the ability to expand.

A wrapper class around Application.

Contains a list of chocies binded to a shortcut letter. The prompt can be expanded using h key.

Parameters

• message (Union[str, Callable[[InquirerPySessionResult], str]]) – The question to ask the user. Refer to message documentation for more details.

• choices (Union[Callable[[InquirerPySessionResult], Union[List[Any], List[Choice], List[Dict[str, Any]]]], List[Any], List[Choice], List[Dict[str, Any]]]) – List of choices to display and select. Refer to Choices documentation for more details.

• style (Optional[InquirerPy.utils.InquirerPyStyle]) – An InquirerPyStyle instance. Refer to Style documentation for more details.

• vi_mode (bool) – Use vim keybinding for the prompt. Refer to keybindings documentation for more details.

• default (Union[Any, Callable[[InquirerPySessionResult], Any]]) – Set the default value of the prompt. This will be used to determine which choice is highlighted (current selection), The default value should the value of one of the choices. For ExpandPrompt specifically, default value can also be a choice[“key”] which is the shortcut key for the choice. Refer to default documentation for more details.

• separator (str) – Separator symbol. Custom symbol that will be used as a separator between the choice index number and the choices.

• help_msg (str) – This parameter is DEPRECATED. Use expand_help instead.

• expand_help (Optional[InquirerPy.prompts.expand.ExpandHelp]) – The help configuration for the prompt. Must be an instance of ExpandHelp. If this value is None, the default help key will be binded to h and the default help message would be “Help, List all choices.”

• expand_pointer (str) – Pointer symbol before prompt expansion. Custom symbol that will be displayed to indicate the prompt is not expanded.

• qmark (str) – Question mark symbol. Custom symbol that will be displayed infront of the question before its answered.

• amark (str) – Answer mark symbol. Custom symbol that will be displayed infront of the question after its answered.

• pointer (str) – Pointer symbol. Customer symbol that will be used to indicate the current choice selection.

• instruction (str) – Short instruction to display next to the question.

• long_instruction (str) – Long instructions to display at the bottom of the prompt.

• validate (Optional[Union[Callable[[Any], bool], Validator]]) – Add validation to user input. The main use case for this prompt would be when multiselect is True, you can enforce a min/max selection. Refer to Validator documentation for more details.

• invalid_message (str) – Error message to display when user input is invalid. Refer to Validator documentation for more details.

• transformer (Optional[Callable[[Any], Any]]) – A function which performs additional transformation on the value that gets printed to the terminal. Different than filter parameter, this is only visual effect and won’t affect the actual value returned by execute(). Refer to transformer documentation for more details.

• filter (Optional[Callable[[Any], Any]]) – A function which performs additional transformation on the result. This affects the actual value returned by execute(). Refer to filter documentation for more details.

• height (Optional[Union[int, str]]) – Preferred height of the prompt. Refer to height documentation for more details.

• max_height (Optional[Union[int, str]]) – Max height of the prompt. Refer to height documentation for more details.

• multiselect (bool) – Enable multi-selection on choices. You can use validate parameter to control min/max selections. Setting to True will also change the result from a single value to a list of values.

• marker (str) – Marker Symbol. Custom symbol to indicate if a choice is selected. This will take effects when multiselect is True.

• marker_pl (str) – Marker place holder when the choice is not selected. This is empty space by default.

• border (bool) – Create border around the choice window.

• keybindings (Optional[Dict[str, List[Dict[str, Union[str, FilterOrBool, List[str]]]]]]) – Customise the builtin keybindings. Refer to keybindings for more details.

• show_cursor (bool) – Display cursor at the end of the prompt. Set to False to hide the cursor.

• cycle (bool) – Return to top item if hit bottom during navigation or vice versa.

• wrap_lines (bool) – Soft wrap question lines when question exceeds the terminal width.

• raise_keyboard_interrupt (bool) – Raise the KeyboardInterrupt exception when ctrl-c is pressed. If false, the result will be None and the question is skiped.

• mandatory (bool) – Indicate if the prompt is mandatory. If True, then the question cannot be skipped.

• mandatory_message (str) – Error message to show when user attempts to skip mandatory prompt.

• session_result (Optional[Dict[Union[str, int], Optional[Union[str, bool, List[Any]]]]]) – Used internally for Classic Syntax (PyInquirer).

Return type

None

Examples

>>> from InquirerPy import inquirer
>>> result = inquirer.expand(message="Select one:", choices[{"name": "1", "value": "1", "key": "a"}]).execute()
>>> print(result)
"1"