PyLink/docs/technical/services-api.md

PyLink Services Bot API

The goal of PyLink’s Services API is to make writing custom services slightly easier. This API automatically creates service bots, handles rejoin on kill/kick, and exposes a simple way for plugins to bind commands to bots. It also handles U-line servprotect modes when enabled and available.

Creating new service bots

Services can be registered and created 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.register_service() returns a utils.ServiceBot instance, which can also be found
# by calling world.services["myservice"].
myservice = utils.register_service("myservice", desc=desc)

utils.register_service() 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.
• default_nick - Sets the default nick this service should use if the user doesn’t provide it. Defaults to the same as 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.register_service("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 service bots will automatically join the autojoin channels configured for a specific network, if any.

However, plugins can persistently join service 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 service bots that they’ve created. A simple example would be in the games plugin:

def die(irc=None):
    utils.unregister_service('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).