bots: Move contrib_bots to api/bots*.

This will make it convenient to include these bots in Zulip API
releases on pypi.

Fix #5009.

bots/yoda/readme.md

@@ -0,0 +1,69 @@
+# Overview
+
+This is the documentation for how to set up and run the yoda bot. (`yoda.py`)
+
+This directory contains library code for running Zulip
+bots that react to messages sent by users.
+
+This bot will allow users to translate a sentence into 'Yoda speak'.
+It looks for messages starting with at-mention of the botname. You will need to have a
+Mashape API key. Please see instructions for getting one below.
+
+## Setup
+
+Before running this bot, make sure to get a Mashape API key.
+Go to this link:
+<https://market.mashape.com/ismaelc/yoda-speak/overview>
+This is the API that powers the `yoda`. You can read more about it
+on this page.
+
+![yoda api overview](assets/yoda-speak-api.png)
+
+Click on the **Sign Up Free** button at the top and create
+an account. Then click on the **Documentation** tab. Scroll down to the
+bottom, and click on the **Test Endpoint** button.
+This will add the Yoda Speak API to your default application. You can
+also add it to a different application if you wish. Now click on the
+**Applications** tab at the top. Select the application that you added
+the Yoda Speak API to. Click on the blue **GET THE KEYS** button.
+
+On the pop-up that comes up, click on the **COPY** button.
+This is your Mashape API key. It is used
+to authenticate. Store it in the `yoda.config` file.
+
+The `yoda.config` file should be located at `~/yoda.config`.
+
+Example input:
+
+    @mention-bot You will learn how to speak like me someday.
+
+If you need help while the bot is running just input `@mention-bot help`.
+
+## Running the bot
+
+Here is an example of running the "yoda" bot from
+inside a Zulip repo:
+
+    cd ~/zulip/api
+    bots_api/run.py bots/yoda/yoda.py --config-file ~/.zuliprc-prod
+
+Once the bot code starts running, you will see a
+message explaining how to use the bot, as well as
+some log messages.  You can use the `--quiet` option
+to suppress some of the informational messages.
+
+The bot code will run continuously until you kill them with
+control-C (or otherwise).
+
+### Configuration
+
+For this document we assume you have some prior experience
+with using the Zulip API, but here is a quick review of
+what a `.zuliprc` files looks like.  You can connect to the
+API as your own human user, or you can go into the Zulip settings
+page to create a user-owned bot.
+
+    [api]
+    email=someuser@example.com
+    key=<your api key>
+    site=https://zulip.somewhere.com

bots/yoda/yoda.py

@@ -0,0 +1,136 @@
+# See readme.md for instructions on running this code.
+
+from __future__ import print_function
+import os
+import logging
+import ssl
+import sys
+try:
+    import requests
+except ImportError as e:
+    logging.error("Dependency missing!!\n{}".format(e))
+    sys.exit(0)
+
+HELP_MESSAGE = '''
+            This bot allows users to translate a sentence into
+            'Yoda speak'.
+            Users should preface messages with '@mention-bot'.
+
+            Before running this, make sure to get a Mashape Api token.
+            Instructions are in the 'readme.md' file.
+            Store it in the 'yoda.config' file.
+            The 'yoda.config' file should be located at '~/yoda.config'.
+            Example input:
+            @mention-bot You will learn how to speak like me someday.
+            '''
+
+
+class ApiKeyError(Exception):
+    '''raise this when there is an error with the Mashape Api Key'''
+
+
+class YodaSpeakHandler(object):
+    '''
+    This bot will allow users to translate a sentence into 'Yoda speak'.
+    It looks for messages starting with '@mention-bot'.
+    '''
+
+    def usage(self):
+        return '''
+            This bot will allow users to translate a sentence into
+            'Yoda speak'.
+            Users should preface messages with '@mention-bot'.
+
+            Before running this, make sure to get a Mashape Api token.
+            Instructions are in the 'readme.md' file.
+            Store it in the 'yoda.config' file.
+            The 'yoda.config' file should be located at '~/yoda.config'.
+            Example input:
+            @mention-bot You will learn how to speak like me someday.
+            '''
+
+    def handle_message(self, message, client, state_handler):
+        handle_input(message, client)
+
+handler_class = YodaSpeakHandler
+
+
+def send_to_yoda_api(sentence, api_key):
+    # function for sending sentence to api
+
+    response = requests.get("https://yoda.p.mashape.com/yoda?sentence=" + sentence,
+                            headers={
+                                "X-Mashape-Key": api_key,
+                                "Accept": "text/plain"
+                            }
+                            )
+
+    if response.status_code == 200:
+        return response.text
+    if response.status_code == 403:
+        raise ApiKeyError
+    else:
+        error_message = response.text['message']
+        logging.error(error_message)
+        error_code = response.status_code
+        error_message = error_message + 'Error code: ' + error_code +\
+            ' Did you follow the instructions in the `readme.md` file?'
+        return error_message
+
+
+def format_input(original_content):
+    # gets rid of whitespace around the edges, so that they aren't a problem in the future
+    message_content = original_content.strip()
+    # replaces all spaces with '+' to be in the format the api requires
+    sentence = message_content.replace(' ', '+')
+    return sentence
+
+
+def handle_input(message, client):
+
+    original_content = message['content']
+    if is_help(original_content):
+        client.send_reply(message, HELP_MESSAGE)
+
+    else:
+        sentence = format_input(original_content)
+        try:
+            reply_message = send_to_yoda_api(sentence, get_api_key())
+
+        except ssl.SSLError or TypeError:
+            reply_message = 'The service is temporarily unavailable, please try again.'
+            logging.error(reply_message)
+
+        except ApiKeyError:
+            reply_message = 'Invalid Api Key. Did you follow the instructions in the ' \
+                            '`readme.md` file?'
+            logging.error(reply_message)
+
+        client.send_reply(message, reply_message)
+
+
+def get_api_key():
+    # function for getting Mashape api key
+    home = os.path.expanduser('~')
+    with open(home + '/yoda.config') as api_key_file:
+        api_key = api_key_file.read().strip()
+    return api_key
+
+
+def send_message(client, message, stream, subject):
+    # function for sending a message
+    client.send_message(dict(
+        type='stream',
+        to=stream,
+        subject=subject,
+        content=message
+    ))
+
+
+def is_help(original_content):
+    # gets rid of whitespace around the edges, so that they aren't a problem in the future
+    message_content = original_content.strip()
+    if message_content == 'help':
+        return True
+    else:
+        return False