Custom Prompt Engine#

The heart of the extension is the actual prompt engine. It reacts on pressed keys and manages widgets.

Structure#

Each prompt engine has the same base structure:

 1from aprompt import PromptEngine
 2from aprompt.result import Result
 3from readchar import keys as k
 4
 5def my_prompt(arguments) -> PromptEngine[result_type]:
 6    alert = False
 7    while True:
 8        key = yield [
 9            w.Alert() if alert else None,
10            widget1,
11            widget2,
12            ...
13        ]
14        alert = False
15
16        if key == k.ENTER:
17            yield Result(result, display="display")
18        elif ...:
19            ...
20        else:
21            alert = True

Line

Purpose

6

Alerts are used to signal the user that an invalid input has been entered.

7

An infinite loop is required for prompt engines.

8

Yield expressions that receive a value are rarely used in python and may be complicated to understand. Just remember the following term: We receive a key pressed by the user after we send widgets.

9

The Alert widget is a special widget that tells the formatter to notify the user an invalid input got sent. We only do that if alert is set to True. Otherwise we use None. None is allowed to be sent to allow conditional expressions.

16

Match the key for different values.

17

When we are done we wrap the result inside a aprompt.result.Result.

Caution

The prompt engine may resume at this point when a validation fails.

Begin#

from aprompt import PromptEngine
from aprompt.widgets import Alert

def path() -> PromptEngine:
    alert = False
    while True:
      key = yield [
          Alert() if alert else None,
          # TODO
      ]
      alert = False

Our prompt engine should take the following arguments:

  • root

    The path to display at the beginning.

  • allow_creation

    Allows to create directories and files.

  • require_file

    Requires a file to be selected instead of a directory.

  • multiple_files

    Multiple files may be selected.

… WIP …