From b98555c512ddb7452c9a217b1024b9e3163dea99 Mon Sep 17 00:00:00 2001 From: Lance Stout Date: Thu, 18 Aug 2011 16:32:06 -0700 Subject: Update the README Now includes how to generate the docs, run tests, and the basic boilerplate for Sleek based projects. --- README.rst | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/README.rst b/README.rst index dc29b639..a8b69ac9 100644 --- a/README.rst +++ b/README.rst @@ -66,6 +66,84 @@ help with SleekXMPP. **Chat** `sleek@conference.jabber.org `_ +Documentation and Testing +------------------------- + +Documentation can be found both inline in the code, and as a Sphinx project in ``/docs``. +To generate the Sphinx documentation, follow the commands below. The HTML output will +be in ``docs/_build/html``:: + + cd docs + make html + open _build/html/index.html + +To run the test suite for SleekXMPP:: + + python testall.py + + +The SleekXMPP Boilerplate +------------------------- + +Projects using SleekXMPP tend to follow a basic pattern for setting up client/component +connections and configuration. Here is the gist of the boilerplate needed for a SleekXMPP +based project. See the documetation or examples directory for more detailed archetypes for +SleekXMPP projects:: + + import logging + + from sleekxmpp import ClientXMPP + from sleekxmpp.exceptions import IqError, IqTimeout + + + class EchoBot(ClientXMPP): + + def __init__(self, jid, password): + ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + self.add_event_handler("message", self.message) + + def start(self, event): + self.send_presence() + + # Most get_* methods from plugins use Iq stanzas, which + # can generate IqError and IqTimeout exceptions + try: + self.get_roster() + except IqError as err: + logging.error('There was an error getting the roster') + logging.error(err.iq['error']['condition']) + self.disconnect() + except IqTimeout: + logging.error('Server is taking too long to respond') + self.disconnect() + + def message(self, msg): + if msg['type'] in ('chat', 'normal'): + msg.reply("Thanks for sending\n%(body)s" % msg).send() + + + if __name__ == '__main__': + # Ideally use optparse or argparse to get JID, + # password, and log level. + + logging.basicConfig(level=logging.DEBUG, + format='%(levelname)-8s %(message)s') + + xmpp = EchoBot('somejid@example.com', 'use_getpass') + xmpp.register_plugin('xep_0030') # Service Discovery + xmpp.register_plugin('xep_0199') # XMPP Ping + + # If you are working with an OpenFire server, you will need + # to useuterborg Larsson version: + # xmppissl_version = ssl.PROTOCOL_SSLv3 + + if xmpp.connect(): + xmpp.process(block=True) + else: + print("Unable to connect.") + Credits ------- -- cgit v1.2.3