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.
11 SleekXMPP's design goals and philosphy are:
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.
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.
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
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.
38 Get the latest stable version from PyPI::
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
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>`_
59 - `Latest Develop Version <http://github.com/fritzy/SleekXMPP/zipball/develop>`_
63 If you are using Python3 and wish to use dnspython, you will have to checkout and
64 install the ``python3`` branch::
66 git clone http://github.com/rthalley/dnspython
69 python3 setup.py install
73 A mailing list and XMPP chat room are available for discussing and getting
77 `SleekXMPP Discussion on Google Groups <http://groups.google.com/group/sleekxmpp-discussion>`_
80 `sleek@conference.jabber.org <xmpp:sleek@conference.jabber.org?join>`_
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``::
90 open _build/html/index.html
92 To run the test suite for SleekXMPP::
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
106 from sleekxmpp import ClientXMPP
107 from sleekxmpp.exceptions import IqError, IqTimeout
110 class EchoBot(ClientXMPP):
112 def __init__(self, jid, password):
113 ClientXMPP.__init__(self, jid, password)
115 self.add_event_handler("session_start", self.session_start)
116 self.add_event_handler("message", self.message)
118 self.register_plugin('xep_0030') # Service Discovery
119 self.register_plugin('xep_0199') # XMPP Ping
121 # If you are working with an OpenFire server, you will
122 # need to use a different SSL version:
124 # self.ssl_version = ssl.PROTOCOL_SSLv3
126 def session_start(self, event):
129 # Most get_*/set_* methods from plugins use Iq stanzas, which
130 # can generate IqError and IqTimeout exceptions
133 except IqError as err:
134 logging.error('There was an error getting the roster')
135 logging.error(err.iq['error']['condition'])
138 logging.error('Server is taking too long to respond')
141 def message(self, msg):
142 if msg['type'] in ('chat', 'normal'):
143 msg.reply("Thanks for sending\n%(body)s" % msg).send()
146 if __name__ == '__main__':
147 # Ideally use optparse or argparse to get JID,
148 # password, and log level.
150 logging.basicConfig(level=logging.DEBUG,
151 format='%(levelname)-8s %(message)s')
153 xmpp = EchoBot('somejid@example.com', 'use_getpass')
155 xmpp.process(block=True)
160 **Main Author:** Nathan Fritz
161 `fritzy@netflint.net <xmpp:fritzy@netflint.net?message>`_,
162 `@fritzy <http://twitter.com/fritzy>`_
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
168 **Co-Author:** Lance Stout
169 `lancestout@gmail.com <xmpp:lancestout@gmail.com?message>`_,
170 `@lancestout <http://twitter.com/lancestout>`_
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>`_)