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-10 18:35:39 +00:00
|
|
|
Put the following in a `echo.py` file.
|
|
|
|
|
2021-01-10 13:10:39 +00:00
|
|
|
```python
|
|
|
|
from xbotlib import Bot
|
|
|
|
|
|
|
|
class EchoBot(Bot):
|
2021-01-10 18:17:10 +00:00
|
|
|
def react(self, message):
|
|
|
|
if message.type == "chat":
|
2021-01-10 18:41:56 +00:00
|
|
|
self.reply(message.body, to=message.sender)
|
2021-01-10 13:10:39 +00:00
|
|
|
|
|
|
|
MyBot()
|
|
|
|
```
|
|
|
|
|
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-10 14:09:42 +00:00
|
|
|
## More Examples
|
2021-01-10 13:10:39 +00:00
|
|
|
|
2021-01-10 14:09:42 +00:00
|
|
|
- **[EchoBot](./examples/echo.py)**: Sends back what you sent it
|
|
|
|
- **[WhisperBot](./examples/whisper.py)**: Pseudo-anonymous whispering in group chats
|
|
|
|
|
|
|
|
See the [examples](./examples/) directoy for all listings.
|
2021-01-10 15:51:20 +00:00
|
|
|
|
|
|
|
## API Reference
|
|
|
|
|
|
|
|
Your bot always sub-classes the `Bot` class provided from `xbotlib`. All
|
|
|
|
underling functions can be extended. For example, if you want to enable more
|
2021-01-10 18:26:30 +00:00
|
|
|
plugins or add different functionality. If something feels awkward then please
|
2021-01-10 15:56:39 +00:00
|
|
|
raise a ticket for that. Seamlessness is still a bitch but we're trying anyway.
|
2021-01-10 15:51:20 +00:00
|
|
|
|
2021-01-10 18:41:56 +00:00
|
|
|
> Bot.react(message)
|
2021-01-10 16:00:38 +00:00
|
|
|
|
|
|
|
A function which you define in your bot implementation in order to respond to
|
2021-01-10 18:17:10 +00:00
|
|
|
chat messages. You can respond to both direct messages and group chat messages
|
|
|
|
in this function by checking the `message.type` which can be either `chat` or
|
|
|
|
`groupchat`.
|
2021-01-10 16:00:38 +00:00
|
|
|
|
|
|
|
Arguments:
|
|
|
|
|
|
|
|
- **message**: sent message and metadata (see [message](#message) reference below)
|
|
|
|
|
2021-01-10 18:41:56 +00:00
|
|
|
> Bot.reply(body, to=None, room=None)
|
2021-01-10 15:51:20 +00:00
|
|
|
|
|
|
|
Send back a response to a direct chat message.
|
|
|
|
|
|
|
|
Arguments:
|
|
|
|
|
2021-01-10 18:44:15 +00:00
|
|
|
- **body**: the message to send
|
2021-01-10 18:17:10 +00:00
|
|
|
- **to**: which user account to reply to (direct chat)
|
|
|
|
- **room**: which room to reply to (group chat)
|
2021-01-10 15:51:20 +00:00
|
|
|
|
2021-01-13 13:00:59 +00:00
|
|
|
> SimpleMessage
|
2021-01-10 16:00:38 +00:00
|
|
|
|
2021-01-10 18:41:56 +00:00
|
|
|
A simple message format. This is the type that you work with when your function
|
|
|
|
accepts a `message` argument.
|
2021-01-10 16:00:38 +00:00
|
|
|
|
|
|
|
Attributes:
|
|
|
|
|
2021-01-10 18:17:10 +00:00
|
|
|
- **body**: the body of the message
|
|
|
|
- **sender**: the sender of the message
|
|
|
|
- **receive**: the receive of the message
|
|
|
|
- **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_ROOM**: The room that the bot can join
|
|
|
|
- **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).
|