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-15 17:21:41 +00:00
|
|
|
The `xbotlib` source code and ideas are largely
|
|
|
|
borrowed/stolen/adapted/reimagined from the XMPP bot experiments that have gone
|
2021-01-15 17:22:24 +00:00
|
|
|
on and are still going on in
|
|
|
|
[Varia](https://git.vvvvvvaria.org/explore/repos?tab=&sort=recentupdate&q=bots).
|
2021-01-15 17:21:41 +00:00
|
|
|
|
2021-01-10 13:10:39 +00:00
|
|
|
## Install
|
|
|
|
|
|
|
|
```sh
|
|
|
|
$ pip install xbotlib
|
|
|
|
```
|
|
|
|
|
|
|
|
## Example
|
|
|
|
|
2021-01-14 21:26:13 +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-14 21:26:13 +00:00
|
|
|
And then `python echo.py`. You will be asked a few questions in order to load
|
|
|
|
the account details that your bot will be using. This will generate a
|
2021-01-15 10:27:50 +00:00
|
|
|
`echobot.conf` file in the same working directory for further use. See the
|
2021-01-14 21:26:13 +00:00
|
|
|
[configuration](#configure-your-bot) section for more.
|
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):
|
2021-01-16 16:39:05 +00:00
|
|
|
self.reply(message.text, to=message.sender)
|
2021-01-13 20:56:45 +00:00
|
|
|
def group(self, message):
|
2021-01-16 16:39:05 +00:00
|
|
|
self.reply(message.content, 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-16 16:39:18 +00:00
|
|
|
- **GlossBot**: Building a shared glossary together
|
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-16 16:39:18 +00:00
|
|
|
- **text**: the entire text of the message
|
|
|
|
- **content**: the text of the message after the nick
|
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-16 16:39:18 +00:00
|
|
|
- **nick**: the nickname of the sender
|
|
|
|
- **type**: the type of message
|
2021-01-10 16:00:38 +00:00
|
|
|
|
2021-01-14 22:45:23 +00:00
|
|
|
## Documenting your bot
|
|
|
|
|
|
|
|
Add a `help = "my help"` to your `Bot` class like so.
|
|
|
|
|
|
|
|
```python
|
|
|
|
class MyBot(Bot):
|
|
|
|
help = "My help"
|
|
|
|
```
|
|
|
|
|
2021-01-15 10:27:50 +00:00
|
|
|
See more in the [commands](#commands) section on how to use this.
|
2021-01-14 22:45:23 +00:00
|
|
|
|
2021-01-15 10:27:50 +00:00
|
|
|
## Commands
|
|
|
|
|
2021-01-16 16:39:18 +00:00
|
|
|
Using `!<command>` in direct messages and `<nick>, @<command>` in group chats,
|
2021-01-15 10:27:50 +00:00
|
|
|
here are the supported commands.
|
|
|
|
|
2021-01-16 16:39:18 +00:00
|
|
|
- **@uptime**: how long the bot has been running
|
|
|
|
- **@help**: the help text for what the bot does
|
2021-01-14 22:45:23 +00:00
|
|
|
|
2021-01-15 17:24:07 +00:00
|
|
|
There are also more general status commands which all bots respond to.
|
|
|
|
|
2021-01-16 16:39:18 +00:00
|
|
|
- **@bots**: status check on who is a bot in the group chat
|
2021-01-15 17:24:07 +00:00
|
|
|
|
2021-01-15 10:08:07 +00:00
|
|
|
## Avatars
|
|
|
|
|
2021-01-15 10:27:50 +00:00
|
|
|
By default, `xbotlib` will look for an `avatar.png` (so far tested with `.png`
|
|
|
|
but other file types may work) file alongside your Python script which contains
|
|
|
|
your bot implementation. You can also specify another path using the `--avatar`
|
|
|
|
option on the command-line interface. The images should ideally have a height
|
|
|
|
of `64` and a width of `64` pixels each.
|
2021-01-15 10:08:07 +00:00
|
|
|
|
2021-01-12 20:39:50 +00:00
|
|
|
## Configure your bot
|
|
|
|
|
2021-01-14 21:26:13 +00:00
|
|
|
All the ways you can pass configuration details to your bot.
|
|
|
|
|
2021-01-15 10:27:50 +00:00
|
|
|
### Using the `.conf` configuration file
|
2021-01-12 20:39:50 +00:00
|
|
|
|
2021-01-14 21:26:13 +00:00
|
|
|
If you run simply run your Python script which contains the bot then `xbotlib`
|
|
|
|
will generate a configuration for you by asking a few questions. This is the
|
|
|
|
simplest way to run your bot locally.
|
|
|
|
|
|
|
|
### Using the command-line interface
|
|
|
|
|
|
|
|
Every bot accepts a number of comand-line arguments to load configuration. You
|
|
|
|
can use the `--help` option to see what is available (e.g. `python bot.py --help`).
|
|
|
|
|
|
|
|
### Using the environment
|
2021-01-12 20:39:50 +00:00
|
|
|
|
2021-01-14 21:26:13 +00:00
|
|
|
`xbotlib` will try to read the following configuration values from the
|
|
|
|
environment if it cannot read them from a configuration file or the
|
|
|
|
command-line interface. This can be useful when doing remote server
|
|
|
|
deployments.
|
2021-01-12 20:39:50 +00:00
|
|
|
|
2021-01-14 21:26:13 +00:00
|
|
|
- **XBOT_ACCOUNT**: The bot account
|
|
|
|
- **XBOT_PASSWORD**: The bot password
|
|
|
|
- **XBOT_NICK**: The bot nickname
|
2021-01-16 18:59:09 +00:00
|
|
|
- **XBOT_AVATAR**: The bot avatar icon
|
2021-01-16 19:21:22 +00:00
|
|
|
- **XBOT_REDIS_URL**: Redis key store connection URL
|
2021-01-12 20:39:50 +00:00
|
|
|
|
2021-01-15 14:52:12 +00:00
|
|
|
## Deploy your bots
|
|
|
|
|
|
|
|
See [bots.varia.zone](https://bots.varia.zone/).
|
|
|
|
|
2021-01-15 20:13:17 +00:00
|
|
|
## Persistent storage
|
|
|
|
|
2021-01-16 19:21:22 +00:00
|
|
|
## Redis key/value storage
|
2021-01-15 20:13:17 +00:00
|
|
|
|
|
|
|
`xbotlib` supports using [Redis](https://redis.io/) as a storage back-end. It
|
2021-01-16 19:21:22 +00:00
|
|
|
is simple to work with because the interface is exactly like a dictionary. You
|
|
|
|
can quickly run Redis locally using
|
|
|
|
[Docker](https://docs.docker.com/engine/install/debian/) or if you're on a
|
|
|
|
Debian system you can also `sudo apt install -y redis`.
|
2021-01-15 20:13:17 +00:00
|
|
|
|
|
|
|
```bash
|
|
|
|
$ docker run --network=host --name redis -d redis
|
2021-01-16 19:21:22 +00:00
|
|
|
$ export XBOT_REDIS_URL=redis://localhost:6379/0
|
2021-01-15 20:13:17 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
And you access the interface via the `self.db` attribute.
|
|
|
|
|
|
|
|
```python
|
|
|
|
def direct(self, message):
|
2021-01-16 19:21:22 +00:00
|
|
|
self.db["mykey"] = message.text
|
2021-01-15 20:13:17 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
You should see `INFO Successfully connected to storage` when your bot
|
|
|
|
initialises. Please see the `GlossBot` example for more on how to work with
|
|
|
|
this type of storage.
|
|
|
|
|
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).
|