1 files changed, 100 insertions, 25 deletions
diff --git a/examples/echo_client.py b/examples/echo_client.py
index 5e6314f0..e6266ec4 100644..100755
--- a/examples/echo_client.py
+++ b/examples/echo_client.py
@@ -1,54 +1,129 @@
 #!/usr/bin/env python
-# coding=utf8
+# -*- coding: utf-8 -*-
 
-import sleekxmpp
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2010  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+import sys
 import logging
-from optparse import OptionParser
 import time
+from optparse import OptionParser
 
-import sys
+import sleekxmpp
 
+# Python versions before 3.0 do not use UTF-8 encoding
+# by default. To ensure that Unicode is handled properly
+# throughout SleekXMPP, we will set the default encoding
+# ourselves to UTF-8.
 if sys.version_info < (3,0):
     reload(sys)
     sys.setdefaultencoding('utf8')
 
 
-class Example(sleekxmpp.ClientXMPP):
+class EchoBot(sleekxmpp.ClientXMPP):
+
+    """
+    A simple SleekXMPP bot that will echo messages it
+    receives, along with a short thank you message.
+    """
 
     def __init__(self, jid, password):
         sleekxmpp.ClientXMPP.__init__(self, jid, password)
+
+        # The session_start event will be triggered when
+        # the bot establishes its connection with the server
+        # and the XML streams are ready for use. We want to
+        # listen for this event so that we we can intialize
+        # our roster.
         self.add_event_handler("session_start", self.start)
+
+        # The message event is triggered whenever a message
+        # stanza is received. Be aware that that includes
+        # MUC messages and error messages.
         self.add_event_handler("message", self.message)
 
     def start(self, event):
+        """
+        Process the session_start event.
+
+        Typical actions for the session_start event are
+        requesting the roster and broadcasting an intial
+        presence stanza.
+
+        Arguments:
+            event -- An empty dictionary. The session_start
+                     event does not provide any additional
+                     data.
+        """
         self.getRoster()
         self.sendPresence()
 
     def message(self, msg):
+        """
+        Process incoming message stanzas. Be aware that this also
+        includes MUC messages and error messages. It is usually
+        a good idea to check the messages's type before processing
+        or sending replies.
+
+        Arguments:
+            msg -- The received message stanza. See the documentation
+                   for stanza objects and the Message stanza to see
+                   how it may be used.
+        """
         msg.reply("Thanks for sending\n%(body)s" % msg).send()
 
+
 if __name__ == '__main__':
-    #parse command line arguements
+    # Setup the command line arguments.
     optp = OptionParser()
-    optp.add_option('-q','--quiet', help='set logging to ERROR', action='store_const', dest='loglevel', const=logging.ERROR, default=logging.INFO)
-    optp.add_option('-d','--debug', help='set logging to DEBUG', action='store_const', dest='loglevel', const=logging.DEBUG, default=logging.INFO)
-    optp.add_option('-v','--verbose', help='set logging to COMM', action='store_const', dest='loglevel', const=5, default=logging.INFO)
-    optp.add_option("-j","--jid", dest="jid", help="JID to use")
-    optp.add_option("-p","--password", dest="password", help="password to use")
-    opts,args = optp.parse_args()
-
-    logging.basicConfig(level=opts.loglevel, format='%(levelname)-8s %(message)s')
-    xmpp = Example(opts.jid, opts.password)
-    xmpp.registerPlugin('xep_0030')
-    xmpp.registerPlugin('xep_0004')
-    xmpp.registerPlugin('xep_0060')
-    xmpp.registerPlugin('xep_0199')
-
-    # use this if you don't have pydns, and want to
-    # talk to GoogleTalk (e.g.)
-    if xmpp.connect(('talk.google.com', 5222)):
-    #khif xmpp.connect():
+
+    # Output verbosity options.
+    optp.add_option('-q','--quiet', help='set logging to ERROR',
+                    action='store_const', dest='loglevel',
+                    const=logging.ERROR, default=logging.INFO)
+    optp.add_option('-d','--debug', help='set logging to DEBUG',
+                    action='store_const', dest='loglevel',
+                    const=logging.DEBUG, default=logging.INFO)
+    optp.add_option('-v','--verbose', help='set logging to COMM',
+                    action='store_const', dest='loglevel',
+                    const=5, default=logging.INFO)
+
+    # JID and password options.
+    optp.add_option("-j", "--jid", dest="jid",
+                    help="JID to use")
+    optp.add_option("-p", "--password", dest="password",
+                    help="password to use")
+
+    opts, args = optp.parse_args()
+
+    # Setup logging.
+    logging.basicConfig(level=opts.loglevel,
+                        format='%(levelname)-8s %(message)s')
+
+    # Setup the EchoBot and register plugins. Note that while plugins may
+    # have interdependencies, the order in which you register them does
+    # not matter.
+    xmpp = EchoBot(opts.jid, opts.password)
+    xmpp.registerPlugin('xep_0030') # Service Discovery
+    xmpp.registerPlugin('xep_0004') # Data Forms
+    xmpp.registerPlugin('xep_0060') # PubSub
+    xmpp.registerPlugin('xep_0199') # XMPP Ping
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the pydns library installed, you will need
+        # to manually specify the name of the server if it does not match
+        # the one in the JID. For example, to use Google Talk you would
+        # need to use:
+        #
+        # if xmpp.connect(('talk.google.com', 5222)):
+        #     ...
         xmpp.process(threaded=False)
-        print("done")
+        print("Done")
     else:
         print("Unable to connect.")