709d05da73
Passing the bot object as an argument to the Message class make the pinhook Bot class more extensible. Now it is easy to inherit and pass attributes of the inherited class into plugins. See https://github.com/archangelic/pinhook/issues/59 |
||
---|---|---|
examples | ||
pinhook | ||
.gitignore | ||
LICENSE | ||
MANIFEST.in | ||
README.md | ||
_config.yml | ||
setup.py |
README.md
pinhook
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:
port
: choose a custom port to connect to the server (default: 6667)ops
: list of operators who can do things like make the bot join other channels or quit (default: empty list)plugin_dir
: directory where the bot should look for plugins (default: "plugins")log_level
: string indicating logging level. Logging can be disabled by setting this to "off". (default: "info")ns_pass
: this is the password to identify with nickservserver_pass
: password for the serverssl_required
: 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 functionnick
: the user who triggered the commandarg
: (for command plugins) all the trailing text after the command. This is what you will use to get optional information for the commandtext
: (for listener plugins) the entire text of the messagechannel
: the channel where the command was initiatedops
: the list of bot operatorsbotnick
: the nickname of the botlogger
: instance ofBot
's loggerdatetime
: awaredatetime.datetime
object when theMessage
object was createdtimestamp
: float for the unix timestamp when theMessage
object was created
It also contains the following IRC functions:
privmsg
: send a message to an arbitrary channel or useraction
: 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!')
OR
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 triggeredpinhook.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