Another pass on the docs
Added a TOC!
This commit is contained in:
parent
d87cd98b4e
commit
bee31b2126
98
README.md
98
README.md
@ -12,13 +12,32 @@ A friendly lightweight wrapper around
|
||||
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.
|
||||
|
||||
The `xbotlib` source code and ideas are largely
|
||||
doing things. The `xbotlib` source code and ideas are largely
|
||||
borrowed/stolen/adapted/reimagined from the XMPP bot experiments that have gone
|
||||
on and are still going on in
|
||||
[Varia](https://git.vvvvvvaria.org/explore/repos?tab=&sort=recentupdate&q=bots).
|
||||
|
||||
- [Install](#install)
|
||||
- [Example](#example)
|
||||
- [API Reference](#api-reference)
|
||||
- [Bot.direct(message)](#botdirect-message-)
|
||||
- [Bot.group(message)](#botgroup-message-)
|
||||
- [SimpleMessage](#simplemessage)
|
||||
- [Documenting your bot](#documenting-your-bot)
|
||||
- [Commands](#commands)
|
||||
- [Avatars](#avatars)
|
||||
- [Configure your bot](#configure-your-bot)
|
||||
- [Using the `.conf` configuration file](#using-the--conf--configuration-file)
|
||||
- [Using the command-line interface](#using-the-command-line-interface)
|
||||
- [Using the environment](#using-the-environment)
|
||||
- [Persistent storage](#persistent-storage)
|
||||
- [Redis key/value storage](#redis-key-value-storage)
|
||||
- [Loading Plugins](#loading-plugins)
|
||||
- [Deploy your bots](#deploy-your-bots)
|
||||
- [Roadmap](#roadmap)
|
||||
- [Changes](#changes)
|
||||
- [license](#license)
|
||||
|
||||
## Install
|
||||
|
||||
```sh
|
||||
@ -27,10 +46,10 @@ $ pip install xbotlib
|
||||
|
||||
## Example
|
||||
|
||||
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.
|
||||
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. This bot is the
|
||||
simplest one we have: it simply echoes back whatever message you send it. It is
|
||||
an easy way to get started.
|
||||
|
||||
```python
|
||||
from xbotlib import EchoBot
|
||||
@ -39,36 +58,48 @@ EchotBot()
|
||||
```
|
||||
|
||||
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
|
||||
the account details that your bot will be using. This will generate an
|
||||
`echobot.conf` file in the same working directory for further use. See the
|
||||
[configuration](#configure-your-bot) section for more.
|
||||
|
||||
Here's the code for the `EchoBot`.
|
||||
Here's the annotated source for the `EchoBot`.
|
||||
|
||||
```python
|
||||
from xbotlib import Bot
|
||||
|
||||
# Define a class and inherit from xbotlib.Bot
|
||||
class EchoBot(Bot):
|
||||
|
||||
# Respond to direct messages using the `direct` function
|
||||
def direct(self, message):
|
||||
# Send back the entire text of the message using `message.text`
|
||||
self.reply(message.text, to=message.sender)
|
||||
|
||||
# Respond to group chat messages using the `group` function
|
||||
def group(self, message):
|
||||
# Send back the content of the message. In this case if we were
|
||||
# sent `echobot, hoi` in the group chat then the `message.content`
|
||||
# would be equal to `hoi`
|
||||
self.reply(message.content, room=message.room)
|
||||
```
|
||||
|
||||
Read more in the [API reference](#api-reference) for how to write your own bots.
|
||||
|
||||
## All examples
|
||||
A numer of other example bots are provided.
|
||||
|
||||
- **EchoBot**: Sends back what you sent it
|
||||
- **WhisperBot**: Anonymous whispering in group chats
|
||||
- **GlossBot**: Building a shared glossary together
|
||||
|
||||
See [xbotlib.py](./xbotlib.py) for all example bots.
|
||||
See [xbotlib.py](./xbotlib.py) for the sources.
|
||||
|
||||
## API Reference
|
||||
|
||||
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.
|
||||
message, you write a [group](#botgroupmessage) function. That's it for the
|
||||
basics.
|
||||
|
||||
### Bot.direct(message)
|
||||
|
||||
@ -113,7 +144,9 @@ See more in the [commands](#commands) section on how to use this.
|
||||
|
||||
## Commands
|
||||
|
||||
Using `@<command>` in direct messages and `<nick>, @<command>` in group chats,
|
||||
Using `@<command>` in direct messages and `<nick>, @<command>` (the `,` is
|
||||
optional, anything will be accepted here and there doesn't seem to be a
|
||||
consensus on what is most common way to "at" another user in XMPP) in group chats,
|
||||
here are the supported commands.
|
||||
|
||||
- **@uptime**: how long the bot has been running
|
||||
@ -133,7 +166,10 @@ of `64` and a width of `64` pixels each.
|
||||
|
||||
## Configure your bot
|
||||
|
||||
All the ways you can pass configuration details to your bot.
|
||||
All the ways you can pass configuration details to your bot. There are three
|
||||
ways to configure your bot, the configuration file, command-line interface and
|
||||
the environment. Use whichever one suits you best. The values are loaded in the
|
||||
following order: command-line > configuration file > environment.
|
||||
|
||||
### Using the `.conf` configuration file
|
||||
|
||||
@ -156,6 +192,30 @@ rooms = test@muc.example.com
|
||||
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`).
|
||||
|
||||
```
|
||||
usage: bot.py [-h] [-d] [-a ACCOUNT] [-p PASSWORD] [-n NICK]
|
||||
[-av AVATAR] [-ru REDIS_URL] [-r ROOMS [ROOMS ...]]
|
||||
[--no-auto-join]
|
||||
|
||||
XMPP bots for humans
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
-d, --debug Enable verbose debug logs
|
||||
-a ACCOUNT, --account ACCOUNT
|
||||
Account for the bot account
|
||||
-p PASSWORD, --password PASSWORD
|
||||
Password for the bot account
|
||||
-n NICK, --nick NICK Nickname for the bot account
|
||||
-av AVATAR, --avatar AVATAR
|
||||
Avatar for the bot account
|
||||
-ru REDIS_URL, --redis-url REDIS_URL
|
||||
Redis storage connection URL
|
||||
-r ROOMS [ROOMS ...], --rooms ROOMS [ROOMS ...]
|
||||
Rooms to automatically join
|
||||
--no-auto-join Disable automatically joining rooms when invited
|
||||
```
|
||||
|
||||
### Using the environment
|
||||
|
||||
`xbotlib` will try to read the following configuration values from the
|
||||
@ -177,12 +237,14 @@ deployments.
|
||||
|
||||
`xbotlib` supports using [Redis](https://redis.io/) as a storage back-end. It
|
||||
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`.
|
||||
can quickly run Redis locally using [Docker](https://docs.docker.com/engine/install/debian/)
|
||||
(`docker run --network=host --name redis -d redis`) or if you're on a Debian system you can
|
||||
also `sudo apt install -y redis`.
|
||||
|
||||
You can configure the connection URL using the command-line interface,
|
||||
configuration or environment. Here is an example using the environment.
|
||||
|
||||
```bash
|
||||
$ docker run --network=host --name redis -d redis
|
||||
$ export XBOT_REDIS_URL=redis://localhost:6379/0
|
||||
```
|
||||
|
||||
|
||||
@ -174,7 +174,7 @@ class Bot(ClientXMPP):
|
||||
"-a",
|
||||
"--account",
|
||||
dest="account",
|
||||
help="Account for the bot account (foo@example.com)",
|
||||
help="Account for the bot account",
|
||||
)
|
||||
self.parser.add_argument(
|
||||
"-p",
|
||||
|
||||
Reference in New Issue
Block a user