SupyBot: A half-ranty review

I’ve recently been playing with SupyBot (an IRC bot written in python) again. It’s main ‘selling points’ are that it aims to be easy to develop plug-ins for. Yeah Right. While I’ve used SupyBot for a long time now (since the start of #unity-coders in fact). I really appreciate both the project and what the developers are doing but I wanted to outline some of the problems I’ve encountered when trying to use SupyBot.

Scripts, Tutorials and Design

There things that SupyBot does really well.The automated scripts for creating bots & plug-ins, the tutorials in the /docs/ folder and the way in which plug-ins are loaded into the core are the three main reasons I’m still using SupyBot. These things combined make writing very simple plug ins virtually effortless. It doesn’t need you to open up random telnet ports to administer the bot either, unlike some other IRC bots. I can’t fault SupyBot on any of these features.

API Documentation

While the scripts that SupyBot ships with to automate plug-in creation are very helpful, they don’t make up for poor documentation. And if there is one thing lacking with SupyBot it’s documentation. Most of the code is documented if you have time to look though all of the project’s source code. I don’t. You’d be better off using the documentation to prop up a table than write a plug-in with.

The closet thing I’ve found to good API documentation is looking at the existing plug-ins shipped with the bot. Which is fine if your plug-in does things which other people’s plug-ins do (or at least partly do). If your plug-in does something a bit different, or the examples are outdated you’ve got no hope, so you better get reading though the source now. The first major thing that I feel the project could benefit from is API documentation.

On a slight sidenode…

I’d also like a list of things I’m not meant to do… I overrode the python equivalent of a constructor (__init__) on a plug-in class and got a small essay from my bot when I loaded the plug-in about a switch from CVS to Darcs and the arguments my constructor should take. While I found this slightly amusing, it really didn’t help very much. It may just be me, but a language that lets you define the value of constants, such as ‘True’ (true story, try it in python 2.x), I really like knowing what I’m allowed to do… because the language won’t stop me from messing up.


A lot of the plug-ins also make use of the bot’s permissions system. SupyBot’s permissions system is a very complete and powerful one (even if not very scalable for large groups of users or plug-ins).

Firstly, a brief description of the system. It’s permissions based. The permissions are defined per user. Each command can have a permission in order to use it. The bot uses ‘anti-permissions’ to disallow users using certain commands. Plug-ins seem to be able to define their own additional permissions as well. The system supports a limited form of predefined ‘roles’ (Owner, Admin & Channel Op are the three I’ve used), but I’ve got no idea if you can define your own roles or assign permissions to existing roles.

There is no definitive list of permissions. While I can understand this is a technical limitation of the design, a list of permissions provided with core plug-ins would be helpful to say the least. Even a text file detailing the permissions and what they do would do. You can give a user channel operator privileges using the permission ‘#channel,op’. This is covered in the documentation however what is not covered is what this does. Does it mean the bot will let them have op? change the topic though the bot? order pizza? who knows.

Setting default permissions is also not covered. Can you set permissions for unregistered users? It’s mentioned briefly in a few of the tutorials but not actually documented anywhere! The use case is quite simple, you might want to set the default of a permission to be the ‘anti-permission’ and only allow some users to use the command (checking the system daemon status, for example).

Again trying to use permissions in plug-ins isn’t really covered in any level of detail. It is possible to work it out from existing plug-ins or examining the permission modules’s source code but I’d really rather not do that. The second thing which I would like to recommend for the developers is Permission Documentation (and not letting ops order pizza)*.


This last point of my rant is purely from an administrator point of view. Configuration of plug-ins is both a fantastic thing and bad thing in SupyBot. The fact that you can find out what configuration options are available for a plug-in, and get a description over IRC is a really nice feature. It means you don’t have to edit configuration files if you don’t want to and can allow trusted users to make configuration changes in your absence.

However, sometimes having to do searches though the bot interface for the configuration options is a little tiresome. The values which the plug-in expects are not always made clear in these descriptions either (do I set this value to -1 or 0 to disable it? is 0 off or unlimited?). There used to be online documentation for a number of the plugins, detailing their commands and their configuration options. It was removed for being too out of date but you can still find it if you look around.

End user documentation (!help and !list)

When using the bot the user can ask the bot “what does this command do?” by using “!help “. The user can also ask the bot “what commands are there” using the “!list” command. Both these commands fetch details from the plug-in source directly. The documentation here (the ‘user facing’ documentation) is fantastic! It even tells the user about the parameters which the commands need.

The instructions in the bot creation wizard (supybot-create) are just as good, it goes though step by step asking the user questions and giving them useful, relevant information at every step. It offers sensible defaults and issues sensible recommendations to the user. Once the process is complete, the configuration file is again filled with useful documentation about the options in the file.

SupyBot is a fantastic bot, and a useful framework for developing plug-ins. It is technically very advanced and one of the nicer IRC frameworks I’ve looked into. It has a wide user base and a wide range of existing plug-ins. So SupyBot is just bad at documentation? Well, no, not everywhere, but without good documentation it can be very frustrating to work with. The end user facing documentation is fantastic, but the developer facing documentation is poor, or non-existent in places. Writing documentation isn’t always the most interesting or nicest part of software development but it is needed.

* No, SupyBot doesn’t let ops order pizza.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.