mirror of
https://github.com/jlu5/PyLink.git
synced 2024-11-01 01:09:22 +01:00
docs/: Start work on writing-plugins.md, improvements to example plugin
This commit is contained in:
parent
0610783479
commit
7625268732
@ -5,7 +5,7 @@ Any documentation here is provided for reference only.
|
||||
|
||||
### Introduction
|
||||
|
||||
PyLink aims to be a modular, plugin-based IRC PseudoService framework. It uses swappable protocol modules and a hook-based system for calling plugins, allowing them to function regardless of the IRCd used.
|
||||
PyLink is an a modular, plugin-based IRC PseudoService framework. It uses swappable protocol modules and a hook-based system for calling plugins, allowing them to function regardless of the IRCd used.
|
||||
|
||||
<img src="core-structure.png" width="50%" height="50%">
|
||||
|
||||
|
@ -1,5 +1,4 @@
|
||||
# plugin_example.py: An example PyLink plugin.
|
||||
# You can add copyright notices and license information here.
|
||||
|
||||
# These two lines add PyLink's root directory to the PATH, so that importing things like
|
||||
# 'utils' and 'log' work.
|
||||
@ -24,6 +23,8 @@ import random
|
||||
def hook_privmsg(irc, source, command, args):
|
||||
channel = args['target']
|
||||
text = args['text']
|
||||
# irc.pseudoclient stores the IrcUser object of the main PyLink client.
|
||||
# (i.e. the user defined in the bot: section of the config)
|
||||
if utils.isChannel(channel) and irc.pseudoclient.nick in text:
|
||||
utils.msg(irc, channel, 'hi there!')
|
||||
log.info('%s said my name on channel %s (PRIVMSG hook caught)' % (source, channel))
|
||||
@ -37,6 +38,9 @@ utils.add_hook(hook_privmsg, 'PRIVMSG')
|
||||
# source: The UID/numeric of the calling user.
|
||||
# args: A list of command args (excluding the command name) that the command was called with.
|
||||
def randint(irc, source, args):
|
||||
# The docstring here is used as command help by the 'help' command, and formatted using the
|
||||
# same line breaks as the raw string. You shouldn't make this text or any one line too long,
|
||||
# to prevent flooding users or getting long lines cut off.
|
||||
"""[<min>] [<max>]
|
||||
Returns a random number between <min> and <max>. <min> and <max> default
|
||||
to 1 and 10 respectively, if both aren't given."""
|
||||
@ -47,8 +51,8 @@ def randint(irc, source, args):
|
||||
rmin, rmax = 1, 10
|
||||
n = random.randint(rmin, rmax)
|
||||
utils.msg(irc, source, str(n))
|
||||
# You can also bind a command function multiple times, to different command names via a
|
||||
# second argument. Note that no checking is done at the moment to prevent multiple
|
||||
# plugins from binding to the same command names (the older command just gets replaced
|
||||
# by the new one!)
|
||||
# You can also bind a command function multiple times, and/or to different command names via a
|
||||
# second argument.
|
||||
# Note: no checking is done at the moment to prevent multiple plugins from binding to the same
|
||||
# command name. The older command just gets replaced by the new one!
|
||||
utils.add_cmd(randint, "random")
|
||||
|
49
docs/technical/writing-plugins.md
Normal file
49
docs/technical/writing-plugins.md
Normal file
@ -0,0 +1,49 @@
|
||||
# Writing plugins for PyLink
|
||||
|
||||
PyLink plugins are modules that extend its functionality by giving it something to do. Without any plugins loaded, PyLink can only sit on a server and do absolutely nothing.
|
||||
|
||||
This guide, along with the sample plugin [`plugin-example.py`](plugin-example.py), aim to show the basics of writing plugins for PyLink.
|
||||
|
||||
### Receiving data from IRC
|
||||
|
||||
Plugins have three main ways of communicating with IRC: hooks, WHOIS handlers, and commands sent in PM to the main PyLink client. A simple plugin can use one, or any mixture of these.
|
||||
|
||||
### Hooks
|
||||
|
||||
Hooks are probably the most versatile form of communication. Each hook payload is formatted as a Python `dict`, with different data keys depending on the command.
|
||||
For example, a `PRIVMSG` payload would give you the fields `target` and `text`, while a `PART` payload would only give you `channels` and `reason` fields.
|
||||
|
||||
There are many hook types available (one for each supported IRC command), and you can read more about them in the [PyLink hooks reference](hooks-reference.md).
|
||||
|
||||
Plugins can bind to hooks using the `utils.add_hook()` function like so: `utils.add_hook(function_name, 'PRIVMSG')`, where `function_name` is your function definition, and `PRIVMSG` is whatever hook name you want to bind to. Once set up, `function_name` will be called whenever the protocol module receives a `PRIVMSG` command.
|
||||
|
||||
Each hook-bound function takes 4 arguments: `irc, source, command, args`.
|
||||
- **irc**: The IRC object where the hook was called. Plugins are globally loaded, so there will be one of these per network.
|
||||
- **source**: The numeric of the sender. This will usually be a UID (for users) or a SID (for server).
|
||||
- **command**: The true command name where the hook originates. This may or may not be the same as the name of the hook, depending on context.
|
||||
- **args**: The hook data (a `dict`) associated with the command. Again, the available data keys differ by hook name
|
||||
(see the [hooks reference](hooks-reference.md) for a list of which can be used).
|
||||
|
||||
Hook functions do not return anything, and can raise exceptions to be caught by the core.
|
||||
|
||||
### PyLink commands
|
||||
|
||||
For plugins that interact with IRC users, there is also the option of binding to PM commands.
|
||||
|
||||
Commands are bound to using the `utils.add_cmd()` function: `utils.add_cmd(testcommand, "hello")`. Here, `testcommand` is the name of your function, and `hello` is the (optional) name of the command to bind to; if it is not specified, it'll use the same name as the function.
|
||||
Now, your command function will be called whenever someone PMs the PyLink client with the command (e.g. `/msg PyLink hello`, case-insensitive).
|
||||
|
||||
Each command function takes 3 arguments: `irc, source, args`.
|
||||
- **irc**: The IRC object where the command was called.
|
||||
- **source**: The numeric of the sender. This will usually be a UID (for users) or a SID (for server).
|
||||
- **args**: A `list` of space-separated command args (excluding the command name) that the command was called with. For example, `/msg PyLink hello world 1234` would give an `args` list of `['world', '1234']`
|
||||
|
||||
Command handlers do not return anything, and can raise exceptions to be caught by the core.
|
||||
|
||||
### WHOIS handlers
|
||||
|
||||
The third option, `WHOIS` handlers, are a lot more limited compared to the other options. They are solely used for `WHOIS` replies, **and only work on IRCds where WHOIS commands are sent to remote servers!** This includes Charybdis and UnrealIRCd, but **not** InspIRCd, which handles all `WHOIS` requests locally (the only thing sent between servers is an IDLE time query).
|
||||
|
||||
WHOIS replies are special in that any plugins wishing to add lines to a WHOIS reply must do so after the regular WHOIS lines (handled by the core), but before a special "End of WHOIS" line. This means that the regular hooks mechanism, which are only called after core handling, won't work here.
|
||||
|
||||
\- section under construction -
|
Loading…
Reference in New Issue
Block a user