Welcome to Botibal’s documentation!¶
A silly, quizzical XMPP bot based on the SliXMPP (3.4+) library.
Installation¶
Botibal is currently compatible with Python 3.4 and 3.5, and has been tested on Linux.
With pip & virtualenv (recommended)¶
To install Botibal in a Python virtualenv (here with Python 3.5 as the default interpreter):
# create a new virtualenv
$ virtualenv /path/to/envs/botibal
# activate the virtualenv
$ source /path/to/envs/botibal/bin/activate
# install botibal
(botibal) $ pip install botibal
# check which packages have been installed
(botibal) $ pip freeze
aiodns==1.0.1
botibal==0.7.5
pyasn1==0.1.9
pyasn1-modules==0.0.8
slixmpp==1.1
To specify a Python interpreter:
# create a new Python 3 virtualenv
$ virtualenv -p /usr/bin/python3.4 /path/to/envs/botibal3
# activate the virtualenv
$ source /path/to/envs/botibal3/bin/activate
# install botibal
(botibal3) $ pip install botibal
# check which packages have been installed
(botibal3) $ pip freeze
aiodns==1.0.0
botibal==0.7.5
pyasn1==0.1.9
pyasn1-modules==0.0.8
pycares==1.0.0
slixmpp==1.1
wheel==0.24.0
From the sources¶
To install Botibal from the latest source revision and install it in a dedicated virtualenv:
# fetch the sources
$ git clone https://github.com/virtualtam/botibal
$ cd botibal
# create and activate a new virtualenv
$ virtualenv /path/to/botibal-src
$ source /path/to/botibal-src/bin/activate
# upgrade pip (required to read requirements attributes)
(botibal-src) $ pip install -U pip
# build and install
(botibal-src) $ make install
# check which packages have been installed
(botibal3) $ pip freeze
aiodns==1.0.0
botibal==0.7.5
pyasn1==0.1.9
pyasn1-modules==0.0.8
pycares==1.0.0
slixmpp==1.1
wheel==0.24.0
Configuration¶
Botibal relies on a simple INI file to hold its configuration. An example configuration file is provided in the sources.
Example configuration file¶
For the bot to work properly, a configuration file must be created:
- it can be located anywhere on the disk,
- it will be passed as a mandatory argument when running a bot (see Usage),
- it holds connection and administration information (JIDs, MUC).
config.example.ini¶[auth]
jid=imahbot@lulzse.cx
password=OhGoshWhereAreTheKeys?
[muc]
room=1408@skyr.im
admin_jid=thecat@saw.it
[nick]
botibal=Botibal
minibal=Minibal
quizzibal=Quizzibal
XMPP bots¶
MiniBal, the minimalist bot¶
- connects to a groupchat,
- answers to plopping:
<user>: plop <bot>=><bot>: plop <user>, - allows to taunt users!
- gives the current date and time.
Botibal, the silly, Fukung-addict-bot¶
- all of MiniBal’s features,
- stores links to fukung.net images,
- knows basic text ciphering (currently, ROT13).
Quizzibal, the quizzical bot¶
- all of MiniBal’s features,
- quizz sessions!
- quizz handling: start/stop, display scores, manage questions.
Usage¶
Start the bot¶
Run with no arguments to get the help string:
$ botibal [-h] [-d] (-b | -m | -q) config_file database_file
positional arguments:
config_file configuration file
database_file data storage file
optional arguments:
-h, --help show this help message and exit
-d, --debug set logging to DEBUG
-b, --botibal BotiBal, the Fukung-addict bot
-m, --minibal MiniBal, the minimalist bot
-q, --quizzibal QuizziBal, the quizzical bot
To start MiniBal:
$ botibal -m ~/botibal/config.ini ~/botibal/botibal.db
Chat commands¶
The available commands depend on which bot is running, and are split as follows:
- MUC - command execution (say/display something);
- PM - bot admin:
- add, delete and list elements,
- change bot status,
- send instructions that will result in the bot sending messages to the MUC.
The bots’ internal command interface is derived from argparse, interaction is thus very similar to running programs from the command-line (see the Examples section).
Once the bot is online and connected to a groupchat, you can:
- get help for MUC commands
- list all available commands:
<bot_nick>: -h - get help for a given command:
<bot_nick>: <command> -h
- list all available commands:
- execute MUC commands:
<bot_nick>: command [args] - get help for PM commands:
- list all available commands:
-h - get help for a given command:
<command> -h
- list all available commands:
- execute PM commands:
command [args]
Examples¶
MUC interaction (MiniBal)¶
<Hans> plop Minibal
<Minibal> plop Hans
[...]
<Hans> Minibal: -h
<Minibal>
usage: Minibal: [-h] {say,time} ...
positional arguments:
{say,time,taunt}
say say something
time
[...]
<Hans> Minibal: say -h
<Minibal>
usage: Minibal: say [-h] text [text ...]
positional arguments:
text
[...]
<Hans> Minibal: say hello, world!
<Minibal> hello, world!
PM interaction (MiniBal)¶
<Hans> -h
<Minibal>
usage: Minibal: [-h] {say,time,quit,taunt} ...
positional arguments:
{say,time,quit,taunt}
say say something
time
quit tells the bot to stop
taunt manage taunts
[...]
<Hans> taunt add programming, do you speak it, mofo?
<Hans> taunt --list
<Minibal>
1 - programming, do you speak it, mofo? (Hans)
Developer resources¶
See also:
Requirements¶
To install production and test dependencies:
(botibal) $ pip install -r requirements/tests.txt
To install production, test and development dependencies:
(botibal) $ pip install -r requirements/development.txt