API reference¶
Everything a plugin or bot script uses, generated from pinhook's own code. For how to use it, with examples, see Writing plugins, Testing plugins and Options.
Writing plugins¶
command ¶
command(command, help_text='N/A', ops=False, ops_msg='', hide=False)
Make a function a command, run when a message starts with its command word.
The function gets the message as its only argument.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
command
|
the command word, like '!roll'. |
required | |
help_text
|
shown next to the command in !help. |
'N/A'
|
|
ops
|
if True, only bot operators can run it. |
False
|
|
ops_msg
|
what anyone else is told when they try. Empty means no reply. |
''
|
|
hide
|
if True, leave it out of !help. |
False
|
listener ¶
listener(name)
Make a function a listener, run for every message that isn't a command.
The function gets the message as its only argument, and returns nothing when it has nothing to say.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
the listener's name, shown in !help and used by !enable and !disable. |
required |
message ¶
message(msg)
Reply with a message, where the message came from.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
msg
|
the text, or a list of lines. Each line is sent separately. |
required |
action ¶
action(msg)
Reply with a /me action, where the message came from.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
msg
|
the text, or a list of lines. Each line is sent separately. |
required |
The message¶
Message ¶
A message sent to the bot, as a plugin gets it.
Attributes:
| Name | Type | Description |
|---|---|---|
nick |
who sent it. |
|
user |
the username part of their hostmask (nick!user@host). |
|
account |
the services account they're logged in to, or None. |
|
channel |
where it was sent. For a private message, the sender's nick. |
|
is_private |
True if it was a private message to the bot. |
|
cmd |
(commands) the command word that triggered it. |
|
arg |
(commands) everything after the command word. |
|
text |
(listeners) the whole message. |
|
msg_type |
'message', or 'action' for a /me. |
|
nick_list |
nicks in the channel. Just the sender for private messages. |
|
is_op |
True if the sender is a bot operator. |
|
ops |
the list of bot operators, as written in the config. |
|
botnick |
the bot's current nick. |
|
store |
the plugin's saved data, a dict kept between restarts. |
|
config |
the plugin's settings from plugin_config, read only. |
|
logger |
the bot's logger. |
|
datetime |
when the message arrived, a timezone-aware datetime. |
|
timestamp |
the same as a unix timestamp. |
Bots¶
Bot ¶
Bases: SingleServerIRCBot
An IRC bot that loads plugins from a folder and runs them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channels
|
channels to join once connected. |
required | |
nickname
|
the bot's nick. |
required | |
server
|
the server to connect to. |
required | |
**kwargs
|
any of the bot's options, like port, ssl_required or ops. See https://archangelic.github.io/pinhook/latest/options/ |
{}
|
Call start() to connect and run until the bot quits.
TwitchBot ¶
Bases: Bot
A bot for Twitch chat, connecting to irc.chat.twitch.tv over ssl.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nickname
|
the bot account's name. |
required | |
channel
|
the channel to join, like '#channel'. |
required | |
token
|
the bot account's oauth token, without 'oauth:'. |
required | |
**kwargs
|
any of the options TwitchBot takes, see https://archangelic.github.io/pinhook/latest/twitch/ |
{}
|
Saved data and settings¶
Store ¶
Bases: dict
A plugin's saved data: a dict that's kept between messages, reloads and restarts.
Plugins get theirs as msg.store. The bot saves it after each plugin call
if anything in it changed, nested changes included.
Values have to be things JSON can hold: strings, numbers, lists, dicts, True, False and None. Keys are saved as strings.
save_if_changed ¶
save_if_changed()
Save the store if anything in it changed since it was last saved.
PluginConfig ¶
Bases: Mapping
A plugin's settings from plugin_config in the bot's config. Read only.
Plugins get theirs as msg.config: their own section, keyed by plugin file
name, and msg.config.shared for the section every plugin can read.
Testing¶
TestBot ¶
Bases: Bot
A Bot that never connects, for testing plugins.
Plugins, ops, bans and the built-in commands all work as they do on a
real server. What the bot sends is recorded in sent instead, and a
plugin that raises an exception fails the test with a PluginError.
say ¶
say(text, nick='tester', channel=None, **who)
Send a message to a channel as nick, and return the bot's replies there.
who can be user, host and account, to test ops and bans by hostmask or account.
action ¶
action(text, nick='tester', channel=None, **who)
Send a /me action to a channel as nick, and return the bot's replies there.
private ¶
private(text, nick='tester', **who)
Send a private message to the bot as nick, and return the bot's replies to them.
sent_to ¶
sent_to(target)
Every message and action the bot has sent to target, like a nick for !help.
PluginError ¶
Bases: Exception
A plugin raised an exception, or returned something it shouldn't.
Deprecated¶
register ¶
register(command, help_text='N/A')
Deprecated, will be removed in 2.0. Use command instead.