mirror of
https://github.com/jlu5/PyLink.git
synced 2024-12-18 08:02:51 +01:00
48aab1cf16
- Rewrite lead section to be more concise - Move to snake case method names - Consistently use the terms "services" and "service bots" [skip ci]
63 lines
3.3 KiB
Markdown
63 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
```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.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.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 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:
|
|
|
|
```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)`.
|