Overview

= Djabot - (NOT only) Django Jabber Bot =

Djabot provides a standalone Jabber (XMPP) client (bot) that executes any commands it receives as Jabber messages.

A command is either:

  • first word of a Jabber message, or
  • a JSON object of a Jabber message.

JSON object MUST contain property "action" that MUST contain a bot command of the same name.

The code was originally written as a Django command called "djabotd" that provides djabot.Client implementation that can run as a daemon.

You can also use djabot.Client in a standalone mode (ie. pure Python solution).

See "httplike_json_api_bot.py" for example Python script.

Djabot was crafted by Marek Kuziel <marek@tracklr.com> as a part of tracklr [real-time time tracker] project, which you can find at http://tracklr.com/

For full list of contributors see AUTHORS.txt

You can view "Djabot - Python Jabber Bot"; a presentation about Djabot at

http://www.slideshare.net/marekkuziel/djabot-python-jabber-bot

Or download it at

http://tracklr.com/tm/presentations/tracklr-djabot.pdf

== Installation ==

=== Get Djabot ===

Mercurial repository and latest version of Djabot can be found at

http://bitbucket.org/vshivak/djabot/

or you can download ready-to-use dev eggs (tgz) from Djabot's pypi directory

http://bitbucket.org/vshivak/djabot/src/tip/pypi/

=== setuptools/easy_install ===

$ easy_install djabot-2.2.tar.gz

=== PIP ===

$ pip install djabot-2.2.tar.gz

=== virtualenv ===

{{{
$ mkvirtualenv djabot (djabot) $ easy_install djabot-2.2.tar.gz (djabot) $ cp lib/python2.6/site-packages/djabot-2.2-py2.6.egg/djabot/httplike_json_api_bot.py . (djabot) $ python httplike_json_api_bot.py djabot@yourexamplejabberserver.com YOURBOTSPASSWORD

}}}

=== virtualenv + buildout + django + djabot = djabotd ===

Create new virtualenv, bootstrap buildout, build django with djabot and run your own daemon..

{{{
$ mkvirtualenv djabotd (djabot) $ cdvirtualenv (djabot) $ wget http://svn.zope.org/checkout/zc.buildout/trunk/bootstrap/bootstrap.py (djabot) $ python bootstrap.py

}}}

Create buildout.cfg for buildout

{{{ [buildout] find-links = http://bitbucket.org/vshivak/djabot/raw/tip/pypi/djabot-2.2.tar.gz eggs = djabot parts = django [django] recipe = djangorecipe version = 1.3 eggs = ${buildout:eggs} }}}

To project/settings.py file add 'djabot' to INSTALLED_APPS and also add and configure DJABOT settings

{{{ INSTALLED_APPS += ('djabot',)

# DJABOT

from local import *

DJABOT_BASE_DIR = LOCAL_DJABOT_BASE_DIR DJABOT_PID_FILE = LOCAL_DJABOT_PID_FILE DJABOT_DAEMONIZE = LOCAL_DJABOT_DAEMONIZE DJABOT_JID = LOCAL_DJABOT_JID DJABOT_PASSWORD = LOCAL_DJABOT_PASSWORD DJABOT_USE_TLS = LOCAL_DJABOT_USE_TLS DJABOTD_USER = LOCAL_DJABOTD_USER DJABOTD_GROUP = LOCAL_DJABOTD_GROUP DJABOTD_ACCESS_LOG = LOCAL_DJABOTD_ACCESS_LOG DJABOTD_ERROR_LOG = LOCAL_DJABOTD_ERROR_LOG

DJABOTS = [
'djabot.bots.httplike_json_api', ]
def djabot_auth(sender):
"""Handles authentication for djabot bots; checks whether command sender is an active Jabber Account. """ return True

DJABOT_AUTH = djabot_auth }}}

Add project/local.py with local settings for the environment

{{{ LOCAL_DJABOT_BASE_DIR = '/path/to/.virtualenvs/djabotd' LOCAL_DJABOT_PID_FILE = '/path/to/.virtualenvs/djabotd/djabot.pid' LOCAL_DJABOT_DAEMONIZE = True LOCAL_DJABOT_JID = 'djabot@yourexamplejabberserver.com' LOCAL_DJABOT_PASSWORD = 'super secret password phrase' LOCAL_DJABOT_USE_TLS = 'tls_noverify' # False, tls_noverify, or path to CA cert file LOCAL_DJABOTD_USER = 'djabotusername' LOCAL_DJABOTD_GROUP = 'djabotgroup' LOCAL_DJABOTD_ACCESS_LOG = '/path/to/.virtualenvs/djabotd/djabot.log' LOCAL_DJABOTD_ERROR_LOG = '/path/to/.virtualenvs/djabotd/djabot.elog' }}}

Once builtout.cfg is created and settings added you can run buildout and then run your daemon

{{{
(djabotd) $ buildout -v (djabotd) $ django djabotd start (djabotd) $ tail -f djabot.log

}}}

=== required libraries ===

libxml2-python (troubleshooting)

# find-path = ftp://xmlsoft.org/libxml2/python/libxml2-python-2.6.21.tar.gz easy_install ftp://xmlsoft.org/libxml2/python/libxml2-python-2.6.21.tar.gz

== Settings ==

=== Basic Settings ===

You need a dedicated Jabber account (DJABOT_JID) with password (DJABOT_PASSWORD) to be able to start your own instance of djabot.

If you choose a Jabber account with TLS support, you will need to set (DJABOT_USE_TLS) to True.

Hint: Google's GTalk supports TLS

Example settings:

>>> DJABOT_JID = 'my-djabot-jabber-account@my-jabber-server.example.net'
>>> DJABOT_PASSWORD = 'very secret password for my Jabber bot account'
>>> DJABOT_USE_TLS = False

=== Bot Settings ===

You can run as many bots as you like in your djabot instance as long as their commands do not clash (ie. two bots contain the same command, in which case first command found out those two would be executed). See TODOS.txt for more information.

Example bot settings:

>>> DJABOTS = [
>>>     'djabot.bots.httplike_json_api',
>>>     ]

=== Auth Settinggs ===

DJABOT_AUTH is setting that contains a custom function that performs authentication of JIDs that send messages to bot. Based on returned boolean value of "auth_check" Djabot decided whether JID that sent the message is allowed to talk to the bot.

>>> def djabot_auth(sender):
>>>     """Handles authentication for djabot bots; checks whether command sender is an active Jabber
>>>     Account.
>>>     """
>>>     try:
>>>         from djauthy.models import Account
>>>         j = Account.objects.get(account=sender, account_type='Jabber', active=True)
>>>         return True
>>>     except Account.DoesNotExist:
>>>         return False
>>>
>>> DJABOT_AUTH = djabot_auth