A script for quickly coding powerful and extensible IRC bots by wrapping any ircII client in a Python class.
Go to file
Thomas Baruchel 4da09b3fb7 Update 2021-06-23 21:36:44 +02:00
LICENSE Initial commit 2021-05-23 16:31:35 +00:00
README.md Update 2021-05-24 16:08:54 +02:00
hack42.py Update 2021-06-23 21:36:44 +02:00

README.md

Hack 42

A script for very quickly coding powerful and extensible IRC bots by wrapping any ircII client in a Python class.

Presentation

Python is a widely known language supported by a huge community. Therefore, coding an IRC bot in Python is a judicious choice. However, rather than reinventing the wheel by implementing low-level functions for handling the IRC protocol, the current project relies on venerable and robust existing clients, which are easy to compile, lightweight and strongly tested. Hack 42 is a wrapper for such clients forked from the famous ircII. The script should work with ircII itself, but also different versions of Epic, as well as BitchX or ScrollZ, etc.

Hacking existing tools rather than building a whole new project from nothing follows a traditional philosophy of coding, explaining the name of the current project (while it could be argued on the other hand that the “42” number in the very same name has no real justification by itself). It allows you to code powerful bots by taking benefits of all features and subtleties from the IRC protocol without having to deal with lots of dependencies huge Python projects have. Furthermore, resulting bots should have a much lower memory footprint and CPU usage than many other Python competitors.

The script by itself is very short and compact (although written with great care), and adding some code at the end for implementing a new bot should simply be a matter of writing a few lines:

class Test(Bot):
    def on_msg(self, nick, msg):
        self.write("/msg " + nick + " Hi, " + nick + "!")

(The code above is very easy to understand; it uses a single hook from the underlying client.)

The script has no dependancy at all (just download it, hack it, and run it); it has been tested with the officiel CPython interpreter as well as with Pypy.

Choosing a client

Forks from ircII share many identical hooks, which provide the most common features an Irc bot should be interested in. Thus, many bots should run with no change at all with any client. Some clients however provide additional commands or hooks; very elaborate bots can take advantage of them.

At least one relevant client should be already installed on many systems or shells; but since Hack 42 relies on the single executable of the client only (with no need for accompanying libraries, etc.), it is also very easy to download and compile a client (without even having to fully install it after the compilation step). Therefore, I strongly suggest to use either Epic5 or ircII which are still maintained and offer state-of-the-art implementations of the IRC and cryptographic protocols.

Writing the bot

A bot is a Python class which extends the Bot class defined at the top of the script. The key idea is that any method whose name starts with on_ will be detected at run time and mapped to the very same hook at the client level. For instance, the on_msg in the example above will be dynamically mapped to the ^on msg event in the client. Epic5 provides about a hundred of such events; for that reason, names are not hardcoded in the script: again, when at run time a method with a on_ name is detected, it is assumed the user is aware of the corresponding event in the client. The list of Epic5 events can be found here, and the list of ircII events can be found here.

The number of arguments expected by each Python method is also dynamically detected at run time by self-inspection. In the example above, it can be seen that the on_msg method has two arguments (not counting the initial self one); then the low-level Irc string will automatically be splitted into two substrings for calling the method. The number of arguments should match the documentation of the corresponding ^on events, but using fewer arguments is allowed: if the method expects a single argument (not counting the self one), the full initial string will be used without being additionally splitted.

Running the bot

The bot starts when an instance of the bot is created and the Python code will not return until the bot exits. Creating an instance allows to pass the initial arguments to the client, and some differences between the chosen client are likely to occur here. Some examples for Epic5 and ircII are provided at the bottom of the script. It may be useful to export the USER environment variable before starting the client, and an option for that is also available.