mirror of
https://github.com/jlu5/PyLink.git
synced 2024-11-01 09:19:23 +01:00
docs: tweak writing-plugins & TOC, move plugin_example to plugins
Closes #226.
This commit is contained in:
parent
aea6657a8b
commit
a0d20df899
@ -23,3 +23,4 @@ PyLink is an a modular, plugin-based IRC services framework. It uses swappable p
|
||||
### Future topics (not yet available)
|
||||
- [Writing tests for PyLink modules](writing-tests.md)
|
||||
- [Supported named user modes](user-modes.csv)
|
||||
- [Services bot API/Creating your own service bots](services-api.md)
|
||||
|
@ -2,7 +2,7 @@
|
||||
|
||||
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.
|
||||
This guide, along with the sample plugins [`plugins/example.py`](../../plugins/example.py), and [`plugins/service.py`](../../plugins/demo_service.py) aim to show the basics of writing plugins for PyLink.
|
||||
|
||||
## Receiving data from IRC
|
||||
|
||||
@ -28,7 +28,7 @@ Hook functions do not return anything, and can raise exceptions to be caught by
|
||||
|
||||
### Bot commands
|
||||
|
||||
For plugins that interact with regular users, you can simply write commands for the PyLink bot.
|
||||
For plugins that interact with regular users, you can also write commands for the PyLink bot, or [create service bots with their own command set](services-api.md). This section only details the former:
|
||||
|
||||
Plugins can add commands by including something like `utils.add_cmd(testcommand, "hello")`. Here, `testcommand` is the name of your function, and `hello` is the (optional) name of the command. If no command name is specified, it will 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).
|
||||
@ -42,7 +42,7 @@ Each command function takes 3 arguments: `irc, source, args`.
|
||||
|
||||
Command handlers do not return anything and can raise exceptions, which are caught by the core and automatically return an error message.
|
||||
|
||||
### Sending data to IRC
|
||||
## Sending data to IRC
|
||||
|
||||
Plugins receive data from the underlying protocol module, and communicate back using outgoing [command functions](pmodule-spec.md) implemented by the protocol module. They should *never* send raw data directly back to IRC, because that wouldn't be portable across different IRCds.
|
||||
|
||||
|
@ -1,4 +1,4 @@
|
||||
# plugin_example.py: An example PyLink plugin.
|
||||
# example.py: An example PyLink plugin.
|
||||
|
||||
# These two lines add PyLink's root directory to the PATH, so that importing things like
|
||||
# 'utils' and 'log' work.
|
||||
@ -23,11 +23,15 @@ 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:
|
||||
irc.msg(channel, 'hi there!')
|
||||
# log.debug, log.info, log.warning, log.error, log.exception (within except: clauses)
|
||||
# and log.critical are supported here.
|
||||
log.info('%s said my name on channel %s (PRIVMSG hook caught)' % (source, channel))
|
||||
|
||||
utils.add_hook(hook_privmsg, 'PRIVMSG')
|
||||
|
||||
|
||||
@ -41,7 +45,11 @@ 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>]
|
||||
|
||||
# The same applies to message replies in general: plugins sending long strings of text should
|
||||
# be wary that long messages can get cut off. Automatic word-wrap may be added in the future:
|
||||
# https://github.com/GLolol/PyLink/issues/153
|
||||
"""[<min> <max>]
|
||||
Returns a random number between <min> and <max>. <min> and <max> default
|
||||
to 1 and 10 respectively, if both aren't given."""
|
||||
try:
|
||||
@ -58,6 +66,4 @@ def randint(irc, source, args):
|
||||
|
||||
# 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")
|
Loading…
Reference in New Issue
Block a user