D’bolla is a no bullshit extensible IRC/Slack bot written for Python 3.5 using asyncio.
pip install websockets
Copy dbolla.conf.example to dbolla.conf and edit this file. You can specify multiples of the same connection by prefixing the config section with ‘slack:’ or ‘irc:’ followed by a unique name for this connection.
Simply run the command:
./bin/dbolla -c /path/to/my/dbolla.conf
To write a new plugin you must inherit from
warmachine.addons.base.WarMachinePlugin
. This class defines an interface you
must implement in order to interact with connections. If you override __init__
you must call super()
.
This is given to you access to the asyncio loop. This is useful for scheduling tasks to be run later.
The directory to store any configuration files and other junk in.
This is a logger that you should use when logging messages.
recv_msg
is the only required method for a plugin. It is called for every
plugin every time a connection receives a message. It takes the arguments
connection
and message
. connection
is the Connection object which allows
you to interact with that chat server. message
is a dictionary containing
information about the message received. It has the following format:
{
'sender': 'sender nickname',
'channel': '#channel_name or None for private messages',
'message': 'The message that was received',
}
You will parse message['message']
for what you are interested in and take some
action based on what was found.
For example:
async def recv_msg(connection, message):
"""
A simple echo 'server'.
"""
# if the message starts with !echo, and it was said in a channel (not a
# private message)...
if message['message'].startswith('!echo') and message['channel']:
# Strip the command !echo from the message
try:
msg_to_repeat = ' '.join(message['message'].split(' ')[1:])
except IndexError:
# There was nothing to echo
return
# Repeat the remainder of the received message
await connection.say(msg_to_repeat, message['channel'])
This method is called when a connection successfully connects and takes the
single argument connection
. Use this method to do any start up initialization
you may want to do such as create configuration files that don’t exist yet.
To write a new connection protocol you must inherit from
warmachine.connections.base.Connection
. This class defines an interface you
must implement to support the plugins. If you override __init__
you must call
super()
.
This global is used to decide which connection to use when it is found in the
config file. E.g. IRC uses 'irc'
and Slack uses 'slack'
. It should be
defined somewhere near the top of your file.
The directory to store any configuration files and other junk in.
D’bolla uses python 3’s asyncio to manage multiple connections concurrently thus
you should use asyncio.open_connection
to create your connection. Once you
have successfully connected you must set self.status
to
warmachine.connections.base.CONNECTED
. This indicates the connection is ready
to use.
This method is constantly checked in a loop by the Bot
class. When a message
is returned it is passed into the recv_msg
method in all loaded plugins. This
return value should be formatted in the following format:
{
'sender': 'sender nickname',
'channel': '#channel_name or None for private messages',
'message': 'The message that was received',
}
This method is used by plugins to send a message to a channel or user.
This should return a unique id used to identify this particular connection. This is used by plugins when saving state. As an example, the IRC connection uses something like this:
@property
@warmachine.utils.decorators.memoize
def id(self):
from hashlib import md5
value = '{}-{}'.format(self.host, self.nick)
return md5(value.encode()).hexdigest()
This method should return a list of all users (including the bot) for the connection.