2021-01-10 13:10:39 +00:00
|
|
|
# xbotlib
|
|
|
|
|
2021-01-10 18:23:21 +00:00
|
|
|
[![PyPI version](https://badge.fury.io/py/xbotlib.svg)](https://badge.fury.io/py/xbotlib)
|
2021-01-10 18:24:20 +00:00
|
|
|
[![Build Status](https://drone.autonomic.zone/api/badges/decentral1se/xbotlib/status.svg?ref=refs/heads/main)](https://drone.autonomic.zone/decentral1se/xbotlib)
|
2021-01-10 18:23:21 +00:00
|
|
|
|
2021-01-10 13:10:39 +00:00
|
|
|
## XMPP bots for humans
|
|
|
|
|
2021-01-10 18:17:10 +00:00
|
|
|
> status: experimental
|
2021-01-10 15:54:55 +00:00
|
|
|
|
2021-01-10 18:17:10 +00:00
|
|
|
A friendly lightweight wrapper around
|
|
|
|
[slixmpp](https://slixmpp.readthedocs.io/) for writing XMPP bots in Python. The
|
2021-01-10 18:35:39 +00:00
|
|
|
goal is to make writing and running XMPP bots easy and fun. `xbotlib` is a
|
|
|
|
[single file implementation](./xbotlib.py) which can easily be understood and
|
|
|
|
extended. It provides a small API surface which reflects the `slixmpp` way of
|
|
|
|
doing things.
|
2021-01-10 15:54:55 +00:00
|
|
|
|
2021-01-10 13:10:39 +00:00
|
|
|
## Install
|
|
|
|
|
|
|
|
```sh
|
|
|
|
$ pip install xbotlib
|
|
|
|
```
|
|
|
|
|
|
|
|
## Example
|
|
|
|
|
2021-01-13 13:31:00 +00:00
|
|
|
Put the following in a `echo.py` file. `xbotlib` provides a number of example
|
|
|
|
bots which you can use to get moving fast and try things out.
|
2021-01-10 18:35:39 +00:00
|
|
|
|
2021-01-10 13:10:39 +00:00
|
|
|
```python
|
2021-01-13 13:08:44 +00:00
|
|
|
from xbotlib import EchoBot
|
2021-01-10 13:10:39 +00:00
|
|
|
|
2021-01-13 13:08:44 +00:00
|
|
|
EchotBot()
|
2021-01-10 13:10:39 +00:00
|
|
|
```
|
|
|
|
|
2021-01-10 18:17:10 +00:00
|
|
|
And then `python echo.py`. You will be asked a few questions like which account
|
2021-01-10 18:35:39 +00:00
|
|
|
details your bot will be using.
|
|
|
|
|
|
|
|
This will generate a `bot.conf` file in the same working directory for further use.
|
2021-01-10 13:10:39 +00:00
|
|
|
|
2021-01-13 13:08:44 +00:00
|
|
|
Here's the code for the `EchoBot`.
|
|
|
|
|
|
|
|
```python
|
|
|
|
class EchoBot(Bot):
|
2021-01-13 20:56:45 +00:00
|
|
|
def direct(self, message):
|
|
|
|
self.reply(message.body, to=message.sender)
|
2021-01-13 13:51:07 +00:00
|
|
|
|
2021-01-13 20:56:45 +00:00
|
|
|
def group(self, message):
|
|
|
|
if "echobot" in message.body:
|
|
|
|
self.reply(message.body.split(":")[-1], room=message.room)
|
2021-01-13 13:08:44 +00:00
|
|
|
```
|
|
|
|
|
2021-01-13 20:56:45 +00:00
|
|
|
Read more in the [API reference](#api-reference) for how to write your own bots.
|
|
|
|
|
2021-01-13 13:08:44 +00:00
|
|
|
## All examples
|
2021-01-10 13:10:39 +00:00
|
|
|
|
2021-01-13 13:08:44 +00:00
|
|
|
- **EchoBot**: Sends back what you sent it
|
2021-01-14 18:12:09 +00:00
|
|
|
- **WhisperBot**: Anonymous whispering in group chats
|
2021-01-10 14:09:42 +00:00
|
|
|
|
2021-01-13 13:08:44 +00:00
|
|
|
See [xbotlib.py](./xbotlib.py) for all example bots.
|
2021-01-10 15:51:20 +00:00
|
|
|
|
|
|
|
## API Reference
|
|
|
|
|
2021-01-13 20:56:45 +00:00
|
|
|
When writing your own bot, you always sub-class the `Bot` class provided from
|
|
|
|
`xbotlib`. Then if you want to respond to a direct message, you write a
|
|
|
|
[direct](#botdirectmessage) function. If you want to respond to a group chat
|
|
|
|
message, you write a [group](#botgroupmessage) function.
|
2021-01-10 15:51:20 +00:00
|
|
|
|
2021-01-13 20:56:45 +00:00
|
|
|
### Bot.direct(message)
|
2021-01-10 16:00:38 +00:00
|
|
|
|
2021-01-13 20:56:45 +00:00
|
|
|
Respond to direct messages.
|
2021-01-10 16:00:38 +00:00
|
|
|
|
|
|
|
Arguments:
|
|
|
|
|
2021-01-13 20:56:45 +00:00
|
|
|
- **message**: received message (see [SimpleMessage](#simplemessage) below for available attributes)
|
2021-01-10 16:00:38 +00:00
|
|
|
|
2021-01-13 20:56:45 +00:00
|
|
|
### Bot.group(message)
|
2021-01-10 15:51:20 +00:00
|
|
|
|
2021-01-13 20:56:45 +00:00
|
|
|
Respond to a message in a group chat.
|
2021-01-10 15:51:20 +00:00
|
|
|
|
|
|
|
Arguments:
|
|
|
|
|
2021-01-13 20:56:45 +00:00
|
|
|
- **message**: received message (see [SimpleMessage](#simplemessage) below for available attributes)
|
2021-01-10 15:51:20 +00:00
|
|
|
|
2021-01-13 20:56:45 +00:00
|
|
|
### SimpleMessage
|
2021-01-10 16:00:38 +00:00
|
|
|
|
2021-01-13 20:56:45 +00:00
|
|
|
A simple message interface.
|
2021-01-10 16:00:38 +00:00
|
|
|
|
|
|
|
Attributes:
|
|
|
|
|
2021-01-10 18:17:10 +00:00
|
|
|
- **body**: the body of the message
|
2021-01-13 13:51:23 +00:00
|
|
|
- **sender**: the user the message came from
|
|
|
|
- **room**: the room the message came from
|
2021-01-13 13:30:46 +00:00
|
|
|
- **receiver**: the receiver of the message
|
2021-01-10 18:17:10 +00:00
|
|
|
- **nickname**: the nickname of the sender
|
|
|
|
- **type**: the type of message (`chat` or `groupchat`)
|
2021-01-10 16:00:38 +00:00
|
|
|
|
2021-01-12 20:39:50 +00:00
|
|
|
## Configure your bot
|
|
|
|
|
|
|
|
### Using the environment
|
|
|
|
|
|
|
|
You can pass the `--no-input` option to your script invocation (e.g. `python bot.py --no-input`).
|
|
|
|
|
|
|
|
`xbotlib` will try to read the following configuration values from the environment.
|
|
|
|
|
2021-01-13 13:08:25 +00:00
|
|
|
- **XBOT_JID**: The username of the bot account
|
|
|
|
- **XBOT_PASSWORD**: The password of the bot account
|
|
|
|
- **XBOT_NICK**: The nickname that the bot uses
|
2021-01-12 20:39:50 +00:00
|
|
|
|
2021-01-10 15:51:20 +00:00
|
|
|
## Roadmap
|
|
|
|
|
2021-01-10 18:38:19 +00:00
|
|
|
See the [issue tracker](https://git.autonomic.zone/decentral1se/xbotlib/issues).
|
2021-01-10 15:51:20 +00:00
|
|
|
|
|
|
|
## Changes
|
|
|
|
|
|
|
|
See the [CHANGELOG.md](./CHANGELOG.md).
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
|
|
See the [LICENSE](./LICENSE.md).
|