README.rst

   1 SleekXMPP
   2 #########
   3
   4 SleekXMPP is an MIT licensed XMPP library for Python 2.6/3.1+,
   5 and is featured in examples in
   6 `XMPP: The Definitive Guide <http://oreilly.com/catalog/9780596521271>`_
   7 by Kevin Smith, Remko Tronçon, and Peter Saint-Andre. If you've arrived
   8 here from reading the Definitive Guide, please see the notes on updating
   9 the examples to the latest version of SleekXMPP.
  10
  11 SleekXMPP's design goals and philosphy are:
  12
  13 **Low number of dependencies**
  14     Installing and using SleekXMPP should be as simple as possible, without
  15     having to deal with long dependency chains.
  16
  17     As part of reducing the number of dependencies, some third party
  18     modules are included with SleekXMPP in the ``thirdparty`` directory.
  19     Imports from this module first try to import an existing installed
  20     version before loading the packaged version, when possible.
  21
  22 **Every XEP as a plugin**
  23     Following Python's "batteries included" approach, the goal is to
  24     provide support for all currently active XEPs (final and draft). Since
  25     adding XEP support is done through easy to create plugins, the hope is
  26     to also provide a solid base for implementing and creating experimental
  27     XEPs.
  28
  29 **Rewarding to work with**
  30     As much as possible, SleekXMPP should allow things to "just work" using
  31     sensible defaults and appropriate abstractions. XML can be ugly to work
  32     with, but it doesn't have to be that way.
  33
  34
  35 Get the Code
  36 ------------
  37
  38 Get the latest stable version from PyPI::
  39
  40     pip install sleekxmpp
  41
  42 The latest source code for SleekXMPP may be found on `Github
  43 <http://github.com/fritzy/SleekXMPP>`_. Releases can be found in the
  44 ``master`` branch, while the latest development version is in the
  45 ``develop`` branch.
  46
  47 **Stable Releases**
  48     - `1.0 RC3 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC3>`_
  49     - `1.0 RC2 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC2>`_
  50     - `1.0 RC1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC1>`_
  51     - `1.0 Beta6.1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta6.1>`_
  52     - `1.0 Beta5 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta5>`_
  53     - `1.0 Beta4 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta4>`_
  54     - `1.0 Beta3 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta3>`_
  55     - `1.0 Beta2 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta2>`_
  56     - `1.0 Beta1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta1>`_
  57
  58 **Develop Releases**
  59     - `Latest Develop Version <http://github.com/fritzy/SleekXMPP/zipball/develop>`_
  60
  61 Installing DNSPython
  62 ---------------------
  63 If you are using Python3 and wish to use dnspython, you will have to checkout and
  64 install the ``python3`` branch::
  65
  66     git clone http://github.com/rthalley/dnspython
  67     cd dnspython
  68     git checkout python3
  69     python3 setup.py install
  70
  71 Discussion
  72 ----------
  73 A mailing list and XMPP chat room are available for discussing and getting
  74 help with SleekXMPP.
  75
  76 **Mailing List**
  77     `SleekXMPP Discussion on Google Groups <http://groups.google.com/group/sleekxmpp-discussion>`_
  78
  79 **Chat**
  80     `sleek@conference.jabber.org <xmpp:sleek@conference.jabber.org?join>`_
  81
  82 Documentation and Testing
  83 -------------------------
  84 Documentation can be found both inline in the code, and as a Sphinx project in ``/docs``.
  85 To generate the Sphinx documentation, follow the commands below. The HTML output will
  86 be in ``docs/_build/html``::
  87
  88     cd docs
  89     make html
  90     open _build/html/index.html
  91
  92 To run the test suite for SleekXMPP::
  93
  94     python testall.py
  95
  96
  97 The SleekXMPP Boilerplate
  98 -------------------------
  99 Projects using SleekXMPP tend to follow a basic pattern for setting up client/component
 100 connections and configuration. Here is the gist of the boilerplate needed for a SleekXMPP
 101 based project. See the documetation or examples directory for more detailed archetypes for
 102 SleekXMPP projects::
 103
 104     import logging
 105
 106     from sleekxmpp import ClientXMPP
 107     from sleekxmpp.exceptions import IqError, IqTimeout
 108
 109
 110     class EchoBot(ClientXMPP):
 111
 112         def __init__(self, jid, password):
 113             ClientXMPP.__init__(self, jid, password)
 114
 115             self.add_event_handler("session_start", self.session_start)
 116             self.add_event_handler("message", self.message)
 117
 118             self.register_plugin('xep_0030') # Service Discovery
 119             self.register_plugin('xep_0199') # XMPP Ping
 120
 121             # If you are working with an OpenFire server, you will
 122             # need to use a different SSL version:
 123             # import ssl
 124             # self.ssl_version = ssl.PROTOCOL_SSLv3
 125
 126         def session_start(self, event):
 127             self.send_presence()
 128
 129             # Most get_*/set_* methods from plugins use Iq stanzas, which
 130             # can generate IqError and IqTimeout exceptions
 131             try:
 132                 self.get_roster()
 133             except IqError as err:
 134                 logging.error('There was an error getting the roster')
 135                 logging.error(err.iq['error']['condition'])
 136                 self.disconnect()
 137             except IqTimeout:
 138                 logging.error('Server is taking too long to respond')
 139                 self.disconnect()
 140
 141         def message(self, msg):
 142             if msg['type'] in ('chat', 'normal'):
 143                 msg.reply("Thanks for sending\n%(body)s" % msg).send()
 144
 145
 146     if __name__ == '__main__':
 147         # Ideally use optparse or argparse to get JID,
 148         # password, and log level.
 149
 150         logging.basicConfig(level=logging.DEBUG,
 151                             format='%(levelname)-8s %(message)s')
 152
 153         xmpp = EchoBot('somejid@example.com', 'use_getpass')
 154         xmpp.connect():
 155         xmpp.process(block=True)
 156
 157
 158 Credits
 159 -------
 160 **Main Author:** Nathan Fritz
 161     `fritzy@netflint.net <xmpp:fritzy@netflint.net?message>`_,
 162     `@fritzy <http://twitter.com/fritzy>`_
 163
 164     Nathan is also the author of XMPPHP and `Seesmic-AS3-XMPP
 165     <http://code.google.com/p/seesmic-as3-xmpp/>`_, and a member of the XMPP
 166     Council.
 167
 168 **Co-Author:** Lance Stout
 169     `lancestout@gmail.com <xmpp:lancestout@gmail.com?message>`_,
 170     `@lancestout <http://twitter.com/lancestout>`_
 171
 172 **Contributors:**
 173     - Brian Beggs (`macdiesel <http://github.com/macdiesel>`_)
 174     - Dann Martens (`dannmartens <http://github.com/dannmartens>`_)
 175     - Florent Le Coz (`louiz <http://github.com/louiz>`_)
 176     - Kevin Smith (`Kev <http://github.com/Kev>`_, http://kismith.co.uk)
 177     - Remko Tronçon (`remko <http://github.com/remko>`_, http://el-tramo.be)
 178     - Te-jé Rogers (`te-je <http://github.com/te-je>`_)
 179     - Thom Nichols (`tomstrummer <http://github.com/tomstrummer>`_)