shellbot.machines.menu module

class shellbot.machines.menu.Menu(bot=None, states=None, transitions=None, initial=None, during=None, on_enter=None, on_exit=None, **kwargs)

Bases: shellbot.machines.input.Input

Selects among multiple options

This implements a state machine that can capture a choice from chat participants. It can ask a question, wait for some input, check provided data and provide guidance when needed.

Example:

machine = Menu(bot=bot,
               question="What would you prefer?",
               options=["Some starter and then main course",
                        "Main course and sweety dessert"])
machine.start()
...

if machine.get('answer') == 1:
    prepare_appetizer()
    prepare_main_course()

if machine.get('answer') == 2:
    prepare_main_course()
    prepare_some_cake()

In normal operation mode, the machine asks a question in the chat space, then listen for an answer, captures it, and stops.

When no adequate answer is provided, the machine will provide guidance in the chat space after some delay, and ask for a retry. Multiple retries can take place, until correct input is provided, or the machine is timed out.

The machine can also time out after a (possibly) long duration, and send a message in the chat space when giving up.

If correct input is mandatory, no time out will take place and the machine will really need a correct answer to stop.

Data that has been captured can be read from the machine itself. For example:

value = machine.get('answer')

If the machine is given a key, this is used for feeding the bot store. For example:

machine.build(key='my_field', ...)
...

value = bot.recall('input')['my_field']

The most straightforward way to process captured data in real-time is to subclass Menu, like in the following example:

class MyMenu(Menu):

    def on_input(self, value):
        do_something_with(value)

machine = MyMenu(...)
machine.start()

RETRY_MESSAGE = u'Invalid input, please enter your choice as a number'

ask()

Asks which menu option to select

If a bare question is provided, then text is added to list all available options.

If a rich question is provided, then we assume that it also contains a representation of menu options and displays it ‘as-is’.

filter(text)

Filters data from user input

Parameters:text (str) – Text coming from the chat space Returns:Text of the selected option, or None

on_init(options=[], **kwargs)

Selects among multiple options

Parameters:

• question (str) – Message to ask for some input (mandatory)
• options (list of str) – The options of the menu
• on_answer (str) – Message on successful data capture
• on_answer_content (str in Markdown or HTML format) – Rich message on successful data capture
• on_answer_file (str) – File to be uploaded on successful data capture
• on_retry (str) – Message to provide guidance and ask for retry
• on_retry_content (str in Markdown or HTML format) – Rich message on retry
• on_retry_file (str) – File to be uploaded on retry
• retry_delay (int) – Repeat the on_retry message after this delay in seconds
• on_cancel (str) – Message on time out
• on_cancel_content (str in Markdown or HTML format) – Rich message on time out
• on_cancel_file (str) – File to be uploaded on time out
• is_mandatory (boolean) – If the bot will insist and never give up
• cancel_delay (int) – Give up on this input after this delay in seconds
• key (str) – The label associated with data captured in bot store