Preface.

English is not my native language. If you see any bugs in this text, please, let me know.

Basic

Introduction.

This documents topic is for people who want to quickly try xmpppy for a simple task, like writing a command-line script for sending a single message.

Writing a simple script

This example demonstrates a simple script that sends message to one recipient. Example:

xsend test@jabber.org Hello there!

You don't have a similar tool in your toolkit? Using the xmpppy library it can be created easily.
What? Already have one? Hmm. Maybe you want to simplify things a bit, or just curious how to do it one more way? Anyway - let's start now!
First - we declare ourself as a python script and importing needed modules:

#!/usr/bin/python
import sys,os,xmpp

After it we have to check if we have enough arguments on the command-line:

if len(sys.argv) < 2:
    print "Syntax: xsend JID text"
    sys.exit(0)

After it we must decode arguments. Omitting all checks to simplify our script:

tojid=sys.argv[1]
text=' '.join(sys.argv[2:])

One more non-jabber step: We have to to get our Jabber ID and login details. Presuming that all info stored in ~/.xsend file:

jidparams={}
if os.access(os.environ['HOME']+'/.xsend',os.R_OK):
    for ln in open(os.environ['HOME']+'/.xsend').readlines():
        key,val=ln.strip().split('=',1)
        jidparams[key.lower()]=val
for mandatory in ['jid','password']:
    if mandatory not in jidparams.keys():
        open(os.environ['HOME']+'/.xsend','w').write('#JID=romeo@montague.net\n#PASSWORD=juliet\n')
        print 'Please ensure the ~/.xsend file has valid JID for sending messages.'
        sys.exit(0)

Phew! The most complex (non-jabber ;) ) part is finished. From now on we have to:

• connect to jabber server
• authenticate ourselves
• submit a message

Let's start:
0. To connect we must have a client instance. Calculating our server name and creating Client class instance for it:

jid=xmpp.protocol.JID(jidparams['jid'])
cl=xmpp.Client(jid.getDomain(),debug=[])

1. Connect and authenticate with credentials from the config file.

cl.connect()
cl.auth(jid.getNode(),jidparams['password'])

2. We can go online now (by sending the inital presence) but will not do that, as it is not nessessary for sending a message. So we send a message now!

#cl.sendInitialPresence()
cl.send(xmpp.protocol.Message(tojid,text))

We're done! The session must now be closed but since we have not registered disconnect handler we will just leave it to python and TCP/IP layer. All jabber servers that I know handle such disconnects correctly.
You can download this script here.

What now?

If you were impressed of how the things were done with xmpppy, you may be interested in more thorough examination of xmpppy library. The "advanced" and "expert" parts of this document are here to help you.
"Advanced" (isn't writed yet) part is much like another tutorial and describing common principles of XMPP usage via xmpppy prism. It describes ideas that are the foundation of XML handling with the simplexml library, the essence of dispatcher's work and how messages are processed, and some guidelines to write more complex programs and uses of the library.
"Expert" part is full library API description documentation. This is epydoc generated output - all info is taken from the xmpppy code so you can re-generate it at any time.