Metadata-Version: 2.1
Name: Flask-Slack-Events
Version: 0.0.1
Summary: Slack event subscriptions for Flask
Home-page: https://github.com/longstem/flask-slack-events
Author: mongkok
Author-email: domake.io@gmail.com
License: MIT
Keywords: flask,slack,events
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Framework :: Flask
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: Flask (>=0.8)

Flask Slack Events
==================

|Pypi| |Build Status| |Codecov| |Code Climate|


`Slack event subscriptions <https://api.slack.com/events-api#subscriptions>`_ for `Flask <http://flask.pocoo.org>`_


Installation
------------

Install last stable version from Pypi::

    pip install flask-slack-events


Create a Slack bot user
-----------------------

See the `Slack's documentation <https://api.slack.com/bot-users#getting-started>`_ for further guidance on creating your bot (**step 1**).

Within the *Basic Information* about your application, copy the **Signing Secret** necessary to `verify requests from Slack <https://api.slack.com/docs/verifying-requests-from-slack>`_.

..  image:: https://user-images.githubusercontent.com/5514990/53696736-cfde0e00-3dfc-11e9-9aeb-23d184f8c600.png
    :alt: Signing Secret


Configure your Application
--------------------------

You should create a ``SlackManager`` object within your application:

.. code-block:: python

    slack_manager = SlackManager()


Once the actual application object has been created, you can configure it for *SlackManager* object with::

    slack_manager.init_app(app)

`Configure your application object <http://flask.pocoo.org/docs/1.0/config/#configuration-basics>`_ updating the ``SLACK_SIGNING_SECRET`` key with the value obtained in the previous **step 1**:

.. code-block:: python

    app.config['SLACK_SIGNING_SECRET'] = '<your Signing Secret>'


Configure your Slack Bot
------------------------

Continue with the `Slacks's documentation <https://api.slack.com/bot-users#setup-events-api>`_ to setting up the Events API (**step 2**) and enter the URL to receive the subscriptions joining your host and the relative path ``/slack/events``:

..  image:: https://user-images.githubusercontent.com/5514990/53696747-e5533800-3dfc-11e9-8cef-4fd13d06e6ef.png
    :alt: Enable Event


Finally, install your bot to a workspace (**step 3**).


How it Works
------------

Now in order to subscribe to `Slack Events <https://api.slack.com/events>`_, use the ``SlackManager.on`` decorator:

.. code-block:: python

    @slack_manager.on('app_mention')
    def app_mention(sender, event):
        # Subscribe to only the message events that mention your bot


Dispatch Events Asynchronously
------------------------------

Some event handlers can delay the execution of another, to avoid this you can configure the event dispatcher and call handlers asynchronously:

.. code-block:: python

    @slack_manager.dispatch_event_handler
    def async_event_dispatcher(event, handlers):
        for handler in handlers:
            task(handler)(event)


Subscribe to Signals
--------------------

The following signals are sended internally by *Flask-Slack-Events*:

signals.request_unauthorized
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Sent when the request received is unauthorized

    Receiver: ``f(sender, **extra)``

signals.expired_event
~~~~~~~~~~~~~~~~~~~~~

    Sent when the event has expired according to the value of ``SLACK_EVENT_EXPIRATION_DELTA`` and the HTTP header ``X-Slack-Request-Timestamp`` received

    Receiver: ``f(sender, **extra)``

signals.invalid_signature
~~~~~~~~~~~~~~~~~~~~~~~~~

    Sent when the signature included within the HTTP header ``X-Slack-Signature`` is invalid

    Receiver: ``f(sender, **extra)``


signals.event_received
~~~~~~~~~~~~~~~~~~~~~~

    Sent when an event has been received

    Receiver: ``f(sender, event, **extra)``


SlackManager Handlers
---------------------

The following handlers are used internally by *Flask-Slack-Events*:

SlackManager.unauthorized_handler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Called to handle an unauthorized request

    Handler: ``f()``

    Default: ``SlackManager.unauthorized()``

SlackManager.expired_event_handler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Called to handle an expired event

    Handler: ``f()``

    Default: ``SlackManager.expired_event()``

SlackManager.invalid_signature_handler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Called to handle a request with an invalid signature

    Handler: ``f()``

    Default: ``SlackManager.invalid_signature()``


SlackManager.dispatch_event_handler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Called to dispatch the event to all handlers connected with ``@SlackManager.on(event_type)``

    Handler: ``f(event, handlers)``

    Default: ``SlackManager.dispatch_event(event, handlers)``


Configuration
-------------

The following configuration values are used internally by *Flask-Slack-Events*:

SLACK_SIGNING_SECRET
~~~~~~~~~~~~~~~~~~~~

    Signing Secret to verify whether requests from *Slack* are authentic

    Default: ``''``

SLACK_EVENTS_URL
~~~~~~~~~~~~~~~~

    URL rule that is used to register the *Subscription View*

    Default: ``/slack/events``

SLACK_EVENT_EXPIRATION_DELTA
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Timedelta added to ``time.time()`` to set the expiration time of each event
    If the value is ``None`` then the event never expires

    Default: ``timedelta(seconds=60 * 5)`` (5 minutes)


Marvin the Paranoid Android
---------------------------

`Marvin <https://github.com/longstem/marvin>`_ is a *Flask* layout that includes this package and makes it super easy to development, build and deploy on *AWS Lambda* + *API Gateway*.  


.. |Pypi| image:: https://img.shields.io/pypi/v/flask-slack-events.svg
   :target: https://pypi.python.org/pypi/flask-slack-events
   :alt: Pypi

.. |Build Status| image:: https://travis-ci.org/longstem/flask-slack-events.svg?branch=master
   :target: https://travis-ci.org/longstem/flask-slack-events
   :alt: Build Status

.. |Codecov| image:: https://img.shields.io/codecov/c/github/longstem/flask-slack-events.svg
   :target: https://codecov.io/gh/longstem/flask-slack-events
   :alt: Codecov

.. |Code Climate| image:: https://api.codeclimate.com/v1/badges/c79a185d546f7e34fdd6/maintainability
   :target: https://codeclimate.com/github/longstem/flask-slack-events
   :alt: Codeclimate


