a pluggable irc bot framework in python


License
MIT
Install
pip install pinhook==1.6.0

Documentation

pinhook

Supported Python versions Package License PyPI package format Package development status With love from tilde.town

The pluggable python framework for IRC bots and Twitch bots

Installation

Pinhook can be installed from PyPI:

pip install pinhook

Creating an IRC Bot

A pinhook bot can be initialized using the command line tool pinhook with a config file, or by importing it into a python file to extend the base class.

From Config File

Pinhook supports configuration files in YAML, TOML, and JSON formats.

Example YAML config:

nickname: "ph-bot"
server: "irc.somewhere.net"
channels:
    - "#foo"
    - "#bar"

Required configuration keys:

  • nickname: (string) nickname for your bot
  • server: (string) server for the bot to connect
  • channels: (array of strings) list of channels to connect to once connected

Optional keys:

  • port: (default: 6667) choose a custom port to connect to the server
  • ops: (default: empty list) list of operators who can do things like make the bot join other channels or quit
  • plugin_dir: (default: "plugins") directory where the bot should look for plugins
  • log_level: (default: "info") string indicating logging level. Logging can be disabled by setting this to "off"
  • ns_pass: this is the password to identify with nickserv
  • server_pass: password for the server
  • ssl_required: (default: False) boolean to turn ssl on or off

Once you have your configuration file ready and your plugins in place, you can start your bot from the command line:

pinhook config.yaml

Pinhook will try to detect the config format from the file extension, but the format can also be supplied using the --format option.

$ pinhook --help
Usage: pinhook [OPTIONS] CONFIG

Options:
  -f, --format [json|yaml|toml]
  --help                         Show this message and exit.

From Python File

To create the bot, just create a python file with the following:

from pinhook.bot import Bot

bot = Bot(
    channels=['#foo', '#bar'],
    nickname='ph-bot',
    server='irc.freenode.net'
)
bot.start()

This will start a basic bot and look for plugins in the 'plugins' directory to add functionality.

Optional arguments are:

  • port: (default: 6667) choose a custom port to connect to the server
  • ops: (default: empty list) list of operators who can do things like make the bot join other channels or quit
  • plugin_dir: (default: "plugins") directory where the bot should look for plugins
  • log_level: (default: "info") string indicating logging level. Logging can be disabled by setting this to "off"
  • ns_pass: this is the password to identify with nickserv
  • server_pass: password for the server
  • ssl_required: (default: False) boolean to turn ssl on or off

Creating a Twitch Bot

Pinhook has a baked in way to connect directly to a twitch channel

from pinhook.bot import TwitchBot

bot = TwitchBot(
    nickname='ph-bot',
    channel='#channel',
    token='super-secret-oauth-token'
)
bot.start()

This function has far less options, as the server, port, and ssl are already handled by twitch.

Optional aguments are:

  • ops
  • plugin_dir
  • log_level

These options are the same for both IRC and Twitch

Creating plugins

There are two types of plugins, commands and listeners. Commands only activate if a message starts with the command word, while listeners receive all messages and are parsed by the plugin for maximum flexibility.

In your chosen plugins directory ("plugins" by default) make a python file with a function. You use the @pinhook.plugin.register decorator to create command plugins, or @pinhook.plugin.listener to create listeners.

The function will need to be structured as such:

import pinhook.plugin

@pinhook.plugin.register('!test')
def test_plugin(msg):
    message = '{}: this is a test!'.format(msg.nick)
    return pinhook.plugin.message(message)

The function will need to accept a single argument in order to accept a Message object from the bot.

The Message object has the following attributes:

  • cmd: (for command plugins) the command that triggered the function
  • nick: the user who triggered the command
  • arg: (for command plugins) all the trailing text after the command. This is what you will use to get optional information for the command
  • text: (for listener plugins) the entire text of the message
  • channel: the channel where the command was initiated
  • ops: the list of bot operators
  • botnick: the nickname of the bot
  • logger: instance of Bot's logger
  • datetime: aware datetime.datetime object when the Message object was created
  • timestamp: float for the unix timestamp when the Message object was created
  • bot: the initialized Bot class

It also contains the following IRC functions:

  • privmsg: send a message to an arbitrary channel or user
  • action: same as privmsg, but does a CTCP action. (i.e., /me does a thing)
  • notice: send a notice

You can optionally use the @pinhook.plugin.ops decorator to denote that a command should only be executable by a bot op.

  • If you specify the optional second argument, it will be displayed when a non-op attempts to execute the command

The function will need to be structured as such:

@pinhook.plugin.register('!test')
@pinhook.plugin.ops('!test', 'Only ops can run this command!')
def test_plugin(msg):
    return pinhook.plugin.message('This was run by an op!')

The plugin function can return one of the following in order to give a response to the command:

  • pinhook.plugin.message: basic message in channel where command was triggered
  • pinhook.plugin.action: CTCP action in the channel where command was triggered (basically like using /me does a thing)

Examples

There are some basic examples in the examples directory in this repository.

Here is a list of live bots using pinhook:

  • pinhook-tilde - fun bot for tilde.town
  • adminbot - admin helper bot for tilde.town, featuring some of the ways you can change the Bot class to suit your needs