Use SlackEventAdapter with existing instance of Flask (#27)

* Add the ability for SlackServer to accept existing Flask instance as a param
* Add server tests for passing an existing Flask instance into the adapter
* Updated README with Bring Your Own Flask example
* Add python 3 to test environments
* Add package version info header

Author: Roach

.travis.yml

@@ -1,16 +1,18 @@
 sudo: false
+dist: trusty
 language: python
 python:
   - "2.7"
-env:
-  matrix:
-    - TOX_ENV=py27
-    - TOX_ENV=flake8
-cache: pip
+  - "3.3"
+  - "3.4"
+  - "3.5"
+  - "3.6"
 install:
-  - "travis_retry pip install setuptools --upgrade"
-  - "travis_retry pip install tox"
+  - travis_retry pip install -r requirements.txt
+  - travis_retry pip install flake8
+  - travis_retry pip install -r requirements-dev.txt
 script:
-  - tox -e $TOX_ENV
-after_script:
-  - cat .tox/$TOX_ENV/log/*.log
+  - flake8 slackeventsapi
+  - py.test --cov-report= --cov=slackeventsapi tests
+after_success:
+  - codecov -e $TRAVIS_PYTHON_VERSION

README.rst

@@ -46,7 +46,7 @@ receiving Team Events.
 user has authorized your app.
 
 🤖  Development workflow:
-------------------------------
+===========================
 
 (1) Create a Slack app on https://api.slack.com/apps/
 (2) Add a `bot user` for your app
@@ -57,11 +57,11 @@ user has authorized your app.
 
 **🎉 Once your app has been authorized, you will begin receiving Slack Events**
 
-    ⚠️  We strongly discourage using ngrok for
-    anything but development. It’s not well-suited for production use.
+    ⚠️  Ngrok is a great tool for developing Slack apps, but we don't recommend using ngrok
+    for production apps.
 
 🤖  Usage
----------
+----------
   **⚠️  Keep your app's credentials safe!**
 
   - For development, keep them in virtualenv variables.
@@ -75,34 +75,68 @@ user has authorized your app.
   SLACK_VERIFICATION_TOKEN = os.environ["SLACK_VERIFICATION_TOKEN"]
 
 Create a Slack Event Adapter for receiving actions via the Events API
+-----------------------------------------------------------------------
+**Using the built-in Flask server:**
 
 .. code:: python
 
   from slackeventsapi import SlackEventAdapter
 
-  slack_events_adapter = SlackEventAdapter(SLACK_VERIFICATION_TOKEN, endpoint="/slack_events")
 
-Create an event listener for "reaction_added" events and print the emoji name
+  slack_events_adapter = SlackEventAdapter(SLACK_VERIFICATION_TOKEN, endpoint="/slack_events")
 
-.. code:: python
 
+  # Create an event listener for "reaction_added" events and print the emoji name
   @slack_events_adapter.on("reaction_added")
   def reaction_added(event):
     emoji = event.get("reaction")
     print(emoji)
 
 
-Start the server on port 3000
+  # Start the server on port 3000
+  slack_events_adapter.start(port=3000)
 
-.. code-block:: python
 
-  slack_events_adapter.start(port=3000)
+**Using your existing Flask instance:**
+
+
+.. code:: python
+
+  from flask import Flask
+  from slackeventsapi import SlackEventAdapter
+
+
+  # This `app` represents your existing Flask app
+  app = Flask(__name__)
+
+
+  # An example of one of your Flask app's routes
+  @app.route("/")
+  def hello():
+    return "Hello there!"
+
+
+  # Bind the Events API route to your existing Flask app by passing the server
+  # instance as the last param, or with `server=app`.
+  slack_events_adapter = SlackEventAdapter(SLACK_VERIFICATION_TOKEN, "/slack/events", app)
+
+
+  # Create an event listener for "reaction_added" events and print the emoji name
+  @slack_events_adapter.on("reaction_added")
+  def reaction_added(event):
+    emoji = event.get("reaction")
+    print(emoji)
+
+
+  # Start the server on port 3000
+  if __name__ == "__main__":
+    app.run(port=3000)
 
 For a comprehensive list of available Slack `Events` and more information on
 `Scopes`, see https://api.slack.com/events-api
 
-🤖  Examples
-------------
+🤖  Example event listeners
+-----------------------------
 
 See `example.py`_ for usage examples. This example also utilizes the
 SlackClient Web API client.

requirements-dev.txt

@@ -2,12 +2,10 @@ coveralls==1.1
 ipdb==0.9.3
 ipython==4.1.2
 pdbpp==0.8.3
-pytest>=2.8.2
-pytest-flask>=0.10
-pytest-mock>=1.1
-pytest-cov==2.2.1
-pytest-pythonpath>=0.3
-Sphinx==1.4.4
-sphinx-rtd-theme==0.1.9
-testfixtures==4.9.1
-tox>=1.8.0
+pytest>=3.2.0
+pytest-flask==0.10.0
+pytest-mock>=1.6.3
+pytest-cov==2.5.1
+pytest-pythonpath==0.7.1
+testfixtures==5.3.1
+tox==2.9.1

requirements.txt

@@ -1,5 +1,5 @@
 appdirs==1.4.0
-pyee>=3.0.3
+pyee==5.0.0
 flask==0.12
 packaging==16.8
 pyparsing==2.1.10

slackeventsapi/__init__.py

@@ -5,10 +5,19 @@
 class SlackEventAdapter(EventEmitter):
     # Initialize the Slack event server
     # If no endpoint is provided, default to listening on '/slack/events'
-    def __init__(self, verification_token, endpoint="/slack/events"):
+    def __init__(self, verification_token, endpoint="/slack/events", server=None):
         EventEmitter.__init__(self)
         self.verification_token = verification_token
-        self.server = SlackServer(verification_token, endpoint, self)
+        self.server = SlackServer(verification_token, endpoint, self, server)
 
     def start(self, host='127.0.0.1', port=None, debug=False, **kwargs):
+        """
+        Start the built in webserver, bound to the host and port you'd like.
+        Default host is `127.0.0.1` and port 8080.
+
+        :param host: The host you want to bind the build in webserver to
+        :param port: The port number you want the webserver to run on
+        :param debug: Set to `True` to enable debug level logging
+        :param kwargs: Additional arguments you'd like to pass to Flask
+        """
         self.server.run(host=host, port=port, debug=debug, **kwargs)

slackeventsapi/server.py

@@ -1,13 +1,48 @@
 from flask import Flask, request, make_response
 import json
+import platform
+import sys
+from .version import __version__
 
 
 class SlackServer(Flask):
-    def __init__(self, verification_token, endpoint, emitter):
-        Flask.__init__(self, __name__)
+    def __init__(self, verification_token, endpoint, emitter, server):
         self.verification_token = verification_token
+        self.emitter = emitter
+        self.endpoint = endpoint
+        self.package_info = self.get_package_info()
 
-        @self.route(endpoint, methods=['GET', 'POST'])
+        # If a server is passed in, bind the event handler routes to it,
+        # otherwise create a new Flask instance.
+        if server:
+            if isinstance(server, Flask):
+                self.bind_route(server)
+            else:
+                raise TypeError("Server must be an instance of Flask")
+        else:
+            Flask.__init__(self, __name__)
+            self.bind_route(self)
+
+    def get_package_info(self):
+        client_name = __name__.split('.')[0]
+        client_version = __version__  # Version is returned from version.py
+
+        # Collect the package info, Python version and OS version.
+        package_info = {
+            "client": "{0}/{1}".format(client_name, client_version),
+            "python": "Python/{v.major}.{v.minor}.{v.micro}".format(v=sys.version_info),
+            "system": "{0}/{1}".format(platform.system(), platform.release())
+        }
+
+        # Concatenate and format the user-agent string to be passed into request headers
+        ua_string = []
+        for key, val in package_info.items():
+            ua_string.append(val)
+
+        return " ".join(ua_string)
+
+    def bind_route(self, server):
+        @server.route(self.endpoint, methods=['GET', 'POST'])
         def event():
             # If a GET request is made, return 404.
             if request.method == 'GET':
@@ -25,11 +60,13 @@ def event():
             # Verify the request token
             request_token = event_data.get("token")
             if self.verification_token != request_token:
-                emitter.emit('error', 'invalid verification token')
+                self.emitter.emit('error', 'invalid verification token')
                 return make_response("Request contains invalid Slack verification token", 403)
 
             # Parse the Event payload and emit the event to the event listener
             if "event" in event_data:
                 event_type = event_data["event"]["type"]
-                emitter.emit(event_type, event_data)
-                return make_response("", 200)
+                self.emitter.emit(event_type, event_data)
+                response = make_response("", 200)
+                response.headers['X-Slack-Powered-By'] = self.package_info
+                return response

tests/test_server.py

@@ -1,5 +1,22 @@
 import json
+from flask import Flask
 import pytest
+import sys
+from slackeventsapi import SlackEventAdapter
+from slackeventsapi.version import __version__
+
+
+def test_existing_flask():
+    valid_flask = Flask(__name__)
+    valid_adapter = SlackEventAdapter("vFO9LARnLI7GflLR8tGqHgdy", "/slack/events", valid_flask)
+    assert isinstance(valid_adapter, SlackEventAdapter)
+
+
+def test_server_not_flask():
+    with pytest.raises(TypeError) as e:
+        invalid_flask = "I am not a Flask"
+        SlackEventAdapter("vFO9LARnLI7GflLR8tGqHgdy", "/slack/events", invalid_flask)
+    assert e.value.args[0] == 'Server must be an instance of Flask'
 
 
 def test_event_endpoint_get(client):
@@ -15,13 +32,35 @@ def test_url_challenge(client):
         data=data,
         content_type='application/json')
     assert res.status_code == 200
-    assert res.data == "valid_challenge_token"
+    assert bytes.decode(res.data) == "valid_challenge_token"
+
+
+def test_valid_event_request(client):
+    data = pytest.reaction_event_fixture
+    res = client.post(
+        '/slack/events',
+        data=data,
+        content_type='application/json')
+    assert res.status_code == 200
 
 
-def test_valid_event(client):
+def test_version_header(client):
+    # Verify [package metadata header is set
+    package_info = SlackEventAdapter("token").server.package_info
+
     data = pytest.reaction_event_fixture
     res = client.post(
         '/slack/events',
         data=data,
         content_type='application/json')
+
     assert res.status_code == 200
+    assert res.headers["X-Slack-Powered-By"] == package_info
+
+
+def test_server_start(mocker):
+    # Verify server started with correct params
+    slack_events_adapter = SlackEventAdapter("token")
+    mocker.spy(slack_events_adapter, 'server')
+    slack_events_adapter.start(port=3000)
+    slack_events_adapter.server.run.assert_called_once_with(debug=False, host='127.0.0.1', port=3000)

tox.ini

@@ -1,29 +1,34 @@
 [tox]
+; you probably don't have all of these python versions on your machine. when you invoke tox, you should pick an
+; environment that you have (e.g. `tox -e py27,py36,flake8`).
+; for quality analysis, use `tox -e flake8` or just `flake8 slackeventsapi`
+; to build the docs, use `tox -e docs`
 envlist=
-    py{27},
-    flake8
-skipsdist=true
-
-[flake8]
-max-line-length= 100
-exclude= tests/*
+    py{27,33,34,35,36},
+    flake8,
+    docs
 
 [testenv]
-passenv = TOXENV CI TRAVIS TRAVIS_*
-commands =
-    py.test --cov-report= --cov=slackeventsapi {posargs:tests}
-    codecov -e TOXENV
-
 deps =
     -r{toxinidir}/requirements-dev.txt
     -r{toxinidir}/requirements.txt
     codecov>=1.4.0
-basepython =
-    py27: python2.7
+commands =
+    ; `--cov-report=html:cov_html`: suppress terminal output, html report in `cov_html/`, populate `.coverage/`
+    ; `--cov=slackeventsapi`: name project
+    ; `{posargs:tests}`: tests located in `tests` by default unless otherwise overriden by tox positional args
+    py.test --cov-report=html:cov_html --cov=slackeventsapi {posargs:tests}
+    ; `codecov` will run the `coverage` utility and then upload results in xml format
+    ; `coverage` utility has configuration in `.coveragerc`
+    ;  CI systems use their own build matricies and virtualenvs and don't need tox. therefore tox shouldn't be used
+    ;  to upload coverage to codecov
+    ;  codecov -e TOXENV
+
+# Flake8 Configuration
+[flake8]
+max-line-length = 100
 
 [testenv:flake8]
-basepython=python
-deps=flake8
-commands=
-    flake8 \
-    {toxinidir}/slackeventsapi
+basepython = python
+deps = flake8
+commands = flake8 slackeventsapi