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,12 @@ 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,17 @@ 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)
@@ -188,6 +190,48 @@ def is_private_message_from_another_user(message_dict, current_user_id):
         return current_user_id != message_dict['sender_id']
     return False
 
+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
     #
@@ -207,7 +251,23 @@ 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 handle_message(message):
@@ -228,6 +288,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,