pbnj

pbnj is an python IRC bot library and framework. It's designed so you can write an absolute minimum of boilerplate to have a fully working and extensible bot.

pbnj is:

• Tested (near complete code coverage)
• Small (less than 500 lines of code without tests)
• Portable (built with the standard library)

Installing

pip install pbnj

Demo!

weather.py

from pbnj.bot import Bot
bot = Bot('forecaster')

@bot.command('^\.weather [0-9]{5}')
def weather(message):
    '''get the weather for a zip code in the US'''
    zip_code = message.args[0]
    response = requests.get('http://my.weather.com/api/{0}'.format(zip_code))
    return '{0}: Currently {r.temp} degrees F'.format(message.nick, r=response.json())

if __name__ == '__main__':
    bot.connect('irc.network.com', port=6697, ssl=True)
    bot.join('#channel')
    bot.run()

Channel log:

> forecaster joins #channel
idler:          .weather 32490
forecaster:     idler: Currently 83 degrees F
idler:          .help
forecaster:     idler: weather - get the weather for a zip code in the US

(More examples can be found in the examples/ directory of this repository)

Argument to @bot.command(...) can be either a string or a callable that returns a boolean.

If it's a string, the string will be treated as a regular expression on all incoming PRIVMSG messages (anything in a channel or private message). If the regex matches, the command function will execute.

If it's a callable, it will be called with the Message object (see below) of each incoming message. If it returns true, the command function will execute.

The function you decorate with @bot.command(...) will reply to the channel that created the message if you return:

• strings
• a Generator via yield (all yielded strings will be sent to the channel)

If you decide to use builitn commands (for more info see below), help output will be populated automatically. The docstring of your function is the help message, with the name of the function used as the command's name.

Importantly, pbnj logs onto a logger named pbnj. If you want to see debugging & connection-related logs, give it some love.

Requirements

None! Using pbnj is easy because we only use the standard library. If you find any code that isn't compatible on your platform, please issue a bug report.

If you want to run tests, you need pytest and pytest-cov. There's a requirements.txt for that too!

Message objects

pbnj hands you a Message object as the only argument to your command functions. This is a message from an IRC channel or server the bot is a part of, and has a number of fields filled out that you can work with.

Normal fields:

• raw_msg: Message as recieved off the socket
• host: Hostname the message came from
• type: IRC command the message represents. If this is PRIVMSG or ACTION, additional fields are parsed.

PRIVMSG/ACTION fields:

• dest: channel the message came from
• nick: nick of the user the message came from
• realname: realname of the user the message came from
• message: trimmed message from the channel
• args: array of everything but the first word in "message"

Built-in commands

pbnj ships with a number of commands that most botmakers build standard into their bots, usable by setting the use_builtin parameter of the pbnj.Bot constructor to true. You can change the prefix for these commands by setting the 'builtin_prefix' parameter in the Bot constructor. The default is ^\.

Hacking

I'm a vim user, if you are too: vim -S etc/Session.vim

If you want to implement something interesting, send a PR! The source code is formatted using black, please use it to format your patches.

Running the Tests

Code coverage by loc is about 100%, but use case coverage is nowhere near that number. We welcome new bug reports, if you encounter behavior you don't expect please let me know!

virtualenv -p $(which python3) .
source bin/activate
pip install -r requirements.txt
py.test

License

pbnj is Copyright (c) 2018, James Luck. It is licensed under the GNU GPLv3. There is a copy of the license included in LICENSE.txt, peruse it there or at https://www.gnu.org/licenses/gpl-3.0.txt