Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

A clean, extensible IRC bot using irckit.

Project description


A clean, extensible IRC bot using Python, irckit, gevent & requests.

**Author:** Daniel Lindsley<br>
**License:** BSD<br>
**Version:** 0.4.1


* Python 2.6+
* gevent
* irckit
* requests


Create your own ```` file & drop in:

import toastbot

bot = toastbot.ToastBot('myircbot', '#myircchannel')

Then run it with ``python``.


The ``Toastbot`` object requires ``nick`` & ``channel`` arguments & can take a
variety of non-required options.

### Required arguments

* ``nick`` - The nickname of the bot, as a string.
* ``channel`` - The channel the bot should connect to, as a string.

### Options

* ``server`` - The server the bot should connect to (default: ````).
* ``username`` -The username the bot should identify as (default: ``nick``);
* ``realname`` - The human readable name the bot should provide (default: 'ToastBot').
* ``debug`` - Controls if the IRC connection should dump debug messages (default: ``false``).
* ``log_dir`` - Controls what directory the logs should go in (default: ``$INSTALL_DIRECTORY/logs``).
* ``variants`` - Used to override ways to address the bot. Should be strings (default: ``[self.nick+': ', self.nick+', ', self.nick+'- ', self.nick+' - ']``).

Available "handlers"

Handlers are how the bot can perform actions based on an incoming message. They
are simple methods hanging off the bot object. The built-in list consists of:

* ``help`` - Provides a description of what I respond to.
* ``dance`` - Get down and funky.
* ``woodies`` - Best quote on the internet..
* ``wiki`` - Search Wikipedia for a topic.
* ``metar`` - Fetch a NOAA METAR by station code.
* ``twitter`` - Search Twitter for a topic.
* ``fatpita`` - Get a random fatpita image. For the lulz.
* ``corgibomb`` - CORGI BOMB

Extending the bot

Adding on further handlers is relatively simple. At its most basic, it's simply
adding on a new method decorated with ``toastbot.handler``. For example, logging
how many times a user has said something in the channel might look like:

import toastbot

class MyBot(toastbot.ToastBot):
talkers = {}

def __init__(self, *args, **kwargs):
super(MyBot, self).__init__(*args, **kwargs)
self.enabled_commands += [

def how_chatty(self, nick, text):
"""Logs how often a user has said something."""
if nick in self.talkers:
self.talkers[nick] += 1
self.talkers[nick] = 1

print self.talkers.items()

bot = MyBot('myircbot', '#myircchannel')

Note that this command does not require addressing the bot at all. If you want
a command that the bot responds to, you might write something like:

import toastbot

class StoolPigeon(toastbot.ToastBot):
# Assume the previous example, but adding...
def __init__(self, *args, **kwargs):
super(StoolPigeon, self).__init__(*args, **kwargs)
self.enabled_commands += [

def stool_pigeon(self, nick, text):
"""Rat out the talkers."""
text = self.is_direct_command('stool_pigeon', text)

if not text:
raise NotHandled()

return str(self.talkers)

bot = StoolPigeon('myircbot', '#myircchannel')

This checks to see if the bot is being directly addressed then returns a
string-ified version of the ``talker`` stats. The included handlers demonstrate
even more complex behavior, such as how to do network fetches or asynchronous

To disable handlers:

import toastbot

class MyBot(toastbot.ToastBot):
talkers = {}

def __init__(self, *args, **kwargs):
super(MyBot, self).__init__(*args, **kwargs)
self.enabled_commands = [func for func in self.enabled_commands if func.__name__ != 'twitter']

bot = MyBot('myircbot', '#myircchannel')

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for toastbot, version 0.4.1
Filename, size File type Python version Upload date Hashes
Filename, size toastbot-0.4.1.tar.gz (6.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page