Clean up for packaging and bug fix

Author: Jeff Ammons

.gitignore

@@ -11,3 +11,8 @@ env
 tests/.cache
 .coverage
 .cache
+
+# Packaging related
+dist/
+rtmbot.egg-info/
+MANIFEST

MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include CHANGELOG.md
+include README.md

README.md

@@ -24,30 +24,29 @@ Installation
 -----------
 
 1. Create your project
+
         mkdir myproject
         cd myproject
 
 2. Install rtmbot (ideally into a virtualenv https://virtualenv.readthedocs.io/en/latest/)
 
         pip install rtmbot
 
-3. Create conf file and configure rtmbot (https://api.slack.com/bot-users)
-
-        vi rtmbot.conf
+3. Create and rtmbot.conf file and configure rtmbot (https://api.slack.com/bot-users)
 
-            DEBUG: True # make this False in production
-            SLACK_TOKEN: "xoxb-11111111111-222222222222222"
-            ACTIVE_PLUGINS:
-                - plugins.repeat.RepeatPlugin
-                - plugins.test.TestPlugin
+        # Add the following to rtmbot.conf
+        DEBUG: True # make this False in production
+        SLACK_TOKEN: "xoxb-11111111111-222222222222222"
+        ACTIVE_PLUGINS:
+            - plugins.repeat.RepeatPlugin
 
 ```DEBUG``` will adjust logging verbosity and cause the runner to exit on exceptions, generally making dubugging more pleasant.
 
 ```SLACK_TOKEN``` is needed to authenticate with your Slack team. More info at https://api.slack.com/web#authentication
 
 ```ACTIVE_PLUGINS``` RTMBot will attempt to import any Plugin specified in `ACTIVE_PLUGINS` (relative to your python path) and instantiate them as plugins. These specified classes should inherit from the core Plugin class.
 
-For example, if your python path includes '/path/to/myproject' and you include `plugins.repeat.RepeatPlugin` in ACTIVE_PLUGINS, it will find the RepeatPlugin class within /path/to/myproject/plugins/repeat.py and instantiate it then attach it to your running RTMBot.
+For example, if your python path includes '/path/to/myproject' and you include `plugins.repeat.RepeatPlugin` in ACTIVE_PLUGINS, it will find the RepeatPlugin class within /path/to/myproject/plugins/repeat.py and instantiate it, then attach it to your running RTMBot.
 
 A Word on Structure
 -------
@@ -64,13 +63,16 @@ RtmBot
 
 Add Plugins
 -------
+Plugins can live within any python module, but we recommend just putting them in ./plugins. (Don't forget to add an __init__.py file to your directory to make it a module -- use `touch __init__.py` within your plugin directory to create one)
 
 To add a plugin, create a file within your plugin directory (./plugins is a good place for it).
 
+    mkdir plugins
+    touch plugins/__init__.py
     cd plugins
     vi myplugin.py
 
-Add your plugin content into this file. Here's an example that will just print all of the requests it receives. See below for more information on available methods.
+Add your plugin content into this file. Here's an example that will just print all of the requests it receives to the console. See below for more information on available methods.
 
     from future import print_function
     from rtmbot.core import Plugin
@@ -82,27 +84,44 @@ Add your plugin content into this file. Here's an example that will just print a
 
 You can install as many plugins as you like, and each will handle every event received by the bot indepentently.
 
-To install the example 'repeat' plugin
+To create an example 'repeat' plugin:
+
+Open `plugins/repeat.py`
+
+Add the following:
+
+    from __future__ import print_function
+    from __future__ import unicode_literals
+
+    from rtmbot.core import Plugin
+
+
+    class RepeatPlugin(Plugin):
 
-    mkdir plugins/
-    cp docs/example-plugins/repeat.py plugins/repeat.py
+        def process_message(self, data):
+            if data['channel'].startswith("D"):
+                self.outputs.append(
+                    [data['channel'], 'from repeat1 "{}" in channel {}'.format(
+                        data['text'], data['channel']
+                    )]
+                )
 
-The repeat plugin will now be loaded by the bot on startup.
+The repeat plugin will now be loaded by the bot on startup. Run `rtmbot` from console to start your RtmBot.
 
-    ./rtmbot.py
+    rtmbot
 
 Create Plugins
 --------
 
 ####Incoming data
-All events from the RTM websocket are sent to the registered plugins. To act on an event, create a function definition called process_(api_method) that accepts a single arg. For example, to handle incoming messages:
+All events from the RTM websocket are sent to the registered plugins. To act on an event, create a function definition, inside your Plugin class, called process_(api_method) that accepts a single arg for data. For example, to handle incoming messages:
 
     def process_message(self, data):
         print data
 
 This will print the incoming message json (dict) to the screen where the bot is running.
 
-Plugins having a method defined as ```catch_all(data)``` will receive ALL events from the websocket. This is useful for learning the names of events and debugging.
+Plugins having a method defined as ```catch_all(self, data)``` will receive ALL events from the websocket. This is useful for learning the names of events and debugging.
 
 For a list of all possible API Methods, look here: https://api.slack.com/rtm
 
@@ -130,37 +149,23 @@ Plugins also have access to the connected SlackClient instance for more complex
 ####Timed jobs
 Plugins can also run methods on a schedule. This allows a plugin to poll for updates or perform housekeeping during its lifetime. This is done by appending a two item array to the crontable array. The first item is the interval in seconds and the second item is the method to run. For example, this will print "hello world" every 10 seconds.
 
+Note that the Job uses the associated Plugin's output array to output back to the RTM stream.
+
     from core import Plugin, Job
 
 
     class myJob(Job):
 
         def say_hello(self):
-            self.outputs.append(["C12345667", "hello world"])
+            self.plugin.outputs.append(["C12345667", "hello world"])
 
 
     class myPlugin(Plugin):
 
         def register_jobs(self):
-            job = myJob(10, 'say_hello', self.debug)
+            job = myJob(10, 'say_hello', self.debug, self)
             self.jobs.append(job)
 
 
 ####Plugin misc
-The data within a plugin persists for the life of the rtmbot process. If you need persistent data, you should use something like sqlite or the python pickle libraries.
-
-####Direct API Calls
-You can directly call the Slack web API in your plugins by including the following import:
-
-    from client import slack_client
-
-You can also rename the client on import so it can be easily referenced like shown below:
-
-    from client import slack_client as sc
-
-Direct API calls can be called in your plugins in the following form:
-    
-    sc.api_call("API.method", "parameters")
-
-####Todo:
-Some rtm data should be handled upstream, such as channel and user creation. These should create the proper objects on-the-fly.
+The data within a plugin persists for the life of the rtmbot process. If you need persistent data, you should use something like sqlite or the python pickle libraries.

client.py

@@ -3,7 +3,8 @@
 import sys
 import os
 import yaml
-import client
+
+from rtmbot import RtmBot
 
 sys.path.append(os.getcwd())
 
@@ -18,11 +19,16 @@ def parse_args():
     )
     return parser.parse_args()
 
-# load args with config path
-args = parse_args()
-config = yaml.load(open(args.config or 'rtmbot.conf', 'r'))
-bot = client.init(config)
-try:
-    bot.start()
-except KeyboardInterrupt:
-    sys.exit(0)
+
+def main(args=None):
+    # load args with config path
+    args = parse_args()
+    config = yaml.load(open(args.config or 'rtmbot.conf', 'r'))
+    bot = RtmBot(config)
+    try:
+        bot.start()
+    except KeyboardInterrupt:
+        sys.exit(0)
+
+if __name__ == "__main__":
+    main()

rtmbot/bin/__init__.py

@@ -7,7 +7,7 @@
 
 from slackclient import SlackClient
 
-from utils.module_loading import import_string
+from rtmbot.utils.module_loading import import_string
 
 sys.dont_write_bytecode = True
 
@@ -33,7 +33,7 @@ def __init__(self, config):
         # TODO: Raise an exception if no SLACK_TOKEN is specified
 
         # get list of directories to search for loading plugins
-        self.active_plugins = config.get('ACTIVE_PLUGINS', None)
+        self.active_plugins = config.get('ACTIVE_PLUGINS', [])
 
         # set base directory for logs and plugin search
         working_directory = os.path.abspath(os.path.dirname(sys.argv[0]))
@@ -124,6 +124,10 @@ def load_plugins(self):
         load any classes with Plugin in the name from any files within those dirs.
         '''
         self._dbg("Loading plugins")
+        if not self.active_plugins:
+            self._dbg("No plugins specified in conf file")
+            return  # nothing to load
+
         for plugin_path in self.active_plugins:
             self._dbg("Importing {}".format(plugin_path))
 

rtmbot.py rtmbot/bin/run_rtmbot.pyrtmbot.py renamed to rtmbot/bin/run_rtmbot.py

@@ -1,13 +1,18 @@
 #!/usr/bin/env python
-
-from distutils.core import setup
+from setuptools import setup, find_packages
 
 setup(
     name='rtmbot',
-    version='0.2.0',
+    version='0.2.11',
     description='A Slack bot written in python that connects via the RTM API.',
-    author='Ryan Huber',
-    author_email='[email protected]',
+    author='Ryan Huber and Jeff Ammons',
+    author_email='[email protected]',
     url='https://github.com/slackhq/python-rtmbot',
-    packages=['rtmbot'],
+    packages=find_packages(),
+    entry_points={'console_scripts': ['rtmbot=rtmbot.bin.run_rtmbot:main']},
+    install_requires=[
+        'python-daemon',
+        'pyyaml',
+        'slackclient'
+    ]
  )