Bots: Add metadata scheme for bots.

* Name & (short) description
* Whether to use any default commands (default to enabled):
(about, '' (empty), usage [remove?], help/commands)
* (Optionally) provide a list of user commands, which help/commands uses

Author: neiljp

zulip_bots/zulip_bots/bots/wikipedia/wikipedia.py

@@ -18,6 +18,11 @@ class WikipediaHandler(object):
     kind of external issue tracker as well.
     '''
 
+    META = {'name': 'Wikipedia',
+            'description': 'Searches Wikipedia for a term and returns the top article.',
+            'defaults': False,  # Let bot handle all messages
+    }
+
     def usage(self):
         return '''
             This plugin will allow users to directly search

zulip_bots/zulip_bots/bots/xkcd/xkcd.py

@@ -3,6 +3,8 @@
 import logging
 import requests
 
+from collections import OrderedDict
+
 XKCD_TEMPLATE_URL = 'https://xkcd.com/%s/info.0.json'
 LATEST_XKCD_URL = 'https://xkcd.com/info.0.json'
 
@@ -14,6 +16,16 @@ class XkcdHandler(object):
     commands.
     '''
 
+    META = {'name': 'XKCD',
+            'description': 'Fetches comic strips from https://xkcd.com.',
+            'defaults': True,
+            'commands': OrderedDict([
+                ('latest', "Show the latest comic strip"),
+                ('random', "Show a random comic strip"),
+                ('<comic id>', "Show a comic strip with a specific 'comic id'"),
+            ]) # NOTE: help not listed here, so default command used
+    }
+
     def usage(self):
         return '''
             This plugin allows users to fetch a comic strip provided by

zulip_bots/zulip_bots/lib.py

@@ -18,6 +18,8 @@
 
 from zulip import Client
 
+from collections import OrderedDict
+
 def exit_gracefully(signum, frame):
     # type: (int, Optional[Any]) -> None
     sys.exit(0)
@@ -159,6 +161,46 @@ def state(self, default):
         yield new_state
         self.set_state(new_state)
 
+def setup_default_commands(bot_details, message_handler):
+    def def_about():
+        if bot_details['description'] == "":
+            return "**{}**".format(bot_details['name'])
+        return "**{}**: {}".format(bot_details['name'], bot_details['description'])
+    def def_help():
+        return ("\n".join("**{}** - {}".format(k, v[1])
+                          for k, v in defaults.items() if k) + "\n" +
+                "\n".join("**{}** - {}".format(k, v)
+                          for k, v in bot_details['commands'].items() if k))
+    def def_commands():
+        return "**Commands**: {} {}".format(
+            " ".join(k for k in defaults if k),
+            " ".join(k for k in bot_details['commands'] if k))
+    defaults = OrderedDict([  # Variable definition required for callbacks above
+        ('', (lambda: "Oops. Your message was empty.", "[BLANK MESSAGE NOT SHOWN]")),
+        ('about', (def_about, "The type and use of this bot")),
+        ('usage', ((lambda: message_handler.usage(), "Bot-provided usage text"))),
+        ('help', (lambda: "{}\n{}\n{}".format(def_about(), message_handler.usage(), def_help()),
+                 "This help text")),
+        ('commands', (def_commands, "A short list of supported commands"))
+    ])
+    return defaults
+
+def sync_botdetails_defaultcommands(bot_details, default_commands):
+    # Update default_commands from any changes in bot_details
+    if not bot_details['defaults']:  # Bot class will handle all commands
+        default_commands = {}
+    else:
+        if len(bot_details['commands']) == 0:  # No commands specified, so don't use this feature
+            del default_commands['commands']
+            del default_commands['help']
+        else:
+            for command in bot_details['commands']:  # Bot commands override defaults
+                if command in default_commands:
+                    del default_commands[command]
+    # Sync default_commands changes with bot_details
+    if len(default_commands) == 0:
+        bot_details['defaults'] = False
+
 def run_message_handler_for_bot(lib_module, quiet, config_file, bot_name):
     # type: (Any, bool, str) -> Any
     #
@@ -178,7 +220,22 @@ def run_message_handler_for_bot(lib_module, quiet, config_file, bot_name):
 
     state_handler = StateHandler()
 
+    # Set default bot_details, then override from class, if provided
+    bot_details = { 'name': bot_name.capitalize(),
+                    'description': "",
+                    'commands': {},
+                    'defaults': True,
+    }
+    bot_details.update(getattr(lib_module.handler_class, 'META', {}))
+
+    # Initialise default commands, then override & sync with bot_details
+    default_commands = setup_default_commands(bot_details, message_handler)
+    sync_botdetails_defaultcommands(bot_details, default_commands)
+
     if not quiet:
+        print("Running {} Bot:".format(bot_details['name']))
+        if bot_details['description'] != "":
+            print("\n{}".format(bot_details['description']))
         print(message_handler.usage())
 
     def extract_query_without_mention(message, client):
@@ -220,6 +277,18 @@ def handle_message(message):
                 return
 
         if is_private_message or is_mentioned:
+            # Handle any default_commands first
+            if len(default_commands) > 0:
+                if '' in default_commands and len(message['content']) == 0:
+                    restricted_client.send_reply(message, default_commands[''][0]())
+                    return
+                for command in default_commands:
+                    if command == '':
+                        continue
+                    if message['content'].startswith(command):
+                        restricted_client.send_reply(message, default_commands[command][0]())
+                        return
+            # ...then pass anything else to bot to deal with
             message_handler.handle_message(
                 message=message,
                 bot_handler=restricted_client,