ff

This is the first part of a tutorial in which we will learn how to use Python and Twisted for making Jabber services. Besides showing how to use the great Twisted support for XMPP, the tutorial will embrace few aspects that go beyond instant messaging and that could make Jabber the backbone of the real time Internet:

• data forms

• an initial implementation of ad hoc commands
  

• transport of RSS and Atom feeds in XMPP stanzas

Moreover we will also learn something about Twisted and databases, in particular embedded databases such as SQLite and the object based ZopeDB.

In order to follow this tutorial you need some basic knowledge of Python and Twisted.

In this first installation we take a look at the basics of twisted.words.protocols.jabber, and we will write our first Jabber client. The examples will use the code from the xmpp-subprotocols branch of Twisted, which is far better than the code in trunk. In order to obtain it issue the following command and then run setup.py:

svn co svn://svn.twistedmatrix.com/svn/Twisted/branches/xmpp-subprotocols-2178-2

The business logic of XMPP clients is implemented as an XMPPHandler, an object that has the xmlstream attribute allowing to send packets and to register observers for receiving incoming stanzas. This object is notified when the connection is ready and the client has been successfully authenticated by calling the connectionInitialized() method. This is an example of the code needed for starting listening to presence stanzas:

from twisted.words.protocols.jabber import xmlstream

class GMailChecker(xmlstream.XMPPHandler):

    def connectionInitialized(self):
        self.xmlstream.addObserver(
            "/presence",
            self.got_presence
        )

    def got_presence(self):
        pass

Form the example you can that all you need for receiving packets is ti register an “observer” using an XPath query. Therefore got_presence will be called each time a stanza whose root element is /presence is received. Easy isn't it? No need to write receiving threads or complex state machines for taking in account all the possible packets. Just register the observers for the stanzas you are interested in and you will be called when a packet is ready. All the observers are also thread safe, since basically there aren't threads: in most cases you can live (a better life) without them. I haven't written “all cases” just because there still exist some limited situations in which you need some thread, and we will consider also them in this tutorial.

And what about sending packets? It's as easy as receiving them. The xmlstream attribute has a send() method allowing you sending chunks of XML. You can build those chunks with the Element objects supplied by the twisted.words.xish.domish package. Here is the code for building a message and sending it:

 def connectionInitialized(self):

        .... 

        msg = Element(("jabber:client", "message"))
        msg["to"] = "ff@jabber.bluendo.com"
        body = msg.addElement("body", content = "Hi Fabio!")
        self.xmlstream.send(msg)

Now we know the very basics for handling an XMPP connection, but we still need to create it. Twisted will take care of all the details, we just need to tell it to start connecting and use our handler once logged in. In order to accomplish this, we need three objects (in this aspect Twisted is a bit complicated, but the separation of roles that is introduced gives a lot flexibility): a factory for building a client xml stream, the manager of handlers for associating them to the stream, and Internet client for physically connecting to the server. Here is the resulting code:

 if __name__ == "__main__":
    from twisted.words.protocols.jabber import client, jstrports
    from twisted.words.protocols.jabber.jid import JID
    from twisted.internet import reactor

    jid = JID("xxx@jabber.bluendo.com")
    cf = client.XMPPClientFactory(jid, "xxx")
    sm = xmlstream.StreamManager(cf)
    sm.addHandler(GMailChecker())

    client_svc = jstrports.client("tcp:%s:5222"%("jabber.bluendo.com"), cf)
    client_svc.startService()
    reactor.run()

Just replace the jabber id and the password with your account, and you be able to login and send you message. Here you may find the full code of the example: http://www.bluendo.com/~fabio/tutorial/part1.py

In the next installation we will improve our client, making it a bit more Twisted like and we will start adding some functionality.