Slim, concise and dynamic python-based IRC bot library. This library is currently built against python 2.7.
$ pip install pIRCThe use of hooks is described in more detail in the hooks_example.py file
There are 3 pairs of ways to use this library.
The first pair of ways is to use the Base class for a single contained bot.
You can instantiate it (which doesn't have much functionality on it's own):
import pIRC
if __name__ == '__main__':
bot = pIRC.Base('irc.website.com',
nick = 'DaBot',
password = 'thisisnotapassword',
channels = ['#Chan-chan'],
realname = 'pIRC Bot',
ident = 'BOT',
command = '$',
replace = dict(
me = lambda _bot: _bot.config['nick']
),
verbose = True,
break_on_match = False,
)
bot.connect()Or inherit it and add custom hooks inside the class (more useful):
import pIRC
class CustomBase(pIRC.Base):
@pIRC.hooks.msg('^Greetings$')
def greet(self, target, sender, *args):
self.message(target, "And a hello to you too, %s"%sender)
if __name__ == '__main__':
bot = CustomBase('irc.website.com',
nick = 'DaBot',
password = 'thisisnotapassword',
channels = ['#Chan-chan'],
realname = 'pIRC Bot',
ident = 'BOT',
command = '$',
replace = dict(
me = 'Static Bot Name'
),
verbose = True,
break_on_match = False,
)
bot.connect()The next pair is similar to the last, but offers more freedom and stability with controlling the bot by using the Bot class with a couple extra config options.
As before, you can instatiate it:
import pIRC
if __name__ == '__main__':
bot = pIRC.Bot('irc.website.com',
nick = 'DaBot',
password = 'thisisnotapassword',
channels = ['#Chan-chan'],
realname = 'pIRC Bot',
ident = 'BOT',
command = '$',
replace = dict(
me = lambda _bot: _bot.config['realname']
),
verbose = True,
break_on_match = False,
hookscripts = ['custom_hooks'],
reload_override = True
)
bot.connect()Or inherit it and add hooks into the class itself:
import pIRC
class CustomBot(pIRC.Bot):
@pIRC.hooks.msg('^Greetings$')
def greet(self, target, sender, *args):
self.message(target, "And a hello to you too, %s"%sender)
if __name__ == '__main__':
bot = CustomBot('irc.website.com',
nick = 'DaBot',
password = 'thisisnotapassword',
channels = ['#Chan-chan'],
realname = 'pIRC Bot',
ident = 'BOT',
command = '$',
replace = dict(
me = 'Botty'
),
verbose = True,
break_on_match = False,
hookscripts = ['custom.hooks'],
reload_override = True
)
bot.connect()Notice the arguement hookscripts.
This option is a list of extensionless python filenames (using import notation) that contain functions wrapped in a @pIRC.hooks descriptor.
It allows the class to refence and use functions outside of the main file without having to make an interiting class.
To load hooks, the file must be passed using the python DOT notation used for imports.
Say you had a file like so: custom/myhooks.py. You would pass the following string: custom.myhooks.
Descriptions of the other configuration variables are avaliable in the Bot class' DocString in the source.
The thrid pair of ways give more functionality by allowing management of a single bot connecting to multiple networks by using the BotGroup class.
It uses threading for each bot used to recover from crashes and improve bot stability. (or something nerdy like that)
This way is setup a bit differently than the previous 2 pairs. Since it carries multiple network connections, it needs to have each network defined separately.
This is done with the .network() method. This method takes the same arguments as does instantiating a Bot class instance does
You can instantiate it with the default settings:
import pIRC
if __name__ == '__main__':
botgroup = pIRC.BotGroup()
botgroup.network('irc.website.com',
nick = 'DaBot',
password = 'thisisnotapassword',
names = ['Hey Bot','Yo Bot'],
channels = ['#Chan-chan'],
realname = 'pIRC Bot',
ident = 'BOT',
command = '$',
replace = dict(
me = lambda _bot: _bot.config['nick']
),
verbose = True,
break_on_match = False,
hookscripts = ['custom_hooks'],
reload_override = True
)
botgroup.connect(True)Or you can instantiate it with an arguement that is a custom class that inherits from the Bot or Base classes to use as the default.
You also have the option to specify a specific custom class per defined network via adding the ref keyword arguement to the .network() method.
import pIRC
class CustomBase(pIRC.Base):
@pIRC.hooks.msg('^Hello$')
def greet(self, info):
self.message(info['target'], "And a hello to you too, {}".format(info['source']['nick']))
class CustomBot(pIRC.Bot):
@pIRC.hooks.msg('^Howdy$')
def greet(self, target, sender, *args):
self.message(info['target'], "And a howdy to you too, {}".format(info['source']['nick']))
if __name__ == '__main__':
botgroup = pIRC.BotGroup(CustomBase, 60)
botgroup.network('irc.website.com', ref = CustomBot, # will greet with "Howdy"
nick = 'DaBot',
password = 'thisisnotapassword',
channels = ['#Chan-chan'],
realname = 'pIRC Bot',
ident = 'BOT',
command = '$',
replace = dict(
me = lambda _bot: _bot.config['nick']
),
verbose = True,
break_on_match = False,
hookscripts = ['custom_hooks'],
reload_override = True
)
botgroup.network('irc.secondwebsite.com', # will greet with "Hello"
nick = 'DaBot',
password = 'thisisnotapassword',
channels = ['#Chan-chan'],
realname = 'pIRC Bot',
ident = 'BOT',
command = '$',
replace = dict(
me = lambda _bot: _bot.config['nick']
),
verbose = True,
break_on_match = False,
hookscripts = ['custom_hooks'],
reload_override = True
)
botgroup.connect(True)The second argument is the interval in seconds which the class uses to check the state of each bot thread and restarts them if they have died.
The argument on the .connect() method is for whether or not to contain the main thread in an input loop or not.
If the argement is False (default value) the method returns for further processing if so desired.
Unless there is a function that you want to override or add, there isn't a need to inherit BotGroup into a custom class.
- Better and more descriptive documentation
- Add more default IRC controls
- Fix up user/channel management caching