Package: pinhook
pinhookThe pluggable python framework for IRC bots and Twitch botsInstallationCreating an IRC BotFrom Config FileFrom Python FileCreating a Twitch BotCreating pluginsExamplesInstallationPinhook can be installed from PyPI:pipinstallpinhookCreating an IRC BotA pinhook bot can be initialized using the command line toolpinhookwith a config file, or by importing it into a python file to extend the base class.From Config FilePinhook 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 botserver: (string) server for the bot to connectchannels: (array of strings) list of channels to connect to once connectedOptional keys:port: (default:6667) choose a custom port to connect to the serverops: (default: empty list) list of operators who can do things like make the bot join other channels or quitplugin_dir: (default:"plugins") directory where the bot should look for pluginslog_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 nickservserver_pass: password for the serverssl_required: (default:False) boolean to turn ssl on or offOnce you have your configuration file ready and your plugins in place, you can start your bot from the command line:pinhookconfig.yamlPinhook will try to detect the config format from the file extension, but the format can also be supplied using the--formatoption.$pinhook--help
Usage:pinhook[OPTIONS]CONFIG

Options:-f,--format[json|yaml|toml]--helpShowthismessageandexit.From Python FileTo create the bot, just create a python file with the following:frompinhook.botimportBotbot=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 serverops: (default: empty list) list of operators who can do things like make the bot join other channels or quitplugin_dir: (default:"plugins") directory where the bot should look for pluginslog_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 nickservserver_pass: password for the serverssl_required: (default:False) boolean to turn ssl on or offCreating a Twitch BotPinhook has a baked in way to connect directly to a twitch channelfrompinhook.botimportTwitchBotbot=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:opsplugin_dirlog_levelThese options are the same for both IRC and TwitchCreating pluginsThere 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.commanddecorator to create command plugins, or@pinhook.plugin.listenerto create listeners.The function will need to be structured as such:importpinhook.plugin@pinhook.plugin.command('!test')deftest_plugin(msg):message='{}: this is a test!'.format(msg.nick)returnpinhook.plugin.message(message)The function will need to accept a single argument in order to accept aMessageobject from the bot.TheMessageobject 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.datetimeobject when theMessageobject was createdtimestamp: float for the unix timestamp when theMessageobject was createdbot: the initialized Bot classIt 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 noticeYou can optionally set a command to be used only by opsThe function will need to be structured as such:@pinhook.plugin.command('!test',ops=True,ops_msg='This command can only be run by an op')deftest_plugin(msg):returnpinhook.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 triggeredpinhook.plugin.action: CTCP action in the channel where command was triggered (basically like using/me does a thing)ExamplesThere are some basic examples in theexamplesdirectory in this repository.Here is a list of live bots using pinhook:pinhook-tilde- fun bot for tilde.townadminbot- admin helper bot for tilde.town, featuring some of the ways you can change the Bot class to suit your needs