|
1 month ago | |
---|---|---|
.drone.yml | 1 month ago | |
.gitignore | 1 month ago | |
CHANGELOG.md | 1 month ago | |
LICENSE | 1 month ago | |
README.md | 1 month ago | |
poetry.lock | 1 month ago | |
pyproject.toml | 1 month ago | |
test_xbotlib.py | 1 month ago | |
xbotlib.py | 1 month ago |
status: experimental
A friendly lightweight wrapper around
slixmpp for writing XMPP bots in Python. The
goal is to make writing and running XMPP bots easy and fun. xbotlib
is a
single file implementation which can easily be understood and
extended. The xbotlib
source code and ideas are largely borrowed from the
XMPP bot experiments going on in
Varia.
$ pip install xbotlib
Put the following in a echo.py
file. This bot echoes back whatever message
you send it in both direct messages and group messages. In group chats, you
need to message the bot directly (e.g. echobot: hi
) (see the commands
section for more).
from xbotlib import Bot
class EchoBot(Bot):
def direct(self, message):
self.reply(message.text, to=message.sender)
def group(self, message):
self.reply(message.content, room=message.room)
EchoBot()
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 an
echobot.conf
file in the same working directory for further use. See the
configuration section for more.
That's it! If you want to go further, continue reading here.
The following sections try to cover all the ways you can configure and extend
your bot using xbotlib
. If anything is unclear, please let us know on the
chat.
Add a help = "my help"
to your Bot
class like so.
class MyBot(Bot):
help = """This is my cool help.
I can list some commands too:
@foo - some command
"""
Your bot will then respond to mybot: @help
invocations. This string can be a
multi-line string with indentation. xbotlib
will try to format this sensibly
for showing in chat clients.
See more in the commands section for more.
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@help
: the help text for what the bot doesThere are also more general status commands which all bots respond to.
@bots
: status check on who is a bot in the group chatThese commands will be detected in any part of the message sent to the bot. So
you can write echobot, can we see your @uptime
, or I'd love to know which @bots are here.
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.
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. This means you can override everything from the command-line easily.
.conf
configuration fileIf 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.
avatar.png
)False
)index.html.j2
)False
)8080
)file
)./
)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
).
avatar.png
)False
)8080
)index.html.j2
)False
)file
)./
)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.
avatar.png
)False
)index.html.j2
)False
)8080
)file
)./
)In order to store data you can make use of the self.db
attribute of the Bot
class. It is a Python dictionary which will be saved to disk automatically for
you as a <nick>.json
in your current working directory. The name and path to
this file can be configured using the output option (e.g. python bot.py --output /var/www/html
)
def group(self, message):
if not message.room in self.db.keys():
self.db[message.room] = "visited"
If you want to inspect the database when the bot is not running, you can look in the file directly.
$ cat <nick>.json
For more advanced use cases, xbotlib
also supports Redis
as a storage back-end. You'll need to configure this (e.g. --storage redis
)
as the default uses the filesystem approach mentioned above. The same self.db
will then be passed as a Redis connection object. You will also need to install
additional dependencies using pip install xbotlib[redis]
.
You can specify a plugins = [...]
on your bot definition and they will be
automatically loaded when you start your bot.
class MyBot(Bot):
plugins = ["xep_0066"]
See here for the list of supported plugins.
Firstly, you'll need to install additional dependencies.
$ pip install xbotlib[web]
Your bot will run a web server if you configure it to do so. Use the --serve
option on the command-line, the serve = True
configuration option or the
XBOT_SERVE=True
environment variable.
If you're running your bot locally, just visit 0.0.0.0:8080 to see. The default response is just some placeholder text. You can write your own responses using the Bot.serve function.
xbotlib
provides a small wrapper API for
Jinja2 which allows you to
easily template and generate HTML. The web server is provided by
aiohttp.
The default template search path is index.html.j2
in the current working
directory. This can be configured through the usual configuration entrypoints.
Here's a small example that renders a random ASCII letter and uses a stylesheet.
index.html.j2
<html>
<head>
<style> h1 { color: red; } </style>
</head>
<body>
<h1>{{ letter }}</h1>
</body>
</html>
bot.py
from string import ascii_letters
async def serve(self, request):
letter = choice(ascii_letters)
rendered = self.template.render(letter=letter)
return self.respond(rendered)
Please note the use of the return
keyword here. The serve
function must
return a response that will be passed to the web server. Also, the async
keyword. This function can handle asynchronous operations and must be marked as
such. You can return any content type that you might find on the web (e.g.
HTML, XML, JSON, audio and maybe even video) but you must specify the
content_type=...
keyword argument for respond
.
See the list of available content types for more.
If you want to pass data from your direct
/group
functions to the serve
function, you'll need to make use of some type of persistent
storage. Your serve
function can read from the storage
back-end and then respond. This is usually as simple as accessing the self.db
attribute.
As long as the --no-auto-join
option is not set (via the configuration file
or environment also), then your bot will automatically join any room it is
invited to. Rooms that your bot has been invited to will be stored in the
.xbotlib/data.json
file. If your bot is turned off or fails for some reason
then it will read this file when turned back on to see what rooms it should
re-join automatically. The data.json
file can be edited freely by hand.
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 function. If you want to respond to a group chat
message, you write a group function. That's it for the
basics.
Respond to direct messages.
Arguments:
Respond to a message in a group chat.
Arguments:
Serve requests via the built-in web server.
See this section for more.
Arguments:
Register additional routes for web serving.
See this section for more.
This is an advanced feature. Use self.web.add_routes
.
from aiohttp.web import get
def routes(self):
self.web.add_routes([get("/foo", self.foo)])
Run some setup logic before starting your bot.
A simple message interface.
Attributes:
Bot.reply(message, to=None, room=None)
Send a reply back.
Arguments:
Bot.respond(response, content_type="text/html")
Return a response via the web server.
Arguments:
Other useful attributes on the Bot
class are:
We're lurking in xbotlibtest@muc.vvvvvvaria.org if you want to chat or just invite your bots for testing.
See more examples on git.vvvvvvaria.org.
See bots.varia.zone.
See the issue tracker.
See the CHANGELOG.md.
See the LICENSE.
Any and all contributions most welcome! Happy to hear how you use the library or what could be improved from a usability perspective.
To test, install Tox (pip install tox
) and run tox
to run the test suite locally.