You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Aug 15, 2022. It is now read-only.
New string-based plugin importing works and docs for it
Updated docs to what I'd like them to be and started stepping through
changes in code to make them work.
Now to make new-style plugins actually work...
A Slack bot written in python that connects via the RTM API.
7
+
A Slack bot written in Python that connects via the RTM API.
8
8
9
-
Python-rtmbot is a callback based bot engine. The plugins architecture should be familiar to anyone with knowledge to the [Slack API](https://api.slack.com) and Python. The configuration file format is YAML.
9
+
Python-rtmbot is a bot engine. The plugins architecture should be familiar to anyone with knowledge to the [Slack API](https://api.slack.com) and Python. The configuration file format is YAML.
*Note*: At this point rtmbot is ready to run, however no plugins are configured.
38
+
DEBUG: True # make this False in production
39
+
SLACK_TOKEN: "xoxb-11111111111-222222222222222"
40
+
ACTIVE_PLUGINS:
41
+
- plugins.repeat.RepeatPlugin
42
+
- plugins.test.TestPlugin
43
+
44
+
```DEBUG``` will adjust logging verbosity and cause the runner to exit on exceptions, generally making dubugging more pleasant.
45
+
46
+
```SLACK_TOKEN``` is needed to authenticate with your Slack team. More info at https://api.slack.com/web#authentication
47
+
48
+
```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.
49
+
50
+
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.
51
+
52
+
A Word on Structure
53
+
-------
54
+
To give you a quick sense of how this library is structured, there is a RtmBot class which does the setup and handles input and outputs of messages. It will also search for and register Plugins within the specified directory(ies). These Plugins handle different message types with various methods and can also register periodic Jobs which will be executed by the Plugins.
55
+
```
56
+
RtmBot
57
+
|--> Plugin
58
+
|---> Job
59
+
|---> Job
60
+
|--> Plugin
61
+
|--> Plugin
62
+
|---> Job
63
+
```
42
64
43
65
Add Plugins
44
66
-------
45
67
46
-
Plugins can be installed as .py files in the ```plugins/``` directory OR as a .py file in any first level subdirectory. If your plugin uses multiple source files and libraries, it is recommended that you create a directory. You can install as many plugins as you like, and each will handle every event received by the bot indepentently.
68
+
To add a plugin, create a file within your plugin directory (./plugins is a good place for it).
69
+
70
+
cd plugins
71
+
vi myplugin.py
72
+
73
+
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.
74
+
75
+
from future import print_function
76
+
from rtmbot.core import Plugin
77
+
78
+
class MyPlugin(Plugin):
79
+
80
+
def catch_all(self, data):
81
+
print(data)
82
+
83
+
You can install as many plugins as you like, and each will handle every event received by the bot indepentently.
The repeat plugin will now be loaded by the bot on startup.
54
91
@@ -58,33 +95,56 @@ Create Plugins
58
95
--------
59
96
60
97
####Incoming data
61
-
Plugins are callback based and respond to any event sent via the rtm websocket. To act on an event, create a function definition called process_(api_method) that accepts a single arg. For example, to handle incoming messages:
98
+
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:
62
99
63
-
def process_message(data):
100
+
def process_message(self, data):
64
101
print data
65
102
66
103
This will print the incoming message json (dict) to the screen where the bot is running.
67
104
68
105
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.
69
106
107
+
For a list of all possible API Methods, look here: https://api.slack.com/rtm
108
+
70
109
Note: If you're using Python 2.x, the incoming data should be a unicode string, be careful you don't coerce it into a normal str object as it will cause errors on output. You can add `from __future__ import unicode_literals` to your plugin file to avoid this.
71
110
72
111
####Outgoing data
73
-
Plugins can send messages back to any channel, including direct messages. This is done by appending a two item array to the outputs global array. The first item in the array is the channel ID and the second is the message text. Example that writes "hello world" when the plugin is started:
74
112
75
-
outputs = []
76
-
outputs.append(["C12345667", "hello world"])
113
+
#####RTM Output
114
+
Plugins can send messages back to any channel or direct message. This is done by appending a two item array to the Plugin's output array (```myPluginInstance.output```). The first item in the array is the channel or DM ID and the second is the message text. Example that writes "hello world" when the plugin is started:
115
+
116
+
class myPlugin(Plugin):
117
+
118
+
def process_message(self, data):
119
+
self.outputs.append(["C12345667", "hello world"])
120
+
121
+
#####SlackClient Web API Output
122
+
Plugins also have access to the connected SlackClient instance for more complex output (or to fetch data you may need).
123
+
124
+
def process_message(self, data):
125
+
self.slack_client.api_call(
126
+
"chat.postMessage", channel="#general", text="Hello from Python! :tada:",
127
+
username='pybot', icon_emoji=':robot_face:'
77
128
78
-
*Note*: you should always create the outputs array at the start of your program, i.e. ```outputs = []```
79
129
80
130
####Timed jobs
81
131
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.
82
132
83
-
outputs = []
84
-
crontable = []
85
-
crontable.append([10, "say_hello"])
86
-
def say_hello():
87
-
outputs.append(["C12345667", "hello world"])
133
+
from core import Plugin, Job
134
+
135
+
136
+
class myJob(Job):
137
+
138
+
def say_hello(self):
139
+
self.outputs.append(["C12345667", "hello world"])
140
+
141
+
142
+
class myPlugin(Plugin):
143
+
144
+
def register_jobs(self):
145
+
job = myJob(10, 'say_hello', self.debug)
146
+
self.jobs.append(job)
147
+
88
148
89
149
####Plugin misc
90
150
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.
0 commit comments