mirror of
https://github.com/jlu5/PyLink.git
synced 2024-11-01 17:29:21 +01:00
7892e37bfa
- Add advanced-service-config to TOC - Move "matching SERVICE name" note to docs/t/services-api.md - Various wording / grammar tweaks
63 lines
3.2 KiB
Markdown
63 lines
3.2 KiB
Markdown
# 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:
|
|
|
|
```python
|
|
|
|
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](../advanced-services-config.md) 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:
|
|
|
|
```python
|
|
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)`.
|