PyLink/docs/technical/services-api.md

PyLink Services Bot API

Starting with PyLink 0.9.x, a services bot API was introduced to make writing custom services slightly easier. PyLink’s Services API automatically connects service bots, and handles rejoin on kick/kill all by itself, meaning less code is needed per plugin to have functional service bots.

Creating new service bots

Services can be created (registered) using code similar to the following in a plugin:

from pylinkirc import utils, world

# Description is optional (though recommended), and usually around a sentence or two.
desc = "Optional description of servicenick, in sentence form."

# First argument is the internal service name.
# utils.registerService() returns a utils.ServiceBot instance, which can also be found
# by calling world["myservice"].
myservice = utils.registerService("myservice", desc=desc)

utils.registerService() passes its arguments directly to the utils.ServiceBot class constructor, which in turn supports the following options:

• name - defines the service name (mandatory)
• default_help - Determines whether the default HELP command should be used for the service. Defaults to True.
• default_list - Determines whether the default LIST command should be used for the service. Defaults to True.
• nick, ident - Sets the default nick and ident for the service bot. If not given, these simply default to the service name.
• manipulatable - Determines whether the bot is marked manipulatable. Only manipulatable clients can be force joined, etc. using PyLink commands. Defaults to False.
• desc - Sets the command description of the service. This is shown in the default HELP command if enabled.

NOTE: It is a good practice for the SERVICE name in utils.registerService("SERVICE") to match your plugin name, as the service bot API implicitly loads configuration options from config blocks named SERVICE:.

Getting the UID of a bot

Should you want to get the UID of a service bot on a specific server, use myservice.uids.get('irc.name')

Setting channels to join

All services bots will automatically join the autojoin channels configured for a specific network, if any.

However, plugins can persistently join services bots to specific channels by calling myservice.join(irc, channels). To manually add/remove channels from the service’s autojoin list, modify the myservice.extra_channels set.

Removing services on unload

All plugins using the services API MUST have a die() function that unregisters all services that they’ve created. A simple example would be in the games plugin:

def die(irc):
    utils.unregisterService('games')

Service bots and commands

Commands for service bots and commands for the main PyLink bot have two main differences.

1. Commands for service bots are bound using myservice.add_cmd(cmdfunc, 'cmdname') instead of utils.add_cmd(...)

2. Replies for service bot commands are sent using myservice.reply(irc, text) instead of irc.reply(...)

Featured commands

Commands for service bots can also be marked as featured, which shows it with its command arguments in the default LIST command. To mark a command as featured, use myservice.add_cmd(cmdfunc, 'cmdname', featured=True).