Licence, copyright and attribution
pyGBot - Versatile IRC Bot Copyright (C) 2008 Morgan Lokhorst-Blight, Alex Soborov, Paul Rotering 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 3 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. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
Based on pyTBot, (c) 2007 Paul Rotering Licensed under GPLv2
Uses ConfigObj, (c) 2008 Michael Foord and Nicola Larosa Licensed under modified (3 clause) BSD License
Uses "C# Events in Python", (c) 2005 Zoran Isailovski Licensed under MIT License
Simple Disclaimer: THIS IS AN ALPHA RELEASE. It it provided AS-IS, with no warranty or support. If it breaks your computer, it's not our fault.
- Python >= 2.5
- Twisted >= 10.0 (including twisted.words)
- pyOpenSSL (only when enabling SSL)
- Decompress the pyGBot archive.
pyGBot.iniand modify the values. These are all of your bot's configuration options. The main options you're interested in to get the bot up and running are
Configuring the Auth System
Some commands are limited to authorized users; this prevents just anyone from telling pyGBot to (for example) join or leave a channel. pyGBot has an auth system to control user login and access in order to use moderator- or administrator-level commands. To configure it, you have to do 2 things: set the auth mode in pyGBot.ini, and add users.
pyGBot has two possible auth modes:
pygbot: This mode uses its own username/password system stored in
nickserv: This mode identifies users by checking to see if they're identified with NickServ, and then checking if they're in
users.inito determine their access level (user, moderator or admin). This is designed for the standard atheme NickServ service.
In order to configure the mode:
- Under the section
[Plugins.system.Auth], change the
authtypevalue to either
nickserv. (Don't add quotation marks around the value).
- If the
authtypevalue don't exist in the file, create them at the end of the file before doing step #2.
By default, no users are configured with the auth system. To add users:
- Enter the details it asks for. In
pygbotauth mode, the username and password are needed for users to log in. In
nickservmode, the username is used to check if a person is identified with NickServ using the same nick as the username you enter (password is not used, but set it to something secure anyway in case you switch to
- If you ever need to remove a user from the system, open
users.iniand delete the section corresponding to that user.
Customising with Included or Downloaded Plugins
pyGBot is highly customisable using plugins. Several plugins are included but not enabled, and you can write or download your own plugins.
If you downloaded a plugin and want to install it:
- Put all the plugin's files into a directory under the
pyGBot/Pluginsdirectory. (Note: If your plugin package contains a
Plugindirectory already, you're probably supposed to move archive's contents to
pyGBotand let it merge the directories together. However, note that we take no responsibility if it overwrites pyGBot's own files or plugins and does something bad!)
- Follow the directions for configuring a plugin, below.
To configure a plugin that's included with pyGBot or one you just downloaded and installed:
- Find the
[Plugins]section. Let's say your plugin's file is in
pyGBot/Plugins/example/ExPlugin.py; then add the line
example.ExPlugin =to the file (put nothing to the right of the equation sign).
- If you want the plugin to automatically activate when you start pyGBot, add
the same line to the
- If the plugin has some custom commands that work with the system.Commands
plugin (i.e. it adds files to
pyGBot/Plugins/system/CommandSpec), then you can bind those commands to the names used by IRC users in the
[Plugins.system.Commands]section. Let's say one file is
DoStuff.pyand you want IRC users to type
^stuffto activate the command, add the line
stuff = DoStuff. (The
^prefix can be changed).
Specific plugins may give more specific information about installing and
configuring. For the included plugins, their configuration is often commented
pyGBot.ini file, and sometimes explained in the comments (comments
start with #).
Detailed documentation on writing plugins is not available (yet! It's coming!).
You can take a look at
pyGBot/BasePlugin.py, as well as existing plugins in
pyGBot/Plugins directory to see how things are done. What follows is a
brief description of the plugin system and a few pointers.
Every plugin must be a class that subclasses
BasePlugin. You should override
the methods in
BasePlugin in order to intercept various IRC events, such as
receiving a message in a channel. When a plugin is loaded by pyGBot, the plugin
class is instantiated once (calling
\_\_init\_\_() in the process), and the
plugin instance's methods are called whenever the associated IRC event occurs.
For pyGBot's API, take a look at the first few methods (above
in the class
pyGBot/core.py, along with Twisted's documentation for
the irc.IRCClient class (which GBot subclasses). If methods exist to do the
same thing in both
GBot and Twisted, use the
GBot version. Logging
facilities are provided via the
log.logger object(pyGBot's log) and
object (IRC chat log), which are both instances of Python's built-in
from pyGBot import log to use them). You can always take a look
at other plugins for examples on using the API.
Note that pyGBot will always pass messages to plugins as
str strings (refer to the Python 2.x manual). pyGBot can handle
str strings going back out (for example, when sending
a message to a channel).
system.Commands plugin provides a set of commands (extensible, of course!)
which are single-line calls made by users to enact some immediate response or
action. The existing ones are primarily related to controlling the bot (join or
part channels, send public message, etc.), but any single-line command could
conceivably be implemented here. A few examples of other commands are the ones
used to play games, the
Seen command (for the
features.Seen plugin) and the
Wiki command (for the
To write your own, start by taking a look at the
BaseCommand class in
pyGBot/Plugins/system/Commands.py and at the existing commands in
pyGBot/Plugins/system/CommandSpec. Like Plugins, Commands need to be a class
BaseCommand; but unlike Plugins, command classes don't have a
persistent instance: when an IRC user calls on a command, the command class
is instantiated, its
__init__() method is called with the command parameters,
and then the instance is discarded.
You can easily write commands that act as a wrapper for a plugin. Doing so
avoids the need to check every incoming message yourself to find out if it's
intended for your plugin, and makes it easy for users of your plugin to change
the name IRC users use to call the command (see the
Please use the issue tracker on the homepage to report any problems with the
software. For assistance, visit
#pyGBot on the foonetic IRC network
- The pyGBot team