<commit_before># 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 services

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.
- `extra_channels` - Defines a dict mapping network names to a set of channels that the bot should autojoin on that network.
- `desc` - Sets the command description of the service. This is shown in the default HELP command if enabled.

### 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(...)`<commit_msg>services-api.md: remove extra_channels argument per d31d09ce7ec1b3be8062e5e18f3572832f7f50b7<commit_after># 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 services

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.

### 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(...)`
{'fraction_non_alphanumeric': 0.0731790333560245, 'fraction_numerical': 0.005616065350578625, 'mean_word_length': 4.778761061946903, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5370835', 'n_tokens_mistral': 1557, 'n_tokens_neox': 1502, 'n_words': 790}