summaryrefslogtreecommitdiff
path: root/README.rst
diff options
context:
space:
mode:
Diffstat (limited to 'README.rst')
-rw-r--r--README.rst182
1 files changed, 182 insertions, 0 deletions
diff --git a/README.rst b/README.rst
new file mode 100644
index 00000000..e2c289d9
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,182 @@
+SleekXMPP
+#########
+
+SleekXMPP is an MIT licensed XMPP library for Python 2.6/3.1+,
+and is featured in examples in
+`XMPP: The Definitive Guide <http://oreilly.com/catalog/9780596521271>`_
+by Kevin Smith, Remko Tronçon, and Peter Saint-Andre. If you've arrived
+here from reading the Definitive Guide, please see the notes on updating
+the examples to the latest version of SleekXMPP.
+
+SleekXMPP's design goals and philosphy are:
+
+**Low number of dependencies**
+ Installing and using SleekXMPP should be as simple as possible, without
+ having to deal with long dependency chains.
+
+ As part of reducing the number of dependencies, some third party
+ modules are included with SleekXMPP in the ``thirdparty`` directory.
+ Imports from this module first try to import an existing installed
+ version before loading the packaged version, when possible.
+
+**Every XEP as a plugin**
+ Following Python's "batteries included" approach, the goal is to
+ provide support for all currently active XEPs (final and draft). Since
+ adding XEP support is done through easy to create plugins, the hope is
+ to also provide a solid base for implementing and creating experimental
+ XEPs.
+
+**Rewarding to work with**
+ As much as possible, SleekXMPP should allow things to "just work" using
+ sensible defaults and appropriate abstractions. XML can be ugly to work
+ with, but it doesn't have to be that way.
+
+
+Get the Code
+------------
+
+Get the latest stable version from PyPI::
+
+ pip install sleekxmpp
+
+The latest source code for SleekXMPP may be found on `Github
+<http://github.com/fritzy/SleekXMPP>`_. Releases can be found in the
+``master`` branch, while the latest development version is in the
+``develop`` branch.
+
+**Latest Release**
+ - `1.0 <http://github.com/fritzy/SleekXMPP/zipball/1.0>`_
+
+**Develop Releases**
+ - `Latest Develop Version <http://github.com/fritzy/SleekXMPP/zipball/develop>`_
+
+**Older Stable Releases**
+ - `1.0 RC3 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC3>`_
+ - `1.0 RC2 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC2>`_
+ - `1.0 RC1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC1>`_
+ - `1.0 Beta6.1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta6.1>`_
+ - `1.0 Beta5 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta5>`_
+ - `1.0 Beta4 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta4>`_
+ - `1.0 Beta3 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta3>`_
+ - `1.0 Beta2 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta2>`_
+ - `1.0 Beta1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta1>`_
+
+Installing DNSPython
+---------------------
+If you are using Python3 and wish to use dnspython, you will have to checkout and
+install the ``python3`` branch::
+
+ git clone http://github.com/rthalley/dnspython
+ cd dnspython
+ git checkout python3
+ python3 setup.py install
+
+Discussion
+----------
+A mailing list and XMPP chat room are available for discussing and getting
+help with SleekXMPP.
+
+**Mailing List**
+ `SleekXMPP Discussion on Google Groups <http://groups.google.com/group/sleekxmpp-discussion>`_
+
+**Chat**
+ `sleek@conference.jabber.org <xmpp:sleek@conference.jabber.org?join>`_
+
+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.session_start)
+ self.add_event_handler("message", self.message)
+
+ self.register_plugin('xep_0030') # Service Discovery
+ self.register_plugin('xep_0199') # XMPP Ping
+
+ # If you are working with an OpenFire server, you will
+ # need to use a different SSL version:
+ # import ssl
+ # self.ssl_version = ssl.PROTOCOL_SSLv3
+
+ def session_start(self, event):
+ self.send_presence()
+
+ # Most get_*/set_* 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.connect()
+ xmpp.process(block=True)
+
+
+Credits
+-------
+**Main Author:** Nathan Fritz
+ `fritzy@netflint.net <xmpp:fritzy@netflint.net?message>`_,
+ `@fritzy <http://twitter.com/fritzy>`_
+
+ Nathan is also the author of XMPPHP and `Seesmic-AS3-XMPP
+ <http://code.google.com/p/seesmic-as3-xmpp/>`_, and a former member of
+ the XMPP Council.
+
+**Co-Author:** Lance Stout
+ `lancestout@gmail.com <xmpp:lancestout@gmail.com?message>`_,
+ `@lancestout <http://twitter.com/lancestout>`_
+
+**Contributors:**
+ - Brian Beggs (`macdiesel <http://github.com/macdiesel>`_)
+ - Dann Martens (`dannmartens <http://github.com/dannmartens>`_)
+ - Florent Le Coz (`louiz <http://github.com/louiz>`_)
+ - Kevin Smith (`Kev <http://github.com/Kev>`_, http://kismith.co.uk)
+ - Remko Tronçon (`remko <http://github.com/remko>`_, http://el-tramo.be)
+ - Te-jé Rogers (`te-je <http://github.com/te-je>`_)
+ - Thom Nichols (`tomstrummer <http://github.com/tomstrummer>`_)