pinhook

the pluggable python framework for IRC bots and Twitch bots


Project maintained by archangelic Hosted on GitHub Pages — Theme by mattgraham

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

Tutorial

Installation

$ pip install pinhook

Creating an IRC Bot

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:

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:

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:

It also contains the following IRC functions:

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

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:

Examples

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

Here is a list of live bots using pinhook: