Legobot is a platform which makes interactive IRC bots easy to build. The bot provides connectivity and the ability to listen and respond to users. The bot provides user functions a usable "message" object when needed, eliminating the need to parse raw IRC strings.
Just run pip install Legobot. You can also install and run this as a non-privileged user by using pip install --user Legobot instead (recommended).
Legobot is intended to be simple in usage, flexible, and allow the user to drive all functionality. Therefore it is a given that it doesn't do much on its own outside of managing the IRC connection and watching conversations. Any triggers and responses are yours to build.
Legobot's primary functionality centers around a few methods:
First, let's initialize our bot:
import Legobot
HOST = 'irc.freenode.com'
PORT = 6667
NICK = 'legobot'
CHANS = [('#freenoode',''),('#bitcoin',''),('#legobot','')] #List of tuples. Format is (channel,password)
myBot = Legobot.legoBot(host=HOST,port=PORT,nick=NICK,chans=CHANS)Write a function, add it to Legobot, then connect!
def helloWorld(msg):
return "Hello, world!"
myBot.addFunc("!helloworld", helloWorld, "Ask your bot to say hello. Usage: !helloworld")
mybot.connect(isSSL=False)Then watch your creation come to life:
<bbriggs> !helloworld
<legobot> Hello, world!
<bbriggs> !help
<legobot> Available functions: !helloworld, !help
<bbriggs> !help !helloworld
<legobot> Ask your bot to say hello. Usage: !helloworld
Congratulations, you just wrote an IRC bot!
Legobot.legobot(host,port,nick,chans, logfunc = "", hostpw = "", defaultFunc = None, defaultFuncChar = "")
Parameters:
host String. IRC host to connect to.
port Int. IRCd port to connect to (port IRC server is listening on).
nick String. Nickname you want your bot to use. Also sets realname value in IRC.
chans List. This is actually a list of tuples in the form of (channel,channel_password). Example: [('#admins','supersecretpassword'),('#social','')]
logfunc Function._ Function object (without parens). logfunc is called with a msg objet for every line read in from irc. Essentially allowing a bot to log all conversations in the room. Can be useful for lookback bots.
hostpw String. Password for the IRCd, if necessary.
defaultFunc Function._ Function object (without parens). Supply a fallback function to trigger if your users ask for a function that doesn't exist.
defaultFuncChar String. Predicating character for which to call your default func. Typically bots are written to respond to a special character, eg: exclamation point. The bot would be expected to respond to things like !help, !tip, etc. defaultFunc and defaultFuncChar allow us to respond to unknown calls, eg !blah would then run the default function if there was not a function specifically written for !blah.
addFunc(self, name, function, helpText = "")
Parameters:
name String. The word you want to trigger the function. Legobot only considers the first word in a message for this. Example: if name="!helloworld" and you say "!helloworld" in IRC, that will trigger the function. However, "will !helloworld work?" will not trigger the function.
function Function. Function object (without parens). It's usually helpful to name the function the same as the trigger. This is the function that gets called when the trigger word in the name parameter is seen.
helpText String. Describe in a few words what this function does. Gets displayed when user requests !help !yourfunction in IRC.
Parameters:
func Function. Function object (without parens). Set the default, fallback function to trigger when users spam nonsense that starts with your trigger character. ie, !xyzzy could trigger !help. If you're not in the mood to be helpful, why not insult your users for being silly?
char String. Single character to serve as a trigger to let Legobot know we're talking to it. Example: setting char to '!' and just saying ! in chat would trigger the default function.
Parameters
isSSL Boolean. Use SSL when connecting to the IRCd host
Parameters:
msgToSend String. Line to send to IRC channel.
Parameters:
None.
Every line that comes in from the IRC connection generates a Message object in Legobot which is then parsed by the bot. Messages where the Message.cmd property (discussed below) matches a trigger will run the corresponding function. Legobot then passes the message object to the newly triggered function as a parameter. Example:
def cointoss(msg):
"""
Inputs:
takes msg object
Outputs:
returns string to echo back to user in IRC
Purpose:
flip an imaginary coin or roll an imaginary N-sided die
Usage:
!roll [# of sides]
"""
if not msg.arg1:
toss = random.randint(0,1)
if toss == 0:
returnVal = "Heads"
else:
returnVal = "Tails"
else:
if not is_num(msg.arg1):
returnVal = "Incorrect syntax. You must use a (sane) number"
elif is_num(msg.arg1) and not int(msg.arg1) >= 2:
returnVal = "Use at least two sides, weirdo."
elif is_num(msg.arg1) and int(msg.arg1) == 2:
toss = random.randint(1,2)
if toss == 1:
returnVal = "Heads"
else:
returnVal = "Tails"
else:
toss = random.randint(1,int(msg.arg1))
returnVal = str(toss)
return returnValNote: If you want your function to reply back to the channel or user the bot receieved from, return a just a string. To respond or forward to a specific channel, return a tuple of two strings in the form (message,channel_or_user)
Properties:
Message.fullMessage, String. full, raw IRC line.
Message.splitMessage, String. IRC line split on whitespaces, truncated to 7 items. The 7th item is all remaining text, if it exists.
Message.length, String. The value of len(self.splitMessage)
Message.userInfo, String. The nick, realname, and host (or hostmask) of the IRC user who sent the message.
Message.actualUserName, String. Realname of IRC the user who sent the message.
Message.target, String. where the message was addressed. ie, channel or individual user. Used to detect if message sent was a private message.
Message.cmd, String. First word in user's actual message. In 'Hello world!', Message.cmd is 'Hello'
Message.arg1, arg2, and arg3, String. Additional positional arguments to evaluate when parsing a triggered command. May or may not be present depending on the length of the input line.
Message.isPM, Boolean. False if message was sent to whole #channel, True if sent to just the bot.
Issues and pull requests welcome. Please send PRs to the development branch.
Legobot Copyright (c) 2016 Bren Briggs and Kevin McCabe
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.