Merge branch 'master' of git://github.com/fritzy/SleekXMPP into develop

# By Lance Stout
# Via Lance Stout
* 'master' of git://github.com/fritzy/SleekXMPP:
  Turns out not all data is UTF-8, so don't try to decode it.

.gitignore

@@ -6,3 +6,5 @@ docs/_build/
 *.swp
 .tox/
 .coverage
+sleekxmpp.egg-info/
+.ropeproject/

LICENSE

@@ -69,8 +69,8 @@ modification, are permitted provided that the following conditions are met:
     * Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
-    * Neither the name of Red Innovation nor the names of its contributors 
-      may be used to endorse or promote products derived from this software 
+    * Neither the name of Red Innovation nor the names of its contributors
+      may be used to endorse or promote products derived from this software
       without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY RED INNOVATION ``AS IS'' AND ANY
@@ -138,3 +138,57 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
+
+
+python-gnupg: A Python wrapper for the GNU Privacy Guard
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Copyright (c) 2008-2012 by Vinay Sajip.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * The name(s) of the copyright holder(s) may not be used to endorse or
+      promote products derived from this software without specific prior
+      written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) "AS IS" AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+socksipy: A Python SOCKS client module.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Copyright 2006 Dan-Haim. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+3. Neither the name of Dan Haim nor the names of his contributors may be used
+   to endorse or promote products derived from this software without specific
+   prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY DAN HAIM "AS IS" AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+EVENT SHALL DAN HAIM OR HIS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA
+OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMANGE.

README.rst

@@ -44,17 +44,13 @@ The latest source code for SleekXMPP may be found on `Github
 ``master`` branch, while the latest development version is in the
 ``develop`` branch.
 
-**Stable Releases**
-    - `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>`_
+**Latest Release**
+    - `1.1.10 <http://github.com/fritzy/SleekXMPP/zipball/1.1.10>`_
 
 **Develop Releases**
     - `Latest Develop Version <http://github.com/fritzy/SleekXMPP/zipball/develop>`_
 
+
 Installing DNSPython
 ---------------------
 If you are using Python3 and wish to use dnspython, you will have to checkout and
@@ -76,6 +72,7 @@ help with SleekXMPP.
 **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``.
@@ -109,23 +106,37 @@ SleekXMPP projects::
         def __init__(self, jid, password):
             ClientXMPP.__init__(self, jid, password)
 
-            self.add_event_handler("session_start", self.start)
+            self.add_event_handler("session_start", self.session_start)
             self.add_event_handler("message", self.message)
 
-        def start(self, event):
-            self.send_presence()
+            # If you wanted more functionality, here's how to register plugins:
+            # self.register_plugin('xep_0030') # Service Discovery
+            # self.register_plugin('xep_0199') # XMPP Ping
 
-            # Most get_* methods from plugins use Iq stanzas, which
+            # Here's how to access plugins once you've registered them:
+            # self['xep_0030'].add_feature('echo_demo')
+
+            # 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()
+            self.get_roster()
+
+            # 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()
+            #
+            # 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'):
@@ -140,19 +151,8 @@ SleekXMPP projects::
                             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 use a different SSL version:
-        #
-        # import ssl
-        # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
-
-        if xmpp.connect():
-            xmpp.process(block=True)
-        else:
-            print("Unable to connect.")
+        xmpp.connect()
+        xmpp.process(block=True)
 
 
 Credits
@@ -162,8 +162,8 @@ Credits
     `@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 member of the XMPP
-    Council.
+    <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>`_, 

conn_tests/test_pubsubjobs.py

@@ -1,171 +0,0 @@
-import logging
-import sleekxmpp
-from optparse import OptionParser
-from xml.etree import cElementTree as ET
-import os
-import time
-import sys
-import unittest
-import sleekxmpp.plugins.xep_0004
-from sleekxmpp.xmlstream.matcher.stanzapath import StanzaPath
-from sleekxmpp.xmlstream.handler.waiter import Waiter
-try:
-	import configparser
-except ImportError:
-	import ConfigParser as configparser
-try:
-	import queue
-except ImportError:
-	import Queue as queue
-
-class TestClient(sleekxmpp.ClientXMPP):
-	def __init__(self, jid, password):
-		sleekxmpp.ClientXMPP.__init__(self, jid, password)
-		self.add_event_handler("session_start", self.start)
-		#self.add_event_handler("message", self.message)
-		self.waitforstart = queue.Queue()
-	
-	def start(self, event):
-		self.getRoster()
-		self.sendPresence()
-		self.waitforstart.put(True)
-
-
-class TestPubsubServer(unittest.TestCase):
-	statev = {}
-
-	def __init__(self, *args, **kwargs):
-		unittest.TestCase.__init__(self, *args, **kwargs)
-
-	def setUp(self):
-		pass
-
-	def test001getdefaultconfig(self):
-		"""Get the default node config"""
-		self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode2')
-		self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode3')
-		self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode4')
-		self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode5')
-		result = self.xmpp1['xep_0060'].getNodeConfig(self.pshost)
-		self.statev['defaultconfig'] = result
-		self.failUnless(isinstance(result, sleekxmpp.plugins.xep_0004.Form))
-	
-	def test002createdefaultnode(self):
-		"""Create a node without config"""
-		self.failUnless(self.xmpp1['xep_0060'].create_node(self.pshost, 'testnode1'))
-
-	def test003deletenode(self):
-		"""Delete recently created node"""
-		self.failUnless(self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode1'))
-	
-	def test004createnode(self):
-		"""Create a node with a config"""
-		self.statev['defaultconfig'].field['pubsub#access_model'].setValue('open')
-		self.statev['defaultconfig'].field['pubsub#notify_retract'].setValue(True)
-		self.statev['defaultconfig'].field['pubsub#persist_items'].setValue(True)
-		self.statev['defaultconfig'].field['pubsub#presence_based_delivery'].setValue(True)
-		p = self.xmpp2.Presence()
-		p['to'] = self.pshost
-		p.send()
-		self.failUnless(self.xmpp1['xep_0060'].create_node(self.pshost, 'testnode2', self.statev['defaultconfig'], ntype='job'))
-	
-	def test005reconfigure(self):
-		"""Retrieving node config and reconfiguring"""
-		nconfig = self.xmpp1['xep_0060'].getNodeConfig(self.pshost, 'testnode2')
-		self.failUnless(nconfig, "No configuration returned")
-		#print("\n%s ==\n %s" % (nconfig.getValues(), self.statev['defaultconfig'].getValues()))
-		self.failUnless(nconfig.getValues() == self.statev['defaultconfig'].getValues(), "Configuration does not match")
-		self.failUnless(self.xmpp1['xep_0060'].setNodeConfig(self.pshost, 'testnode2', nconfig))
-
-	def test006subscribetonode(self):
-		"""Subscribe to node from account 2"""
-		self.failUnless(self.xmpp2['xep_0060'].subscribe(self.pshost, "testnode2"))
-	
-	def test007publishitem(self):
-		"""Publishing item"""
-		item = ET.Element('{http://netflint.net/protocol/test}test')
-		w = Waiter('wait publish', StanzaPath('message/pubsub_event/items'))
-		self.xmpp2.registerHandler(w)
-		#result = self.xmpp1['xep_0060'].setItem(self.pshost, "testnode2", (('test1', item),))
-		result = self.xmpp1['jobs'].createJob(self.pshost, "testnode2", 'test1', item)
-		msg = w.wait(5) # got to get a result in 5 seconds
-		self.failUnless(msg != False, "Account #2 did not get message event")
-		#result = self.xmpp1['xep_0060'].setItem(self.pshost, "testnode2", (('test2', item),))
-		result = self.xmpp1['jobs'].createJob(self.pshost, "testnode2", 'test2', item)
-		w = Waiter('wait publish2', StanzaPath('message/pubsub_event/items'))
-		self.xmpp2.registerHandler(w)
-		self.xmpp2['jobs'].claimJob(self.pshost, 'testnode2', 'test1')
-		msg = w.wait(5) # got to get a result in 5 seconds
-		self.xmpp2['jobs'].claimJob(self.pshost, 'testnode2', 'test2')
-		self.xmpp2['jobs'].finishJob(self.pshost, 'testnode2', 'test1')
-		self.xmpp2['jobs'].finishJob(self.pshost, 'testnode2', 'test2')
-		print result
-		#need to add check for update
-
-	def test900cleanup(self):
-		"Cleaning up"
-		#self.failUnless(self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode2'), "Could not delete test node.")
-		time.sleep(10)
-	
-
-if __name__ == '__main__':
-	#parse command line arguements
-	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("-c","--config", dest="configfile", default="config.xml", help="set config file to use")
-	optp.add_option("-n","--nodenum", dest="nodenum", default="1", help="set node number to use")
-	optp.add_option("-p","--pubsub", dest="pubsub", default="1", help="set pubsub host to use")
-	opts,args = optp.parse_args()
-	
-	logging.basicConfig(level=opts.loglevel, format='%(levelname)-8s %(message)s')
-
-	#load xml config
-	logging.info("Loading config file: %s" % opts.configfile)
-	config = configparser.RawConfigParser()
-	config.read(opts.configfile)
-	
-	#init
-	logging.info("Account 1 is %s" % config.get('account1', 'jid'))
-	xmpp1 = TestClient(config.get('account1','jid'), config.get('account1','pass'))
-	logging.info("Account 2 is %s" % config.get('account2', 'jid'))
-	xmpp2 = TestClient(config.get('account2','jid'), config.get('account2','pass'))
-	
-	xmpp1.registerPlugin('xep_0004')
-	xmpp1.registerPlugin('xep_0030')
-	xmpp1.registerPlugin('xep_0060')
-	xmpp1.registerPlugin('xep_0199')
-	xmpp1.registerPlugin('jobs')
-	xmpp2.registerPlugin('xep_0004')
-	xmpp2.registerPlugin('xep_0030')
-	xmpp2.registerPlugin('xep_0060')
-	xmpp2.registerPlugin('xep_0199')
-	xmpp2.registerPlugin('jobs')
-
-	if not config.get('account1', 'server'):
-		# we don't know the server, but the lib can probably figure it out
-		xmpp1.connect() 
-	else:
-		xmpp1.connect((config.get('account1', 'server'), 5222))
-	xmpp1.process(threaded=True)
-	
-	#init
-	if not config.get('account2', 'server'):
-		# we don't know the server, but the lib can probably figure it out
-		xmpp2.connect() 
-	else:
-		xmpp2.connect((config.get('account2', 'server'), 5222))
-	xmpp2.process(threaded=True)
-
-	TestPubsubServer.xmpp1 = xmpp1
-	TestPubsubServer.xmpp2 = xmpp2
-	TestPubsubServer.pshost = config.get('settings', 'pubsub')
-	xmpp1.waitforstart.get(True)
-	xmpp2.waitforstart.get(True)
-	testsuite = unittest.TestLoader().loadTestsFromTestCase(TestPubsubServer)
-
-	alltests_suite = unittest.TestSuite([testsuite])
-	result = unittest.TextTestRunner(verbosity=2).run(alltests_suite)
-	xmpp1.disconnect()
-	xmpp2.disconnect()

conn_tests/test_pubsubserver.py

@@ -1,233 +0,0 @@
-import logging
-import sleekxmpp
-from optparse import OptionParser
-from xml.etree import cElementTree as ET
-import os
-import time
-import sys
-import unittest
-import sleekxmpp.plugins.xep_0004
-from sleekxmpp.xmlstream.matcher.stanzapath import StanzaPath
-from sleekxmpp.xmlstream.handler.waiter import Waiter
-try:
-	import configparser
-except ImportError:
-	import ConfigParser as configparser
-try:
-	import queue
-except ImportError:
-	import Queue as queue
-
-class TestClient(sleekxmpp.ClientXMPP):
-	def __init__(self, jid, password):
-		sleekxmpp.ClientXMPP.__init__(self, jid, password)
-		self.add_event_handler("session_start", self.start)
-		#self.add_event_handler("message", self.message)
-		self.waitforstart = queue.Queue()
-	
-	def start(self, event):
-		self.getRoster()
-		self.sendPresence()
-		self.waitforstart.put(True)
-
-
-class TestPubsubServer(unittest.TestCase):
-	statev = {}
-
-	def __init__(self, *args, **kwargs):
-		unittest.TestCase.__init__(self, *args, **kwargs)
-
-	def setUp(self):
-		pass
-
-	def test001getdefaultconfig(self):
-		"""Get the default node config"""
-		self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode2')
-		self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode3')
-		self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode4')
-		self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode5')
-		result = self.xmpp1['xep_0060'].getNodeConfig(self.pshost)
-		self.statev['defaultconfig'] = result
-		self.failUnless(isinstance(result, sleekxmpp.plugins.xep_0004.Form))
-	
-	def test002createdefaultnode(self):
-		"""Create a node without config"""
-		self.failUnless(self.xmpp1['xep_0060'].create_node(self.pshost, 'testnode1'))
-
-	def test003deletenode(self):
-		"""Delete recently created node"""
-		self.failUnless(self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode1'))
-	
-	def test004createnode(self):
-		"""Create a node with a config"""
-		self.statev['defaultconfig'].field['pubsub#access_model'].setValue('open')
-		self.statev['defaultconfig'].field['pubsub#notify_retract'].setValue(True)
-		self.failUnless(self.xmpp1['xep_0060'].create_node(self.pshost, 'testnode2', self.statev['defaultconfig']))
-	
-	def test005reconfigure(self):
-		"""Retrieving node config and reconfiguring"""
-		nconfig = self.xmpp1['xep_0060'].getNodeConfig(self.pshost, 'testnode2')
-		self.failUnless(nconfig, "No configuration returned")
-		#print("\n%s ==\n %s" % (nconfig.getValues(), self.statev['defaultconfig'].getValues()))
-		self.failUnless(nconfig.getValues() == self.statev['defaultconfig'].getValues(), "Configuration does not match")
-		self.failUnless(self.xmpp1['xep_0060'].setNodeConfig(self.pshost, 'testnode2', nconfig))
-
-	def test006subscribetonode(self):
-		"""Subscribe to node from account 2"""
-		self.failUnless(self.xmpp2['xep_0060'].subscribe(self.pshost, "testnode2"))
-	
-	def test007publishitem(self):
-		"""Publishing item"""
-		item = ET.Element('{http://netflint.net/protocol/test}test')
-		w = Waiter('wait publish', StanzaPath('message/pubsub_event/items'))
-		self.xmpp2.registerHandler(w)
-		result = self.xmpp1['xep_0060'].setItem(self.pshost, "testnode2", (('test1', item),))
-		msg = w.wait(5) # got to get a result in 5 seconds
-		self.failUnless(msg != False, "Account #2 did not get message event")
-		self.failUnless(result)
-		#need to add check for update
-	
-	def test008updateitem(self):
-		"""Updating item"""
-		item = ET.Element('{http://netflint.net/protocol/test}test', {'someattr': 'hi there'})
-		w = Waiter('wait publish', StanzaPath('message/pubsub_event/items'))
-		self.xmpp2.registerHandler(w)
-		result = self.xmpp1['xep_0060'].setItem(self.pshost, "testnode2", (('test1', item),))
-		msg = w.wait(5) # got to get a result in 5 seconds
-		self.failUnless(msg != False, "Account #2 did not get message event")
-		self.failUnless(result)
-		#need to add check for update
-	
-	def test009deleteitem(self):
-		"""Deleting item"""
-		w = Waiter('wait retract', StanzaPath('message/pubsub_event/items@node=testnode2'))
-		self.xmpp2.registerHandler(w)
-		result = self.xmpp1['xep_0060'].deleteItem(self.pshost, "testnode2", "test1")
-		self.failUnless(result, "Got error when deleting item.")
-		msg = w.wait(1)
-		self.failUnless(msg != False, "Did not get retract notice.")
-	
-	def test010unsubscribenode(self):
-		"Unsubscribing Account #2"
-		self.failUnless(self.xmpp2['xep_0060'].unsubscribe(self.pshost, "testnode2"), "Got error response when unsubscribing.")
-	
-	def test011createcollectionnode(self):
-		"Create a collection node w/ Account #2"
-		self.failUnless(self.xmpp2['xep_0060'].create_node(self.pshost, "testnode3", self.statev['defaultconfig'], True), "Could not create collection node")
-	
-	def test012subscribecollection(self):
-		"Subscribe Account #1 to collection"
-		self.failUnless(self.xmpp1['xep_0060'].subscribe(self.pshost, "testnode3"))
-	
-	def test013assignnodetocollection(self):
-		"Assign node to collection"
-		self.failUnless(self.xmpp2['xep_0060'].addNodeToCollection(self.pshost, 'testnode2', 'testnode3'))
-	
-	def test014publishcollection(self):
-		"""Publishing item to collection child"""
-		item = ET.Element('{http://netflint.net/protocol/test}test')
-		w = Waiter('wait publish2', StanzaPath('message/pubsub_event/items@node=testnode2'))
-		self.xmpp1.registerHandler(w)
-		result = self.xmpp2['xep_0060'].setItem(self.pshost, "testnode2", (('test2', item),))
-		msg = w.wait(5) # got to get a result in 5 seconds
-		self.failUnless(msg != False, "Account #1 did not get message event: perhaps node was advertised incorrectly?")
-		self.failUnless(result)
-
-#	def test016speedtest(self):
-#		"Uncached speed test"
-#		import time
-#		start = time.time()
-#		for y in range(0, 50000, 1000):
-#			start2 = time.time()
-#			for x in range(y, y+1000):
-#				self.failUnless(self.xmpp1['xep_0060'].subscribe(self.pshost, "testnode4", subscribee="testuser%s@whatever" % x))
-#			print time.time() - start2
-#		seconds = time.time() - start
-#		print "--", seconds
-#		print "---------"
-#		time.sleep(15)
-#		self.failUnless(self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode4'), "Could not delete non-cached test node")
-	
-#	def test015speedtest(self):
-#		"cached speed test"
-#		result = self.xmpp1['xep_0060'].getNodeConfig(self.pshost)
-#		self.statev['defaultconfig'] = result
-#		self.statev['defaultconfig'].field['pubsub#node_type'].setValue("leaf")
-#		self.statev['defaultconfig'].field['sleek#saveonchange'].setValue(True)
-#		self.failUnless(self.xmpp1['xep_0060'].create_node(self.pshost, 'testnode4', self.statev['defaultconfig']))
-#		self.statev['defaultconfig'].field['sleek#saveonchange'].setValue(False)
-#		self.failUnless(self.xmpp1['xep_0060'].create_node(self.pshost, 'testnode5', self.statev['defaultconfig']))
-#		start = time.time()
-#		for y in range(0, 50000, 1000):
-#			start2 = time.time()
-#			for x in range(y, y+1000):
-#				self.failUnless(self.xmpp1['xep_0060'].subscribe(self.pshost, "testnode5", subscribee="testuser%s@whatever" % x))
-#			print time.time() - start2
-#		seconds = time.time() - start
-#		print "--", seconds
-
-	def test900cleanup(self):
-		"Cleaning up"
-		self.failUnless(self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode2'), "Could not delete test node.")
-		self.failUnless(self.xmpp1['xep_0060'].deleteNode(self.pshost, 'testnode3'), "Could not delete collection node")
-	
-
-if __name__ == '__main__':
-	#parse command line arguements
-	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("-c","--config", dest="configfile", default="config.xml", help="set config file to use")
-	optp.add_option("-n","--nodenum", dest="nodenum", default="1", help="set node number to use")
-	optp.add_option("-p","--pubsub", dest="pubsub", default="1", help="set pubsub host to use")
-	opts,args = optp.parse_args()
-	
-	logging.basicConfig(level=opts.loglevel, format='%(levelname)-8s %(message)s')
-
-	#load xml config
-	logging.info("Loading config file: %s" % opts.configfile)
-	config = configparser.RawConfigParser()
-	config.read(opts.configfile)
-	
-	#init
-	logging.info("Account 1 is %s" % config.get('account1', 'jid'))
-	xmpp1 = TestClient(config.get('account1','jid'), config.get('account1','pass'))
-	logging.info("Account 2 is %s" % config.get('account2', 'jid'))
-	xmpp2 = TestClient(config.get('account2','jid'), config.get('account2','pass'))
-	
-	xmpp1.registerPlugin('xep_0004')
-	xmpp1.registerPlugin('xep_0030')
-	xmpp1.registerPlugin('xep_0060')
-	xmpp1.registerPlugin('xep_0199')
-	xmpp2.registerPlugin('xep_0004')
-	xmpp2.registerPlugin('xep_0030')
-	xmpp2.registerPlugin('xep_0060')
-	xmpp2.registerPlugin('xep_0199')
-
-	if not config.get('account1', 'server'):
-		# we don't know the server, but the lib can probably figure it out
-		xmpp1.connect() 
-	else:
-		xmpp1.connect((config.get('account1', 'server'), 5222))
-	xmpp1.process(threaded=True)
-	
-	#init
-	if not config.get('account2', 'server'):
-		# we don't know the server, but the lib can probably figure it out
-		xmpp2.connect() 
-	else:
-		xmpp2.connect((config.get('account2', 'server'), 5222))
-	xmpp2.process(threaded=True)
-
-	TestPubsubServer.xmpp1 = xmpp1
-	TestPubsubServer.xmpp2 = xmpp2
-	TestPubsubServer.pshost = config.get('settings', 'pubsub')
-	xmpp1.waitforstart.get(True)
-	xmpp2.waitforstart.get(True)
-	testsuite = unittest.TestLoader().loadTestsFromTestCase(TestPubsubServer)
-
-	alltests_suite = unittest.TestSuite([testsuite])
-	result = unittest.TextTestRunner(verbosity=2).run(alltests_suite)
-	xmpp1.disconnect()
-	xmpp2.disconnect()

conn_tests/testconfig.ini

@@ -1,13 +0,0 @@
-[settings]
-enabled=true
-pubsub=pubsub.recon
-
-[account1]
-jid=fritzy@recon
-pass=testing123
-server=
-
-[account2]
-jid=fritzy2@recon
-pass=testing123
-server=

conn_tests/testpubsub.py

@@ -1,350 +0,0 @@
-"""
-    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 logging
-import sleekxmpp
-from optparse import OptionParser
-from xml.etree import cElementTree as ET
-import os
-import time
-import sys
-import Queue
-import thread
-
-
-class testps(sleekxmpp.ClientXMPP):
-	def __init__(self, jid, password, ssl=False, plugin_config = {}, plugin_whitelist=[], nodenum=0, pshost=None):
-		sleekxmpp.ClientXMPP.__init__(self, jid, password, ssl, plugin_config, plugin_whitelist)
-		self.registerPlugin('xep_0004')
-		self.registerPlugin('xep_0030')
-		self.registerPlugin('xep_0060')
-		self.registerPlugin('xep_0092')
-		self.add_handler("<message xmlns='jabber:client'><event xmlns='http://jabber.org/protocol/pubsub#event' /></message>", self.pubsubEventHandler, name='Pubsub Event', threaded=True)
-		self.add_event_handler("session_start", self.start, threaded=True)
-		self.add_handler("<iq type='error' />", self.handleError, name='Iq Error')
-		self.events = Queue.Queue()
-		self.default_config = None
-		self.ps = self.plugin['xep_0060']
-		self.node = "pstestnode_%s"
-		self.pshost = pshost
-		if pshost is None:
-			self.pshost = self.boundjid.host
-		self.nodenum = int(nodenum)
-		self.leafnode = self.nodenum + 1
-		self.collectnode = self.nodenum + 2
-		self.lasterror = ''
-		self.sprintchars = 0
-		self.defaultconfig = None
-		self.tests = ['test_defaultConfig', 'test_createDefaultNode', 'test_getNodes', 'test_deleteNode', 'test_createWithConfig', 'test_reconfigureNode', 'test_subscribeToNode', 'test_addItem', 'test_updateItem', 'test_deleteItem', 'test_unsubscribeNode', 'test_createCollection', 'test_subscribeCollection', 'test_addNodeCollection', 'test_deleteNodeCollection', 'test_addCollectionNode', 'test_deleteCollectionNode', 'test_unsubscribeNodeCollection', 'test_deleteCollection']
-		self.passed = 0
-		self.width = 120
-	
-	def start(self, event):
-		#TODO: make this configurable
-		self.getRoster()
-		self.sendPresence(ppriority=20)
-		thread.start_new(self.test_all, tuple())
-	
-	def sprint(self, msg, end=False, color=False):
-		length = len(msg)
-		if color:
-			if color == "red":
-				color = "1;31"
-			elif color == "green":
-				color = "0;32"
-			msg = "%s%s%s" % ("\033[%sm" % color, msg, "\033[0m")
-		if not end:
-			sys.stdout.write(msg)
-			self.sprintchars += length
-		else:
-			self.sprint("%s%s" % ("." * (self.width - self.sprintchars - length), msg))
-			print('')
-			self.sprintchars = 0
-		sys.stdout.flush()
-
-	def pubsubEventHandler(self, xml):
-		for item in xml.findall('{http://jabber.org/protocol/pubsub#event}event/{http://jabber.org/protocol/pubsub#event}items/{http://jabber.org/protocol/pubsub#event}item'):
-			self.events.put(item.get('id', '__unknown__'))
-		for item in xml.findall('{http://jabber.org/protocol/pubsub#event}event/{http://jabber.org/protocol/pubsub#event}items/{http://jabber.org/protocol/pubsub#event}retract'):
-			self.events.put(item.get('id', '__unknown__'))
-		for item in xml.findall('{http://jabber.org/protocol/pubsub#event}event/{http://jabber.org/protocol/pubsub#event}collection/{http://jabber.org/protocol/pubsub#event}disassociate'):
-			self.events.put(item.get('node', '__unknown__'))
-		for item in xml.findall('{http://jabber.org/protocol/pubsub#event}event/{http://jabber.org/protocol/pubsub#event}collection/{http://jabber.org/protocol/pubsub#event}associate'):
-			self.events.put(item.get('node', '__unknown__'))
-	
-	def handleError(self, xml):
-		error = xml.find('{jabber:client}error')
-		self.lasterror =  error.getchildren()[0].tag.split('}')[-1]
-		
-	def test_all(self):
-		print("Running Publish-Subscribe Tests")
-		version = self.plugin['xep_0092'].getVersion(self.pshost)
-		if version:
-			print("%s %s on %s" % (version.get('name', 'Unknown Server'), version.get('version', 'v?'), version.get('os', 'Unknown OS')))
-		print("=" * self.width)
-		for test in self.tests:
-			testfunc = getattr(self, test)
-			self.sprint("%s" % testfunc.__doc__)
-			if testfunc():
-				self.sprint("Passed", True, "green")
-				self.passed += 1
-			else:
-				if not self.lasterror:
-					self.lasterror = 'No response'
-				self.sprint("Failed (%s)" % self.lasterror, True, "red")
-				self.lasterror = ''
-		print("=" * self.width)
-		self.sprint("Cleaning up...")
-		#self.ps.deleteNode(self.pshost, self.node % self.nodenum)
-		self.ps.deleteNode(self.pshost, self.node % self.leafnode)
-		#self.ps.deleteNode(self.pshost, self.node % self.collectnode)
-		self.sprint("Done", True, "green")
-		self.disconnect()
-		self.sprint("%s" % self.passed, False, "green")
-		self.sprint("/%s Passed -- " % len(self.tests))
-		if len(self.tests) - self.passed:
-			self.sprint("%s" % (len(self.tests) - self.passed), False, "red")
-		else:
-			self.sprint("%s" % (len(self.tests) - self.passed), False, "green")
-		self.sprint(" Failed Tests")
-		print
-		#print "%s/%s Passed -- %s Failed Tests" % (self.passed, len(self.tests), len(self.tests) - self.passed)
-	
-	def test_defaultConfig(self):
-		"Retreiving default configuration"
-		result = self.ps.getNodeConfig(self.pshost)
-		if result is False or result is None:
-			return False
-		else:
-			self.defaultconfig = result
-			try:
-				self.defaultconfig.field['pubsub#access_model'].setValue('open')
-			except KeyError:
-				pass
-			try:
-				self.defaultconfig.field['pubsub#notify_retract'].setValue(True)
-			except KeyError:
-				pass
-			return True
-	
-	def test_createDefaultNode(self):
-		"Creating default node"
-		return self.ps.create_node(self.pshost, self.node % self.nodenum)
-	
-	def test_getNodes(self):
-		"Getting list of nodes"
-		self.ps.getNodes(self.pshost)
-		self.ps.getItems(self.pshost, 'blog')
-		return True
-	
-	def test_deleteNode(self):
-		"Deleting node"
-		return self.ps.deleteNode(self.pshost, self.node % self.nodenum)
-	
-	def test_createWithConfig(self):
-		"Creating node with config"
-		if self.defaultconfig is None:
-			self.lasterror = "No Avail Config"
-			return False
-		return self.ps.create_node(self.pshost, self.node % self.leafnode, self.defaultconfig)
-	
-	def test_reconfigureNode(self):
-		"Retrieving node config and reconfiguring"
-		nconfig = self.ps.getNodeConfig(self.pshost, self.node % self.leafnode)
-		if nconfig == False:
-			return False
-		return self.ps.setNodeConfig(self.pshost, self.node % self.leafnode, nconfig)
-		
-	def test_subscribeToNode(self):
-		"Subscribing to node"
-		return self.ps.subscribe(self.pshost, self.node % self.leafnode)
-	
-	def test_addItem(self):
-		"Adding item, waiting for notification"
-		item = ET.Element('test')
-		result = self.ps.setItem(self.pshost, self.node % self.leafnode, (('test_node1', item),))
-		if result == False:
-			return False
-		try:
-			event = self.events.get(True, 10)
-		except Queue.Empty:
-			return False
-		if event == 'test_node1':
-			return True
-		return False
-	
-	def test_updateItem(self):
-		"Updating item, waiting for notification"
-		item = ET.Element('test')
-		item.attrib['crap'] = 'yup, right here'
-		result = self.ps.setItem(self.pshost, self.node % self.leafnode, (('test_node1', item),))
-		if result == False:
-			return False
-		try:
-			event = self.events.get(True, 10)
-		except Queue.Empty:
-			return False
-		if event == 'test_node1':
-			return True
-		return False
-
-	def test_deleteItem(self):
-		"Deleting item, waiting for notification"
-		result = self.ps.deleteItem(self.pshost, self.node % self.leafnode, 'test_node1')
-		if result == False:
-			return False
-		try:
-			event = self.events.get(True, 10)
-		except Queue.Empty:
-			self.lasterror = "No Notification"
-			return False
-		if event == 'test_node1':
-			return True
-		return False
-	
-	def test_unsubscribeNode(self):
-		"Unsubscribing from node"
-		return self.ps.unsubscribe(self.pshost, self.node % self.leafnode)
-
-	def test_createCollection(self):
-		"Creating collection node"
-		return self.ps.create_node(self.pshost, self.node % self.collectnode, self.defaultconfig, True)
-	
-	def test_subscribeCollection(self):
-		"Subscribing to collection node"
-		return self.ps.subscribe(self.pshost, self.node % self.collectnode)
-	
-	def test_addNodeCollection(self):
-		"Assigning node to collection, waiting for notification"
-		config = self.ps.getNodeConfig(self.pshost, self.node % self.leafnode)
-		if not config or config is None:
-			self.lasterror = "Config Error"
-			return False
-		try:
-			config.field['pubsub#collection'].setValue(self.node % self.collectnode)
-		except KeyError:
-			self.sprint("...Missing Field...", False, "red")
-			config.addField('pubsub#collection', value=self.node % self.collectnode)
-		if not self.ps.setNodeConfig(self.pshost, self.node % self.leafnode, config):
-			return False
-		try:
-			event = self.events.get(True, 10)
-		except Queue.Empty:
-			self.lasterror = "No Notification"
-			return False
-		if event == self.node % self.leafnode:
-			return True
-		return False
-	
-	def test_deleteNodeCollection(self):
-		"Removing node assignment to collection, waiting for notification"
-		config = self.ps.getNodeConfig(self.pshost, self.node % self.leafnode)
-		if not config or config is None:
-			self.lasterror = "Config Error"
-			return False
-		try:
-			config.field['pubsub#collection'].delValue(self.node % self.collectnode)
-		except KeyError:
-			self.sprint("...Missing Field...", False, "red")
-			config.addField('pubsub#collection', value='')
-		if not self.ps.setNodeConfig(self.pshost, self.node % self.leafnode, config):
-			return False
-		try:
-			event = self.events.get(True, 10)
-		except Queue.Empty:
-			self.lasterror = "No Notification"
-			return False
-		if event == self.node % self.leafnode:
-			return True
-		return False
-
-	def test_addCollectionNode(self):
-		"Assigning node from collection, waiting for notification"
-		config = self.ps.getNodeConfig(self.pshost, self.node % self.collectnode)
-		if not config or config is None:
-			self.lasterror = "Config Error"
-			return False
-		try:
-			config.field['pubsub#children'].setValue(self.node % self.leafnode)
-		except KeyError:
-			self.sprint("...Missing Field...", False, "red")
-			config.addField('pubsub#children', value=self.node % self.leafnode)
-		if not self.ps.setNodeConfig(self.pshost, self.node % self.collectnode, config):
-			return False
-		try:
-			event = self.events.get(True, 10)
-		except Queue.Empty:
-			self.lasterror = "No Notification"
-			return False
-		if event == self.node % self.leafnode:
-			return True
-		return False
-
-	def test_deleteCollectionNode(self):
-		"Removing node from collection, waiting for notification"
-		config = self.ps.getNodeConfig(self.pshost, self.node % self.collectnode)
-		if not config or config is None:
-			self.lasterror = "Config Error"
-			return False
-		try:
-			config.field['pubsub#children'].delValue(self.node % self.leafnode)
-		except KeyError:
-			self.sprint("...Missing Field...", False, "red")
-			config.addField('pubsub#children', value='')
-		if not self.ps.setNodeConfig(self.pshost, self.node % self.collectnode, config):
-			return False
-		try:
-			event = self.events.get(True, 10)
-		except Queue.Empty:
-			self.lasterror = "No Notification"
-			return False
-		if event == self.node % self.leafnode:
-			return True
-		return False
-	
-	def test_unsubscribeNodeCollection(self):
-		"Unsubscribing from collection"
-		return self.ps.unsubscribe(self.pshost, self.node % self.collectnode)
-	
-	def test_deleteCollection(self):
-		"Deleting collection"
-		return self.ps.deleteNode(self.pshost, self.node % self.collectnode)
-
-if __name__ == '__main__':
-	#parse command line arguements
-	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("-c","--config", dest="configfile", default="config.xml", help="set config file to use")
-	optp.add_option("-n","--nodenum", dest="nodenum", default="1", help="set node number to use")
-	optp.add_option("-p","--pubsub", dest="pubsub", default="1", help="set pubsub host to use")
-	opts,args = optp.parse_args()
-	
-	logging.basicConfig(level=opts.loglevel, format='%(levelname)-8s %(message)s')
-
-	#load xml config
-	logging.info("Loading config file: %s" % opts.configfile)
-	config = ET.parse(os.path.expanduser(opts.configfile)).find('auth')
-	
-	#init
-	logging.info("Logging in as %s" % config.attrib['jid'])
-	
-	
-	plugin_config = {}
-	plugin_config['xep_0092'] = {'name': 'SleekXMPP Example', 'version': '0.1-dev'}
-	plugin_config['xep_0199'] = {'keepalive': True, 'timeout': 30, 'frequency': 300}
-	
-	con = testps(config.attrib['jid'], config.attrib['pass'], plugin_config=plugin_config, plugin_whitelist=[], nodenum=opts.nodenum, pshost=opts.pubsub)
-	if not config.get('server', None):
-		# we don't know the server, but the lib can probably figure it out
-		con.connect() 
-	else:
-		con.connect((config.attrib['server'], 5222))
-	con.process(threaded=False)
-	print("")

docs/.gitignore

@@ -0,0 +1 @@
+_build/*

docs/_static/haiku.css

@@ -59,9 +59,10 @@ body {
     margin: auto;
     padding: 0px;
     font-family: "Helvetica Neueu", Helvetica, sans-serif;
-    min-width: 59em;
+    min-width: 30em;
     max-width: 70em;
     color: #444;
+    text-align: center;
 }
 
 div.footer {
@@ -124,21 +125,25 @@ a.headerlink:hover {
 /* basic text elements */
 
 div.content {
+    margin: auto;
     margin-top: 20px;
-    margin-left: 40px;
-    margin-right: 40px;
     margin-bottom: 50px;
     font-size: 0.9em;
+    width: 700px;
+    text-align: left;
 }
 
 /* heading and navigation */
 
 div.header {
     position: relative;
+    margin: auto;
     margin-top: 125px;
     height: 85px;
     padding: 0 40px;
     font-family: "Yanone Kaffeesatz";
+    text-align: left;
+    width: 750px;
 }
 div.header h1 {
     font-size: 2.6em;
@@ -185,12 +190,12 @@ div.topnav {
     z-index: 0;
 }
 div.topnav p {
+    margin: auto;
     margin-top: 0;
-    margin-left: 40px;
-    margin-right: 40px;
     margin-bottom: 0px;
     text-align: right;
     font-size: 0.8em;
+    width: 750px;
 }
 div.bottomnav {
     background: #eeeeee;
@@ -404,3 +409,23 @@ div.viewcode-block:target {
     padding: 0 12px;
 }
 
+#from_andyet {
+    -webkit-box-shadow: #CCC 0px 0px 3px;
+    background: rgba(255, 255, 255, 1);
+    bottom: 0px;
+    right: 17px;
+    padding: 3px 10px;
+    position: fixed;
+}
+
+#from_andyet h2 {
+    background-image: url("images/from_&yet.png");
+    background-repeat: no-repeat;
+    height: 29px;
+    line-height: 0;
+    text-indent: -9999em;
+    width: 79px;
+    margin-top: 0;
+    margin: 0px;
+    padding: 0px;
+}

docs/_templates/defindex.html

@@ -1,35 +0,0 @@
-{#
-    basic/defindex.html
-    ~~~~~~~~~~~~~~~~~~~
-
-    Default template for the "index" page.
-
-    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
-{% extends "layout.html" %}
-{% set title = _('Overview') %}
-{% block body %}
-  <h1>{{ docstitle|e }}</h1>
-  <p>
-    Welcome! This is
-    {% block description %}the documentation for {{ project|e }}
-    {{ release|e }}{% if last_updated %}, last updated {{ last_updated|e }}{% endif %}{% endblock %}.
-  </p>
-  {% block tables %}
-  <p><strong>{{ _('Indices and tables:') }}</strong></p>
-  <table class="contentstable" align="center"><tr>
-    <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{{ _('Complete Table of Contents') }}</a><br>
-         <span class="linkdescr">{{ _('lists all sections and subsections') }}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{{ _('Search Page') }}</a><br>
-         <span class="linkdescr">{{ _('search this documentation') }}</span></p>
-    </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">{{ _('Global Module Index') }}</a><br>
-         <span class="linkdescr">{{ _('quick access to all modules') }}</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{{ _('General Index') }}</a><br>
-         <span class="linkdescr">{{ _('all functions, classes, terms') }}</span></p>
-    </td></tr>
-  </table>
-  {% endblock %}
-{% endblock %}

docs/_templates/indexcontent.html

@@ -1,61 +0,0 @@
-{% extends "defindex.html" %}
-{% block tables %}
-  <p><strong>Parts of the documentation:</strong></p>
-  <table class="contentstable" align="center"><tr>
-    <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("whatsnew/" + version) }}">What's new in Python {{ version }}?</a><br/>
-         <span class="linkdescr">or <a href="{{ pathto("whatsnew/index") }}">all "What's new" documents</a> since 2.0</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">Tutorial</a><br/>
-         <span class="linkdescr">start here</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("library/index") }}">Library Reference</a><br/>
-         <span class="linkdescr">keep this under your pillow</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">Language Reference</a><br/>
-         <span class="linkdescr">describes syntax and language elements</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("using/index") }}">Python Setup and Usage</a><br/>
-         <span class="linkdescr">how to use Python on different platforms</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">Python HOWTOs</a><br/>
-         <span class="linkdescr">in-depth documents on specific topics</span></p>
-    </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">Extending and Embedding</a><br/>
-         <span class="linkdescr">tutorial for C/C++ programmers</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">Python/C API</a><br/>
-         <span class="linkdescr">reference for C/C++ programmers</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("install/index") }}">Installing Python Modules</a><br/>
-         <span class="linkdescr">information for installers &amp; sys-admins</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("distutils/index") }}">Distributing Python Modules</a><br/>
-         <span class="linkdescr">sharing modules with others</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("documenting/index") }}">Documenting Python</a><br/>
-         <span class="linkdescr">guide for documentation authors</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">FAQs</a><br/>
-         <span class="linkdescr">frequently asked questions (with answers!)</span></p>
-    </td></tr>
-  </table>
-
-  <p><strong>Indices and tables:</strong></p>
-  <table class="contentstable" align="center"><tr>
-    <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("py-modindex") }}">Global Module Index</a><br/>
-         <span class="linkdescr">quick access to all modules</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/>
-         <span class="linkdescr">all functions, classes, terms</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("glossary") }}">Glossary</a><br/>
-         <span class="linkdescr">the most important terms explained</span></p>
-    </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/>
-         <span class="linkdescr">search this documentation</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Complete Table of Contents</a><br/>
-         <span class="linkdescr">lists all sections and subsections</span></p>
-    </td></tr>
-  </table>
-
-  <p><strong>Meta information:</strong></p>
-  <table class="contentstable" align="center"><tr>
-    <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}">Reporting bugs</a></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("about") }}">About the documentation</a></p>
-    </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("license") }}">History and License of Python</a></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("copyright") }}">Copyright</a></p>
-    </td></tr>
-  </table>
-{% endblock %}

docs/_templates/layout.html

@@ -4,7 +4,7 @@
 
     Sphinx layout template for the haiku theme.
 
-    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 #}
 {% extends "basic/layout.html" %}
@@ -44,9 +44,8 @@
         {%- if logo -%}
           <img class="rightlogo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
         {%- endif -%}
-        <h1 class="heading">
-            <a href="{{ pathto('index') }}"><span>{{ project|e }}</span></a>
-        </h1>
+        <h1 class="heading"><a href="{{ pathto('index') }}">
+          <span>{{ title|striptags }}</span></a></h1>
         <h2 class="heading"><span>{{ shorttitle|e }}</span></h2>
         {%- endif %}
         {%- endblock %}
@@ -66,4 +65,6 @@
       <div class="bottomnav">
       {{ nav() }}
       </div>
+      <a id="from_andyet" href="http://andyet.net"><h2>From &amp;yet</h2></a>
 {% endblock %}
+

docs/api/basexmpp.rst

@@ -1,5 +1,5 @@
 ========
-basexmpp
+BaseXMPP
 ========
 
 .. module:: sleekxmpp.basexmpp

docs/api/clientxmpp.rst

@@ -1,17 +1,8 @@
 ==========
-clientxmpp
+ClientXMPP
 ==========
 
 .. module:: sleekxmpp.clientxmpp
 
 .. autoclass:: ClientXMPP
-    
-    .. automethod:: connect
-
-    .. automethod:: register_feature
-
-    .. automethod:: get_roster
-
-    .. automethod:: update_roster
-
-    .. automethod:: del_roster_item
+    :members:

docs/api/componentxmpp.rst

@@ -0,0 +1,8 @@
+=============
+ComponentXMPP
+=============
+
+.. module:: sleekxmpp.componentxmpp
+
+.. autoclass:: ComponentXMPP
+    :members:

docs/api/exceptions.rst

@@ -0,0 +1,14 @@
+Exceptions
+==========
+
+.. module:: sleekxmpp.exceptions
+
+    
+.. autoexception:: XMPPError
+    :members:
+
+.. autoexception:: IqError
+    :members:
+
+.. autoexception:: IqTimeout
+    :members:

docs/api/xmlstream.rst

@@ -1,8 +0,0 @@
-=========
-xmlstream
-=========
-
-.. module:: sleekxmpp.xmlstream
-
-.. autoclass:: XMLStream
-    :members:

docs/api/xmlstream/filesocket.rst

@@ -0,0 +1,12 @@
+.. module:: sleekxmpp.xmlstream.filesocket
+
+.. _filesocket:
+
+Python 2.6 File Socket Shims
+============================
+
+.. autoclass:: FileSocket
+    :members:
+
+.. autoclass:: Socket26
+    :members:

docs/api/xmlstream/handler.rst

@@ -0,0 +1,24 @@
+Stanza Handlers
+===============
+
+The Basic Handler
+-----------------
+.. module:: sleekxmpp.xmlstream.handler.base
+
+.. autoclass:: BaseHandler
+    :members:
+
+Callback
+--------
+.. module:: sleekxmpp.xmlstream.handler.callback
+
+.. autoclass:: Callback
+    :members:
+
+
+Waiter
+------
+.. module:: sleekxmpp.xmlstream.handler.waiter
+
+.. autoclass:: Waiter
+    :members:

docs/api/xmlstream/jid.rst

@@ -0,0 +1,7 @@
+Jabber IDs (JID)
+=================
+
+.. module:: sleekxmpp.xmlstream.jid
+
+.. autoclass:: JID
+    :members:

docs/api/xmlstream/matcher.rst

@@ -0,0 +1,41 @@
+Stanza Matchers
+===============
+
+The Basic Matcher
+-----------------
+.. module:: sleekxmpp.xmlstream.matcher.base
+
+.. autoclass:: MatcherBase
+    :members:
+
+
+ID Matching
+-----------
+.. module:: sleekxmpp.xmlstream.matcher.id
+
+.. autoclass:: MatcherId
+    :members:
+
+
+Stanza Path Matching
+--------------------
+.. module:: sleekxmpp.xmlstream.matcher.stanzapath
+
+.. autoclass:: StanzaPath
+    :members:
+
+
+XPath
+-----
+.. module:: sleekxmpp.xmlstream.matcher.xpath
+
+.. autoclass:: MatchXPath
+    :members:
+
+
+XMLMask
+-------
+.. module:: sleekxmpp.xmlstream.matcher.xmlmask
+
+.. autoclass:: MatchXMLMask
+    :members:

docs/api/xmlstream/scheduler.rst

@@ -0,0 +1,11 @@
+=========
+Scheduler
+=========
+
+.. module:: sleekxmpp.xmlstream.scheduler
+
+.. autoclass:: Task
+    :members:
+
+.. autoclass:: Scheduler
+    :members:

docs/api/xmlstream/stanzabase.rst

@@ -0,0 +1,123 @@
+.. _stanzabase:
+
+==============
+Stanza Objects
+==============
+
+.. module:: sleekxmpp.xmlstream.stanzabase
+
+The :mod:`~sleekmxpp.xmlstream.stanzabase` module provides a wrapper for the
+standard :mod:`~xml.etree.ElementTree` module that makes working with XML
+less painful. Instead of having to manually move up and down an element
+tree and insert subelements and attributes, you can interact with an object
+that behaves like a normal dictionary or JSON object, which silently maps
+keys to XML attributes and elements behind the scenes.
+
+Overview
+--------
+
+The usefulness of this layer grows as the XML you have to work with
+becomes nested. The base unit here, :class:`ElementBase`, can map to a
+single XML element, or several depending on how advanced of a mapping
+is desired from interface keys to XML structures. For example, a single
+:class:`ElementBase` derived class could easily describe:
+
+.. code-block:: xml
+
+    <message to="user@example.com" from="friend@example.com">
+      <body>Hi!</body>
+      <x:extra>
+        <x:item>Custom item 1</x:item>
+        <x:item>Custom item 2</x:item>
+        <x:item>Custom item 3</x:item>
+      </x:extra>
+    </message>
+
+If that chunk of XML were put in the :class:`ElementBase` instance
+``msg``, we could extract the data from the XML using::
+
+    >>> msg['extra']
+    ['Custom item 1', 'Custom item 2', 'Custom item 3']
+
+Provided we set up the handler for the ``'extra'`` interface to load the
+``<x:item>`` element content into a list.
+
+The key concept is that given an XML structure that will be repeatedly
+used, we can define a set of :term:`interfaces` which when we read from,
+write to, or delete, will automatically manipulate the underlying XML
+as needed. In addition, some of these interfaces may in turn reference
+child objects which expose interfaces for particularly complex child
+elements of the original XML chunk.
+
+.. seealso::
+    :ref:`create-stanza-interfaces`.
+
+Because the :mod:`~sleekxmpp.xmlstream.stanzabase` module was developed
+as part of an `XMPP <http://xmpp.org>`_ library, these chunks of XML are
+referred to as :term:`stanzas <stanza>`, and in SleekXMPP we refer to a
+subclass of :class:`ElementBase` which defines the interfaces needed for
+interacting with a given :term:`stanza` a :term:`stanza object`.
+
+To make dealing with more complicated and nested :term:`stanzas <stanza>`
+or XML chunks easier, :term:`stanza objects <stanza object>` can be
+composed in two ways: as iterable child objects or as plugins. Iterable
+child stanzas, or :term:`substanzas`, are accessible through a special
+``'substanzas'`` interface. This option is useful for stanzas which
+may contain more than one of the same kind of element. When there is
+only one child element, the plugin method is more useful. For plugins,
+a parent stanza object delegates one of its XML child elements to the
+plugin stanza object. Here is an example:
+
+.. code-block:: xml
+
+    <iq type="result">
+      <query xmlns="http://jabber.org/protocol/disco#info">
+        <identity category="client" type="bot" name="SleekXMPP Bot" />
+      </query>
+    </iq>
+
+We can can arrange this stanza into two objects: an outer, wrapper object for
+dealing with the ``<iq />`` element and its attributes, and a plugin object to
+control the ``<query />`` payload element. If we give the plugin object the
+name ``'disco_info'`` (using its :attr:`ElementBase.plugin_attrib` value), then
+we can access the plugin as so::
+
+    >>> iq['disco_info']
+    '<query xmlns="http://jabber.org/protocol/disco#info">
+      <identity category="client" type="bot" name="SleekXMPP Bot" />
+    </query>'
+
+We can then drill down through the plugin object's interfaces as desired::
+
+    >>> iq['disco_info']['identities']
+    [('client', 'bot', 'SleekXMPP Bot')]
+
+Plugins may also add new interfaces to the parent stanza object as if they
+had been defined by the parent directly, and can also override the behaviour
+of an interface defined by the parent.
+
+.. seealso::
+
+    - :ref:`create-stanza-plugins`
+    - :ref:`create-extension-plugins`
+    - :ref:`override-parent-interfaces`
+     
+
+Registering Stanza Plugins
+--------------------------
+
+.. autofunction:: register_stanza_plugin
+
+ElementBase
+-----------
+
+.. autoclass:: ElementBase
+    :members:
+    :private-members:
+    :special-members:
+
+StanzaBase
+----------
+
+.. autoclass:: StanzaBase
+    :members:

docs/api/xmlstream/tostring.rst

@@ -0,0 +1,46 @@
+.. module:: sleekxmpp.xmlstream.tostring
+
+.. _tostring:
+
+XML Serialization
+=================
+
+Since the XML layer of SleekXMPP is based on :mod:`~xml.etree.ElementTree`,
+why not just use the built-in :func:`~xml.etree.ElementTree.tostring`
+method? The answer is that using that method produces ugly results when
+using namespaces. The :func:`tostring()` method used here intelligently
+hides namespaces when able and does not introduce excessive namespace
+prefixes::
+
+    >>> from sleekxmpp.xmlstream.tostring import tostring
+    >>> from xml.etree import cElementTree as ET
+    >>> xml = ET.fromstring('<foo xmlns="bar"><baz /></foo>')
+    >>> ET.tostring(xml)
+    '<ns0:foo xmlns:ns0="bar"><ns0:baz /></foo>'
+    >>> tostring(xml)
+    '<foo xmlns="bar"><baz /></foo>'
+
+As a side effect of this namespace hiding, using :func:`tostring()` may
+produce unexpected results depending on how the :func:`tostring()` method
+is invoked. For example, when sending XML on the wire, the main XMPP
+stanzas with their namespace of ``jabber:client`` will not include the
+namespace because that is already declared by the stream header. But, if
+you create a :class:`~sleekxmpp.stanza.message.Message` instance and dump
+it to the terminal, the ``jabber:client`` namespace will appear.
+
+.. autofunction:: tostring
+
+Escaping Special Characters
+---------------------------
+
+In order to prevent errors when sending arbitrary text as the textual
+content of an XML element, certain characters must be escaped. These
+are: ``&``, ``<``, ``>``, ``"``, and ``'``. The default escaping
+mechanism is to replace those characters with their equivalent escape
+entities: ``&amp;``, ``&lt;``, ``&gt;``, ``&apos;``, and ``&quot;``.
+
+In the future, the use of CDATA sections may be allowed to reduce the
+size of escaped text or for when other XMPP processing agents do not
+undertand these entities.
+
+.. autofunction:: xml_escape

docs/api/xmlstream/xmlstream.rst

@@ -0,0 +1,10 @@
+==========
+XML Stream
+==========
+
+.. module:: sleekxmpp.xmlstream.xmlstream
+
+.. autoexception:: RestartStream
+
+.. autoclass:: XMLStream
+    :members:

docs/architecture.rst

@@ -17,21 +17,21 @@ of the tedium of creating/manipulating XML.
 
 The Foundation: XMLStream
 -------------------------
-``XMLStream`` is a mostly XMPP-agnostic class whose purpose is to read
-and write from a bi-directional XML stream. It also allows for callback
-functions to execute when XML matching given patterns is received; these
-callbacks are also referred to as :term:`stream handlers <stream handler>`.
-The class also provides a basic eventing system which can be triggered
-either manually or on a timed schedule.
+:class:`~sleekxmpp.xmlstream.xmlstream.XMLStream` is a mostly XMPP-agnostic
+class whose purpose is to read and write from a bi-directional XML stream.
+It also allows for callback functions to execute when XML matching given
+patterns is received; these callbacks are also referred to as :term:`stream
+handlers <stream handler>`. The class also provides a basic eventing system
+which can be triggered either manually or on a timed schedule.
 
 The Main Threads
 ~~~~~~~~~~~~~~~~
-``XMLStream`` instances run using at least three background threads: the
-send thread, the read thread, and the scheduler thread. The send thread is
-in charge of monitoring the send queue and writing text to the outgoing
-XML stream. The read thread pulls text off of the incoming XML stream and
-stores the results in an event queue. The scheduler thread is used to emit
-events after a given period of time.
+:class:`~sleekxmpp.xmlstream.xmlstream.XMLStream` instances run using at
+least three background threads: the send thread, the read thread, and the
+scheduler thread. The send thread is in charge of monitoring the send queue
+and writing text to the outgoing XML stream. The read thread pulls text off
+of the incoming XML stream and stores the results in an event queue. The
+scheduler thread is used to emit events after a given period of time.
 
 Additionally, the main event processing loop may be executed in its
 own thread if SleekXMPP is being used in the background for another
@@ -61,9 +61,10 @@ when this bit of XML is received (with an assumed namespace of
    new object is determined using a map of namespaced element names to
    classes.
 
-   Our incoming XML is thus turned into a ``Message`` :term:`stanza object`
-   because the namespaced element name ``{jabber:client}message`` is
-   associated with the class ``sleekxmpp.stanza.Message``.
+   Our incoming XML is thus turned into a :class:`~sleekxmpp.stanza.Message`
+   :term:`stanza object` because the namespaced element name
+   ``{jabber:client}message`` is associated with the class
+   :class:`~sleekxmpp.stanza.Message`.
 
 2. **Match stanza objects to callbacks.**
 
@@ -72,8 +73,8 @@ when this bit of XML is received (with an assumed namespace of
    :term:`stanza object` is paired with a reference to the handler and
    placed into the event queue.
 
-   Our ``Message`` object is thus paired with the message stanza handler
-   ``BaseXMPP._handle_message`` to create the tuple::
+   Our :class:`~sleekxmpp.stanza.Message` object is thus paired with the message stanza handler
+   :meth:`BaseXMPP._handle_message` to create the tuple::
 
        ('stanza', stanza_obj, handler)
 
@@ -88,7 +89,7 @@ when this bit of XML is received (with an assumed namespace of
    parameter.
 
    .. warning:: 
-       The callback, aka :term:`stream handler`, is executed in the main
+       The callback, aka :term:`stream handler`, is executed in the main event
        processing thread. If the handler blocks, event processing will also
        block.
 
@@ -96,20 +97,22 @@ when this bit of XML is received (with an assumed namespace of
 
    Since a :term:`stream handler` shouldn't block, if extensive processing
    for a stanza is required (such as needing to send and receive an
-   ``Iq`` stanza), then custom events must be used. These events are not
-   explicitly tied to the incoming XML stream and may be raised at any
-   time. Importantly, these events may be handled in their own thread.
+   :class:`~sleekxmpp.stanza.Iq` stanza), then custom events must be used.
+   These events are not explicitly tied to the incoming XML stream and may
+   be raised at any time. Importantly, these events may be handled in their
+   own thread.
 
    When the event is raised, a copy of the stanza is created for each
-   handler registered for the event. In contrast to :term:`stream handlers <stream handler>`, 
-   these functions are referred to as :term:`event handlers <event handler>`. 
-   Each stanza/handler pair is then put into the event queue.
+   handler registered for the event. In contrast to :term:`stream handlers
+   <stream handler>`, these functions are referred to as :term:`event
+   handlers <event handler>`. Each stanza/handler pair is then put into the
+   event queue.
 
    .. note::
        It is possible to skip the event queue and process an event immediately
        by using ``direct=True`` when raising the event.
 
-   The code for ``BaseXMPP._handle_message`` follows this pattern, and
+   The code for :meth:`BaseXMPP._handle_message` follows this pattern, and
    raises a ``'message'`` event::
 
        self.event('message', msg)
@@ -145,125 +148,30 @@ when this bit of XML is received (with an assumed namespace of
 
 Raising XMPP Awareness: BaseXMPP
 --------------------------------
-While ``XMLStream`` attempts to shy away from anything too XMPP specific,
-``BaseXMPP``'s sole purpose is to provide foundational support for sending
-and receiving XMPP stanzas. This support includes registering the basic
-message, presence, and iq stanzas, methods for creating and sending
-stanzas, and default handlers for incoming messages and keeping track of
-presence notifications.
+While :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream` attempts to shy away
+from anything too XMPP specific, :class:`~sleekxmpp.basexmpp.BaseXMPP`'s
+sole purpose is to provide foundational support for sending and receiving
+XMPP stanzas. This support includes registering the basic message,
+presence, and iq stanzas, methods for creating and sending stanzas, and
+default handlers for incoming messages and keeping track of presence
+notifications.
 
 The plugin system for adding new XEP support is also maintained by
-``BaseXMPP``.
+:class:`~sleekxmpp.basexmpp.BaseXMPP`.
 
 .. index:: ClientXMPP, BaseXMPP
 
 ClientXMPP
 ----------
-``ClientXMPP`` extends ``BaseXMPP`` with additional logic for connecting to
-an XMPP server by performing DNS lookups. It also adds support for stream
+:class:`~sleekxmpp.clientxmpp.ClientXMPP` extends
+:class:`~sleekxmpp.clientxmpp.BaseXMPP` with additional logic for connecting
+to an XMPP server by performing DNS lookups. It also adds support for stream
 features such as STARTTLS and SASL.
 
 .. index:: ComponentXMPP, BaseXMPP
 
 ComponentXMPP
 -------------
-``ComponentXMPP`` is only a thin layer on top of ``BaseXMPP`` that
-implements the component handshake protocol.
-
-.. index::
-    double: object; stanza
-
-Stanza Objects: A Brief Look
-----------------------------
-.. seealso::
-    See :ref:`api-stanza-objects` for a more detailed overview.
-
-Almost worthy of their own standalone library, :term:`stanza objects <stanza object>`
-are wrappers for XML objects which expose dictionary like interfaces
-for manipulating their XML content. For example, consider the XML:
-
-.. code-block:: xml
-
-    <message />
-
-A very plain element to start with, but we can create a :term:`stanza object`
-using ``sleekxmpp.stanza.Message`` as so::
-
-    msg = Message(xml=ET.fromstring("<message />"))
-
-The ``Message`` stanza class defines interfaces such as ``'body'`` and
-``'to'``, so we can assign values to those interfaces to include new XML
-content::
-
-    msg['body'] = "Following so far?"
-    msg['to'] = 'user@example.com'
-
-Dumping the XML content of ``msg`` (using ``msg.xml``), we find:
-
-.. code-block:: xml
-
-    <message to="user@example.com">
-      <body>Following so far?</body>
-    </message>
-
-The process is similar for reading from interfaces and deleting interface
-contents. A :term:`stanza object` behaves very similarly to a regular
-``dict`` object: you may assign to keys, read from keys, and ``del`` keys.
-
-Stanza interfaces come with built-in behaviours such as adding/removing
-attribute and sub element values. However, a lot of the time more custom
-logic is needed. This can be provided by defining methods of the form
-``get_*``, ``set_*``, and ``del_*`` for any interface which requires custom
-behaviour.
-
-Stanza Plugins
-~~~~~~~~~~~~~~
-Since it is generally possible to embed one XML element inside another,
-:term:`stanza objects <stanza object>` may be nested. Nested 
-:term:`stanza objects <stanza object>` are referred to as :term:`stanza plugins <stanza plugin>`
-or :term:`substanzas <substanza>`.
-
-A :term:`stanza plugin` exposes its own interfaces by adding a new
-interface to its parent stanza. To demonstrate, consider these two stanza
-class definitions using ``sleekxmpp.xmlstream.ElementBase``:
-
-
-.. code-block:: python
-
-    class Parent(ElementBase):
-        name = "the-parent-xml-element-name"
-        namespace = "the-parent-namespace"
-        interfaces = set(('foo', 'bar'))
-
-    class Child(ElementBase):
-        name = "the-child-xml-element-name"
-        namespace = "the-child-namespace"
-        plugin_attrib = 'child'
-        interfaces = set(('baz',))
-
-
-If we register the ``Child`` stanza as a plugin of the ``Parent`` stanza as
-so, using ``sleekxmpp.xmlstream.register_stanza_plugin``::
-
-    register_stanza_plugin(Parent, Child)
-
-Then we can access content in the child stanza through the parent.
-Note that the interface used to access the child stanza is the same as
-``Child.plugin_attrib``::
-
-    parent = Parent()
-    parent['foo'] = 'a'
-    parent['child']['baz'] = 'b'
-
-The above code would produce:
-
-.. code-block:: xml
-
-    <the-parent-xml-element xmlns="the-parent-namespace" foo="a">
-      <the-child-xml-element xmlsn="the-child-namespace" baz="b" />
-    </the-parent-xml-element>
-
-It is also possible to allow a :term:`substanza` to appear multiple times
-by using ``iterable=True`` in the ``register_stanza_plugin`` call. All
-iterable :term:`substanzas <substanza>` can be accessed using a standard
-``substanzas`` interface.
+:class:`~sleekxmpp.componentxmpp.ComponentXMPP` is only a thin layer on top of
+:class:`~sleekxmpp.basexmpp.BaseXMPP` that implements the component handshake
+protocol.

docs/conf.py

@@ -16,7 +16,7 @@ import sys, os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -25,7 +25,7 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -50,7 +50,7 @@ copyright = u'2011, Nathan Fritz, Lance Stout'
 # The short X.Y version.
 version = '1.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0RC1'
+release = '1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -81,7 +81,7 @@ exclude_patterns = ['_build']
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'default'
+pygments_style = 'tango'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
@@ -218,3 +218,5 @@ man_pages = [
     ('index', 'sleekxmpp', u'SleekXMPP Documentation',
      [u'Nathan Fritz, Lance Stout'], 1)
 ]
+
+intersphinx_mapping = {'python': ('http://docs.python.org/3.2', 'python-objects.inv')}

docs/create_plugin.rst

@@ -1,3 +1,5 @@
+.. _create-plugin:
+
 Creating a SleekXMPP Plugin
 ===========================
 

docs/getting_started/component.rst

@@ -1,2 +1,75 @@
+.. _echocomponent:
+
+=================================
 Create and Run a Server Component
 =================================
+
+.. note::
+    
+    If you have any issues working through this quickstart guide
+    or the other tutorials here, please either send a message to the
+    `mailing list <http://groups.google.com/group/sleekxmpp-discussion>`_
+    or join the chat room at `sleek@conference.jabber.org
+    <xmpp:sleek@conference.jabber.org?join>`_.
+
+If you have not yet installed SleekXMPP, do so now by either checking out a version
+from `Github <http://github.com/fritzy/SleekXMPP>`_, or installing it using ``pip``
+or ``easy_install``.
+
+.. code-block:: sh
+
+    pip install sleekxmpp  # Or: easy_install sleekxmpp
+
+
+Many XMPP applications eventually graduate to requiring to run as a server 
+component in order to meet scalability requirements. To demonstrate how to 
+turn an XMPP client bot into a component, we'll turn the echobot example
+(:ref:`echobot`) into a component version.
+
+The first difference is that we will add an additional import statement:
+
+.. code-block:: python
+
+    from sleekxmpp.componentxmpp import ComponentXMPP
+
+Likewise, we will change the bot's class definition to match:
+
+.. code-block:: python
+
+    class EchoComponent(ComponentXMPP):
+
+        def __init__(self, jid, secret, server, port):
+            ComponentXMPP.__init__(self, jid, secret, server, port)
+
+A component instance requires two extra parameters compared to a client
+instance: ``server`` and ``port``. These specifiy the name and port of
+the XMPP server that will be accepting the component. For example, for
+a MUC component, the following could be used:
+
+.. code-block:: python
+
+    muc = ComponentXMPP('muc.sleekxmpp.com', '******', 'sleekxmpp.com', 5555)
+
+.. note::
+
+    The ``server`` value is **NOT** derived from the provided JID for the
+    component, unlike with client connections.
+
+One difference with the component version is that we do not have
+to handle the :term:`session_start` event if we don't wish to deal
+with presence.
+
+The other, main difference with components is that the
+``'from'`` value for every stanza must be explicitly set, since
+components may send stanzas from multiple JIDs. To do so,
+the :meth:`~sleekxmpp.basexmpp.BaseXMPP.send_message()` and
+:meth:`~sleekxmpp.basexmpp.BaseXMPP.send_presence()` accept the parameters
+``mfrom`` and ``pfrom``, respectively. For any method that uses
+:class:`~sleekxmpp.stanza.iq.Iq` stanzas, ``ifrom`` may be used.
+
+
+Final Product
+-------------
+
+.. include:: ../../examples/echo_component.py
+    :literal:

docs/getting_started/echobot.rst

@@ -69,8 +69,8 @@ use ASCII. We can get Python to use UTF-8 as the default encoding by including:
 .. code-block:: python
 
     if sys.version_info < (3, 0):
-        reload(sys)
-        sys.setdefaultencoding('utf8')
+        from sleekxmpp.util.misc_ops import setdefaultencoding
+        setdefaultencoding('utf8')
 
 .. warning::
 

docs/getting_started/iq.rst

@@ -1,2 +1,182 @@
 Send/Receive IQ Stanzas
 =======================
+
+Unlike :class:`~sleekxmpp.stanza.message.Message` and
+:class:`~sleekxmpp.stanza.presence.Presence` stanzas which only use
+text data for basic usage, :class:`~sleekxmpp.stanza.iq.Iq` stanzas
+require using XML payloads, and generally entail creating a new
+SleekXMPP plugin to provide the necessary convenience methods to
+make working with them easier.
+
+Basic Use
+---------
+
+XMPP's use of :class:`~sleekxmpp.stanza.iq.Iq` stanzas is built around
+namespaced ``<query />`` elements. For clients, just sending the
+empty ``<query />`` element will suffice for retrieving information. For
+example, a very basic implementation of service discovery would just
+need to be able to send:
+
+.. code-block:: xml
+
+    <iq to="user@example.com" type="get" id="1">
+      <query xmlns="http://jabber.org/protocol/disco#info" />
+    </iq>
+
+Creating Iq Stanzas
+~~~~~~~~~~~~~~~~~~~
+
+SleekXMPP provides built-in support for creating basic :class:`~sleekxmpp.stanza.iq.Iq`
+stanzas this way. The relevant methods are:
+
+* :meth:`~sleekxmpp.basexmpp.BaseXMPP.make_iq`
+* :meth:`~sleekxmpp.basexmpp.BaseXMPP.make_iq_get`
+* :meth:`~sleekxmpp.basexmpp.BaseXMPP.make_iq_set`
+* :meth:`~sleekxmpp.basexmpp.BaseXMPP.make_iq_result`
+* :meth:`~sleekxmpp.basexmpp.BaseXMPP.make_iq_error`
+* :meth:`~sleekxmpp.basexmpp.BaseXMPP.make_iq_query`
+
+These methods all follow the same pattern: create or modify an existing 
+:class:`~sleekxmpp.stanza.iq.Iq` stanza, set the ``'type'`` value based
+on the method name, and finally add a ``<query />`` element with the given
+namespace. For example, to produce the query above, you would use:
+
+.. code-block:: python
+
+    self.make_iq_get(queryxmlns='http://jabber.org/protocol/disco#info',
+                     ito='user@example.com')
+
+
+Sending Iq Stanzas
+~~~~~~~~~~~~~~~~~~
+
+Once an :class:`~sleekxmpp.stanza.iq.Iq` stanza is created, sending it
+over the wire is done using its :meth:`~sleekxmpp.stanza.iq.Iq.send()`
+method, like any other stanza object. However, there are a few extra
+options to control how to wait for the query's response.
+
+These options are:
+
+* ``block``: The default behaviour is that :meth:`~sleekxmpp.stanza.iq.Iq.send()`
+  will block until a response is received and the response stanza will be the
+  return value. Setting ``block`` to ``False`` will cause the call to return
+  immediately. In which case, you will need to arrange some way to capture
+  the response stanza if you need it.
+
+* ``timeout``: When using the blocking behaviour, the call will eventually
+  timeout with an error. The default timeout is 30 seconds, but this may
+  be overidden two ways. To change the timeout globally, set:
+
+    .. code-block:: python
+
+        self.response_timeout = 10
+
+  To change the timeout for a single call, the ``timeout`` parameter works:
+
+    .. code-block:: python
+        
+        iq.send(timeout=60)
+
+* ``callback``: When not using a blocking call, using the ``callback``
+  argument is a simple way to register a handler that will execute
+  whenever a response is finally received. Using this method, there
+  is no timeout limit. In case you need to remove the callback, the
+  name of the newly created callback is returned.
+
+    .. code-block:: python
+
+       cb_name = iq.send(callback=self.a_callback) 
+
+       # ... later if we need to cancel
+       self.remove_handler(cb_name)
+
+Properly working with :class:`~sleekxmpp.stanza.iq.Iq` stanzas requires
+handling the intended, normal flow, error responses, and timed out
+requests. To make this easier, two exceptions may be thrown by
+:meth:`~sleekxmpp.stanza.iq.Iq.send()`: :exc:`~sleekxmpp.exceptions.IqError`
+and :exc:`~sleekxmpp.exceptions.IqTimeout`. These exceptions only
+apply to the default, blocking calls.
+
+.. code-block:: python
+
+    try:
+        resp = iq.send()
+        # ... do stuff with expected Iq result
+    except IqError as e:
+        err_resp = e.iq
+        # ... handle error case
+    except IqTimeout:
+        # ... no response received in time
+        pass
+
+If you do not care to distinguish between errors and timeouts, then you
+can combine both cases with a generic :exc:`~sleekxmpp.exceptions.XMPPError`
+exception:
+
+.. code-block:: python
+
+    try:
+        resp = iq.send()
+    except XMPPError:
+        # ... Don't care about the response
+        pass
+
+Advanced Use
+------------
+
+Going beyond the basics provided by SleekXMPP requires building at least a
+rudimentary SleekXMPP plugin to create a :term:`stanza object` for
+interfacting with the :class:`~sleekxmpp.stanza.iq.Iq` payload.
+
+.. seealso::
+
+    * :ref:`create-plugin`
+    * :ref:`work-with-stanzas`
+    * :ref:`using-handlers-matchers`
+    
+
+The typical way to respond to :class:`~sleekxmpp.stanza.iq.Iq` requests is
+to register stream handlers. As an example, suppose we create a stanza class
+named ``CustomXEP`` which uses the XML element ``<query xmlns="custom-xep" />``,
+and has a :attr:`~sleekxmpp.xmlstream.stanzabase.ElementBase.plugin_attrib` value
+of ``custom_xep``.
+
+There are two types of incoming :class:`~sleekxmpp.stanza.iq.Iq` requests:
+``get`` and ``set``. You can register a handler that will accept both and then
+filter by type as needed, as so:
+
+.. code-block:: python
+
+    self.register_handler(Callback(
+        'CustomXEP Handler',
+        StanzaPath('iq/custom_xep'),
+        self._handle_custom_iq))
+
+    # ...
+
+    def _handle_custom_iq(self, iq):
+        if iq['type'] == 'get':
+            # ...
+            pass
+        elif iq['type'] == 'set':
+            # ...
+            pass
+        else:
+            # ... This will capture error responses too
+            pass
+
+If you want to filter out query types beforehand, you can adjust the matching
+filter by using ``@type=get`` or ``@type=set`` if you are using the recommended
+:class:`~sleekxmpp.xmlstream.matcher.stanzapath.StanzaPath` matcher.
+
+.. code-block:: python
+
+    self.register_handler(Callback(
+        'CustomXEP Handler',
+        StanzaPath('iq@type=get/custom_xep'),
+        self._handle_custom_iq_get))
+
+    # ...
+
+    def _handle_custom_iq_get(self, iq):
+        assert(iq['type'] == 'get')

docs/getting_started/muc.rst

@@ -1,2 +1,208 @@
+.. _mucbot:
+
+=========================
 Mulit-User Chat (MUC) Bot
 =========================
+
+.. note::
+
+    If you have any issues working through this quickstart guide
+    or the other tutorials here, please either send a message to the
+    `mailing list <http://groups.google.com/group/sleekxmpp-discussion>`_
+    or join the chat room at `sleek@conference.jabber.org
+    <xmpp:sleek@conference.jabber.org?join>`_.
+
+If you have not yet installed SleekXMPP, do so now by either checking out a version
+from `Github <http://github.com/fritzy/SleekXMPP>`_, or installing it using ``pip``
+or ``easy_install``.
+
+.. code-block:: sh
+
+    pip install sleekxmpp  # Or: easy_install sleekxmpp
+
+
+Now that you've got the basic gist of using SleekXMPP by following the
+echobot example (:ref:`echobot`), we can use one of the bundled plugins
+to create a very popular XMPP starter project: a `Multi-User Chat`_
+(MUC) bot. Our bot will login to an XMPP server, join an MUC chat room
+and "lurk" indefinitely, responding with a generic message to anyone
+that mentions its nickname. It will also greet members as they join the
+chat room.
+
+.. _`multi-user chat`: http://xmpp.org/extensions/xep-0045.html
+
+Joining The Room
+----------------
+
+As usual, our code will be based on the pattern explained in :ref:`echobot`.
+To start, we create an ``MUCBot`` class based on
+:class:`ClientXMPP <sleekxmpp.clientxmpp.ClientXMPP>` and which accepts
+parameters for the JID of the MUC room to join, and the nick that the
+bot will use inside the chat room.  We also register an
+:term:`event handler` for the :term:`session_start` event.
+
+
+.. code-block:: python
+
+    import sleekxmpp
+
+    class MUCBot(sleekxmpp.ClientXMPP):
+
+        def __init__(self, jid, password, room, nick):
+            sleekxmpp.ClientXMPP.__init__(self, jid, password)
+
+            self.room = room
+            self.nick = nick
+
+            self.add_event_handler("session_start", self.start)
+
+After initialization, we also need to register the MUC (XEP-0045) plugin
+so that we can make use of the group chat plugin's methods and events.
+
+.. code-block:: python
+
+    xmpp.register_plugin('xep_0045')
+
+Finally, we can make our bot join the chat room once an XMPP session
+has been established:
+
+.. code-block:: python
+
+    def start(self, event):
+        self.get_roster()
+        self.send_presence()
+        self.plugin['xep_0045'].joinMUC(self.room,
+                                        self.nick,
+                                        wait=True)
+
+Note that as in :ref:`echobot`, we need to include send an initial presence and request
+the roster. Next, we want to join the group chat, so we call the
+``joinMUC`` method of the MUC plugin.
+
+.. note::
+
+    The :attr:`plugin <sleekxmpp.basexmpp.BaseXMPP.plugin>` attribute is
+    dictionary that maps to instances of plugins that we have previously
+    registered, by their names.
+
+
+Adding Functionality
+--------------------
+
+Currently, our bot just sits dormantly inside the chat room, but we
+would like it to respond to two distinct events by issuing a generic
+message in each case to the chat room. In particular, when a member
+mentions the bot's nickname inside the chat room, and when a member
+joins the chat room.
+
+Responding to Mentions
+~~~~~~~~~~~~~~~~~~~~~~
+
+Whenever a user mentions our bot's nickname in chat, our bot will
+respond with a generic message resembling *"I heard that, user."* We do
+this by examining all of the messages sent inside the chat and looking
+for the ones which contain the nickname string.
+
+First, we register an event handler for the :term:`groupchat_message`
+event inside the bot's ``__init__`` function.
+
+.. note::
+
+    We do not register a handler for the :term:`message` event in this
+    bot, but if we did, the group chat message would have been sent to
+    both handlers.
+
+.. code-block:: python
+
+    def __init__(self, jid, password, room, nick):
+        sleekxmpp.ClientXMPP.__init__(self, jid, password)
+
+        self.room = room
+        self.nick = nick
+
+        self.add_event_handler("session_start", self.start)
+        self.add_event_handler("groupchat_message", self.muc_message)
+
+Then, we can send our generic message whenever the bot's nickname gets
+mentioned.
+
+.. warning::
+
+    Always check that a message is not from yourself,
+    otherwise you will create an infinite loop responding
+    to your own messages.
+
+.. code-block:: python
+
+    def muc_message(self, msg):
+        if msg['mucnick'] != self.nick and self.nick in msg['body']:
+            self.send_message(mto=msg['from'].bare,
+                              mbody="I heard that, %s." % msg['mucnick'],
+                              mtype='groupchat')
+
+
+Greeting Members
+~~~~~~~~~~~~~~~~
+
+Now we want to greet member whenever they join the group chat. To
+do this we will use the dynamic ``muc::room@server::got_online`` [1]_
+event so it's a good idea to register an event handler for it.
+
+.. note::
+
+    The groupchat_presence event is triggered whenever a
+    presence stanza is received from any chat room, including
+    any presences you send yourself. To limit event handling
+    to a single room, use the events ``muc::room@server::presence``,
+    ``muc::room@server::got_online``, or ``muc::room@server::got_offline``.
+
+.. code-block:: python
+
+    def __init__(self, jid, password, room, nick):
+        sleekxmpp.ClientXMPP.__init__(self, jid, password)
+
+        self.room = room
+        self.nick = nick
+
+        self.add_event_handler("session_start", self.start)
+        self.add_event_handler("groupchat_message", self.muc_message)
+        self.add_event_handler("muc::%s::got_online" % self.room,
+                               self.muc_online)
+
+Now all that's left to do is to greet them:
+
+.. code-block:: python
+
+    def muc_online(self, presence):
+        if presence['muc']['nick'] != self.nick:
+            self.send_message(mto=presence['from'].bare,
+                              mbody="Hello, %s %s" % (presence['muc']['role'],
+                                                      presence['muc']['nick']),
+                              mtype='groupchat')
+
+.. [1] this is similar to the :term:`got_online` event and is sent by
+       the xep_0045 plugin whenever a member joins the referenced
+       MUC chat room.
+
+
+Final Product
+-------------
+
+.. compound::
+
+    The final step is to create a small runner script for initialising our ``MUCBot`` class and adding some
+    basic configuration options. By following the basic boilerplate pattern in :ref:`echobot`, we arrive
+    at the code below. To experiment with this example, you can use:
+
+    .. code-block:: sh
+
+            python muc.py -d -j jid@example.com -r room@muc.example.net -n lurkbot
+
+    which will prompt for the password, log in, and join the group chat. To test, open
+    your regular IM client and join the same group chat that you sent the bot to. You
+    will see ``lurkbot`` as one of the members in the group chat, and that it greeted
+    you upon entry. Send a message with the string "lurkbot" inside the body text, and you
+    will also see that it responds with our pre-programmed customized message.
+
+.. include:: ../../examples/muc.py
+    :literal:

docs/getting_started/proxy.rst

@@ -1,2 +1,42 @@
+.. _proxy:
+
+=========================
 Enable HTTP Proxy Support
 =========================
+
+.. note::
+    
+    If you have any issues working through this quickstart guide
+    or the other tutorials here, please either send a message to the
+    `mailing list <http://groups.google.com/group/sleekxmpp-discussion>`_
+    or join the chat room at `sleek@conference.jabber.org
+    <xmpp:sleek@conference.jabber.org?join>`_.
+
+In some instances, you may wish to route XMPP traffic through
+an HTTP proxy, probably to get around restrictive firewalls.
+SleekXMPP provides support for basic HTTP proxying with DIGEST
+authentication.
+
+Enabling proxy support is done in two steps. The first is to instruct SleekXMPP
+to use a proxy, and the second is to configure the proxy details:
+
+.. code-block:: python
+
+    xmpp = ClientXMPP(...)
+    xmpp.use_proxy = True
+    xmpp.proxy_config = {
+        'host': 'proxy.example.com',
+        'port': 5555,
+        'username': 'example_user',
+        'password': '******'
+    }
+
+The ``'username'`` and ``'password'`` fields are optional if the proxy does not
+require authentication.
+
+
+The Final Product
+-----------------
+
+.. include:: ../../examples/proxy_echo_client.py
+    :literal:

docs/handlersmatchers.rst

@@ -1,2 +1,4 @@
+.. _using-handlers-matchers:
+
 Using Stream Handlers and Matchers
 ==================================

docs/howto/stanzas.rst

@@ -0,0 +1,30 @@
+.. _work-with-stanzas:
+
+How to Work with Stanza Objects
+===============================
+
+
+.. _create-stanza-interfaces:
+
+Defining Stanza Interfaces
+--------------------------
+
+
+.. _create-stanza-plugins:
+
+Creating Stanza Plugins
+-----------------------
+
+
+
+.. _create-extension-plugins:
+
+Creating a Stanza Extension
+---------------------------
+
+
+
+.. _override-parent-interfaces:
+
+Overriding a Parent Stanza
+--------------------------

docs/index.rst

@@ -12,13 +12,8 @@ SleekXMPP
     ``master`` branch, while the latest development version is in the
     ``develop`` branch.
 
-    **Stable Releases**
-        - `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>`_
+    **Latest Stable Release**
+        - `1.0 <http://github.com/fritzy/SleekXMPP/zipball/1.0>`_
 
     **Develop Releases**
         - `Latest Develop Version <http://github.com/fritzy/SleekXMPP/zipball/develop>`_
@@ -64,6 +59,72 @@ SleekXMPP's design goals and philosphy are:
     sensible defaults and appropriate abstractions. XML can be ugly to work
     with, but it doesn't have to be that way.
 
+Here's your first SleekXMPP Bot:
+--------------------------------
+
+.. code-block:: python
+
+    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)
+
+            # If you wanted more functionality, here's how to register plugins:
+            # self.register_plugin('xep_0030') # Service Discovery
+            # self.register_plugin('xep_0199') # XMPP Ping
+
+            # Here's how to access plugins once you've registered them:
+            # self['xep_0030'].add_feature('echo_demo')
+
+            # 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()
+            self.get_roster()
+
+            # 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)
+
+
+
 Getting Started (with Examples)
 -------------------------------
 .. toctree::
@@ -84,8 +145,10 @@ Tutorials, FAQs, and How To Guides
 .. toctree::
     :maxdepth: 1
    
+    faq
     xeps
     xmpp_tdg
+    howto/stanzas
     create_plugin
     features
     sasl
@@ -113,8 +176,35 @@ API Reference
     
     event_index
     api/clientxmpp
+    api/componentxmpp
     api/basexmpp
-    api/xmlstream
+    api/exceptions
+    api/xmlstream/jid
+    api/xmlstream/stanzabase
+    api/xmlstream/handler
+    api/xmlstream/matcher
+    api/xmlstream/xmlstream
+    api/xmlstream/scheduler
+    api/xmlstream/tostring
+    api/xmlstream/filesocket
+
+Core Stanzas
+~~~~~~~~~~~~
+.. toctree::
+    :maxdepth: 2
+
+    api/stanza/rootstanza
+    api/stanza/message
+    api/stanza/presence
+    api/stanza/iq
+    api/stanza/error
+    api/stanza/stream_error
+
+Plugins
+~~~~~~~
+.. toctree::
+    :maxdepth: 2
+
 
 Additional Info
 ---------------
@@ -132,17 +222,24 @@ Additional Info
 
 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 member of the XMPP
-    Council.
+**Main Author:** `Nathan Fritz <http://andyet.net/team/fritzy>`_
+     `fritzy@netflint.net <xmpp:fritzy@netflint.net?message>`_,
+     `@fritzy <http://twitter.com/fritzy>`_
 
-**Co-Author:** Lance Stout
-    `lancestout@gmail.com <xmpp:lancestout@gmail.com?message>`_, 
-    `@lancestout <http://twitter.com/lancestout>`_
+     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 <http://andyet.net/team/lance>`_
+     `lancestout@gmail.com <xmpp:lancestout@gmail.com?message>`_,
+     `@lancestout <http://twitter.com/lancestout>`_
+
+Both Fritzy and Lance work for `&yet <http://andyet.net>`_, which specializes in
+realtime web and XMPP applications.
+
+    - `contact@andyet.net <mailto:contact@andyet.net>`_
+    - `XMPP Consulting <http://xmppconsulting.com>`_
 
 **Contributors:**
     - Brian Beggs (`macdiesel <http://github.com/macdiesel>`_)

docs/xeps.rst

@@ -1,2 +1,50 @@
 Supported XEPS
 ==============
+
+======= ============================= ================
+XEP     Description                   Notes
+======= ============================= ================
+`0004`_ Data forms                   
+`0009`_ Jabber RPC                   
+`0012`_ Last Activity             
+`0030`_ Service Discovery
+`0033`_ Extended Stanza Addressing
+`0045`_ Multi-User Chat (MUC)         Client-side only
+`0050`_ Ad-hoc Commands
+`0059`_ Result Set Management
+`0060`_ Publish/Subscribe (PubSub)    Client-side only
+`0066`_ Out-of-band Data
+`0078`_ Non-SASL Authentication
+`0082`_ XMPP Date and Time Profiles
+`0085`_ Chat-State Notifications
+`0086`_ Error Condition Mappings
+`0092`_ Software Version
+`0128`_ Service Discovery Extensions
+`0202`_ Entity Time
+`0203`_ Delayed Delivery
+`0224`_ Attention
+`0249`_ Direct MUC Invitations
+======= ============================= ================
+
+
+.. _0004: http://xmpp.org/extensions/xep-0004.html
+.. _0009: http://xmpp.org/extensions/xep-0009.html
+.. _0012: http://xmpp.org/extensions/xep-0012.html
+.. _0030: http://xmpp.org/extensions/xep-0030.html
+.. _0033: http://xmpp.org/extensions/xep-0033.html
+.. _0045: http://xmpp.org/extensions/xep-0045.html
+.. _0050: http://xmpp.org/extensions/xep-0050.html
+.. _0059: http://xmpp.org/extensions/xep-0059.html
+.. _0060: http://xmpp.org/extensions/xep-0060.html
+.. _0066: http://xmpp.org/extensions/xep-0066.html
+.. _0078: http://xmpp.org/extensions/xep-0078.html
+.. _0082: http://xmpp.org/extensions/xep-0082.html
+.. _0085: http://xmpp.org/extensions/xep-0085.html
+.. _0086: http://xmpp.org/extensions/xep-0086.html
+.. _0092: http://xmpp.org/extensions/xep-0092.html
+.. _0128: http://xmpp.org/extensions/xep-0128.html
+.. _0199: http://xmpp.org/extensions/xep-0199.html
+.. _0202: http://xmpp.org/extensions/xep-0202.html
+.. _0203: http://xmpp.org/extensions/xep-0203.html
+.. _0224: http://xmpp.org/extensions/xep-0224.html
+.. _0249: http://xmpp.org/extensions/xep-0249.html

examples/adhoc_provider.py

@@ -11,7 +11,6 @@
 
 import sys
 import logging
-import time
 import getpass
 from optparse import OptionParser
 
@@ -22,8 +21,8 @@ import sleekxmpp
 # throughout SleekXMPP, we will set the default encoding
 # ourselves to UTF-8.
 if sys.version_info < (3, 0):
-    reload(sys)
-    sys.setdefaultencoding('utf8')
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
 else:
     raw_input = input
 
@@ -41,7 +40,7 @@ class CommandBot(sleekxmpp.ClientXMPP):
         # 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
+        # listen for this event so that we we can initialize
         # our roster.
         self.add_event_handler("session_start", self.start)
 
@@ -50,7 +49,7 @@ class CommandBot(sleekxmpp.ClientXMPP):
         Process the session_start event.
 
         Typical actions for the session_start event are
-        requesting the roster and broadcasting an intial
+        requesting the roster and broadcasting an initial
         presence stanza.
 
         Arguments:
@@ -72,7 +71,7 @@ class CommandBot(sleekxmpp.ClientXMPP):
 
     def _handle_command(self, iq, session):
         """
-        Respond to the intial request for a command.
+        Respond to the initial request for a command.
 
         Arguments:
             iq      -- The iq stanza containing the command request.
@@ -192,14 +191,14 @@ if __name__ == '__main__':
 
     # 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
+        # If you do not have the dnspython 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)
+        xmpp.process(block=True)
         print("Done")
     else:
         print("Unable to connect.")

examples/adhoc_user.py

@@ -11,7 +11,6 @@
 
 import sys
 import logging
-import time
 import getpass
 from optparse import OptionParser
 
@@ -22,8 +21,8 @@ import sleekxmpp
 # throughout SleekXMPP, we will set the default encoding
 # ourselves to UTF-8.
 if sys.version_info < (3, 0):
-    reload(sys)
-    sys.setdefaultencoding('utf8')
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
 else:
     raw_input = input
 
@@ -44,7 +43,7 @@ class CommandUserBot(sleekxmpp.ClientXMPP):
         # 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
+        # listen for this event so that we we can initialize
         # our roster.
         self.add_event_handler("session_start", self.start)
         self.add_event_handler("message", self.message)
@@ -54,7 +53,7 @@ class CommandUserBot(sleekxmpp.ClientXMPP):
         Process the session_start event.
 
         Typical actions for the session_start event are
-        requesting the roster and broadcasting an intial
+        requesting the roster and broadcasting an initial
         presence stanza.
 
         Arguments:
@@ -198,14 +197,14 @@ if __name__ == '__main__':
 
     # 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
+        # If you do not have the dnspython 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)
+        xmpp.process(block=True)
         print("Done")
     else:
         print("Unable to connect.")

examples/admin_commands.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+    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
+import getpass
+from optparse import OptionParser
+
+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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class AdminCommands(sleekxmpp.ClientXMPP):
+
+    """
+    A simple SleekXMPP bot that uses admin commands to
+    add a new user to a server.
+    """
+
+    def __init__(self, jid, password, command):
+        sleekxmpp.ClientXMPP.__init__(self, jid, password)
+
+        self.command = command
+
+        self.add_event_handler("session_start", self.start)
+
+    def start(self, event):
+        """
+        Process the session_start event.
+
+        Typical actions for the session_start event are
+        requesting the roster and broadcasting an initial
+        presence stanza.
+
+        Arguments:
+            event -- An empty dictionary. The session_start
+                     event does not provide any additional
+                     data.
+        """
+        self.send_presence()
+        self.get_roster()
+
+        def command_success(iq, session):
+            print('Command completed')
+            if iq['command']['form']:
+                for var, field in iq['command']['form']['fields'].items():
+                    print('%s: %s' % (var, field['value']))
+            if iq['command']['notes']:
+                print('Command Notes:')
+                for note in iq['command']['notes']:
+                    print('%s: %s' % note)
+            self.disconnect()
+
+        def command_error(iq, session):
+            print('Error completing command')
+            print('%s: %s' % (iq['error']['condition'],
+                              iq['error']['text']))
+            self['xep_0050'].terminate_command(session)
+            self.disconnect()
+
+        def process_form(iq, session):
+            form = iq['command']['form']
+            answers = {}
+            for var, field in form['fields'].items():
+                if var != 'FORM_TYPE':
+                    if field['type'] == 'boolean':
+                        answers[var] = raw_input('%s (y/n): ' % field['label'])
+                        if answers[var].lower() in ('1', 'true', 'y', 'yes'):
+                            answers[var] = '1'
+                        else:
+                            answers[var] = '0'
+                    else:
+                        answers[var] = raw_input('%s: ' % field['label'])
+                else:
+                    answers['FORM_TYPE'] = field['value']
+            form['type'] = 'submit'
+            form['values'] = answers
+
+            session['next'] = command_success
+            session['payload'] = form
+
+            self['xep_0050'].complete_command(session)
+
+        session = {'next': process_form,
+                   'error': command_error}
+
+        command = self.command.replace('-', '_')
+        handler = getattr(self['xep_0133'], command, None)
+
+        if handler:
+            handler(session={
+                'next': process_form,
+                'error': command_error
+            })
+        else:
+            print('Invalid command name: %s' % self.command)
+            self.disconnect()
+
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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")
+    optp.add_option("-c", "--command", dest="command",
+                    help="admin command to use")
+
+    opts, args = optp.parse_args()
+
+    # Setup logging.
+    logging.basicConfig(level=opts.loglevel,
+                        format='%(levelname)-8s %(message)s')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+    if opts.command is None:
+        opts.command = raw_input("Admin command: ")
+
+    # Setup the CommandBot and register plugins. Note that while plugins may
+    # have interdependencies, the order in which you register them does
+    # not matter.
+    xmpp = AdminCommands(opts.jid, opts.password, opts.command)
+    xmpp.register_plugin('xep_0133') # Service Administration
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

examples/config.xml

@@ -1,10 +0,0 @@
-<config xmlns="sleekxmpp:config">
-  <jid>component.localhost</jid>
-  <secret>ssshh</secret>
-  <server>localhost</server>
-  <port>8888</port>
-
-  <query xmlns="jabber:iq:roster">
-    <item jid="user@example.com" subscription="both" />
-  </query>
-</config>

examples/config_component.py

@@ -1,192 +0,0 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-
-"""
-    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
-import time
-from optparse import OptionParser
-
-import sleekxmpp
-from sleekxmpp.componentxmpp import ComponentXMPP
-from sleekxmpp.stanza.roster import Roster
-from sleekxmpp.xmlstream import ElementBase
-from sleekxmpp.xmlstream.stanzabase import ET, registerStanzaPlugin
-
-# 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')
-else:
-    raw_input = input
-
-
-class Config(ElementBase):
-
-    """
-    In order to make loading and manipulating an XML config
-    file easier, we will create a custom stanza object for
-    our config XML file contents. See the documentation
-    on stanza objects for more information on how to create
-    and use stanza objects and stanza plugins.
-
-    We will reuse the IQ roster query stanza to store roster
-    information since it already exists.
-
-    Example config XML:
-      <config xmlns="sleekxmpp:config">
-        <jid>component.localhost</jid>
-        <secret>ssshh</secret>
-        <server>localhost</server>
-        <port>8888</port>
-
-        <query xmlns="jabber:iq:roster">
-          <item jid="user@example.com" subscription="both" />
-        </query>
-      </config>
-    """
-
-    name = "config"
-    namespace = "sleekxmpp:config"
-    interfaces = set(('jid', 'secret', 'server', 'port'))
-    sub_interfaces = interfaces
-
-
-registerStanzaPlugin(Config, Roster)
-
-
-class ConfigComponent(ComponentXMPP):
-
-    """
-    A simple SleekXMPP component that uses an external XML
-    file to store its configuration data. To make testing
-    that the component works, it will also echo messages sent
-    to it.
-    """
-
-    def __init__(self, config):
-        """
-        Create a ConfigComponent.
-
-        Arguments:
-            config      -- The XML contents of the config file.
-            config_file -- The XML config file object itself.
-        """
-        ComponentXMPP.__init__(self, config['jid'],
-                                     config['secret'],
-                                     config['server'],
-                                     config['port'])
-
-        # Store the roster information.
-        self.roster = config['roster']['items']
-
-        # The session_start event will be triggered when
-        # the component 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
-        # broadcast any needed initial presence stanzas.
-        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.
-
-        The typical action for the session_start event in a component
-        is to broadcast presence stanzas to all subscribers to the
-        component. Note that the component does not have a roster
-        provided by the XMPP server. In this case, we have possibly
-        saved a roster in the component's configuration file.
-
-        Since the component may use any number of JIDs, you should
-        also include the JID that is sending the presence.
-
-        Arguments:
-            event -- An empty dictionary. The session_start
-                     event does not provide any additional
-                     data.
-        """
-        for jid in self.roster:
-            if self.roster[jid]['subscription'] != 'none':
-                self.sendPresence(pfrom=self.jid, pto=jid)
-
-    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.
-
-        Since a component may send messages from any number of JIDs,
-        it is best to always include a from JID.
-
-        Arguments:
-            msg -- The received message stanza. See the documentation
-                   for stanza objects and the Message stanza to see
-                   how it may be used.
-        """
-        # The reply method will use the messages 'to' JID as the
-        # outgoing reply's 'from' JID.
-        msg.reply("Thanks for sending\n%(body)s" % msg).send()
-
-
-if __name__ == '__main__':
-    # Setup the command line arguments.
-    optp = OptionParser()
-
-    # 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)
-
-    # Component name and secret options.
-    optp.add_option("-c", "--config", help="path to config file",
-                    dest="config", default="config.xml")
-
-    opts, args = optp.parse_args()
-
-    # Setup logging.
-    logging.basicConfig(level=opts.loglevel,
-                        format='%(levelname)-8s %(message)s')
-
-    # Load configuration data.
-    config_file = open(opts.config, 'r+')
-    config_data = "\n".join([line for line in config_file])
-    config = Config(xml=ET.fromstring(config_data))
-    config_file.close()
-
-    # Setup the ConfigComponent and register plugins. Note that while plugins
-    # may have interdependencies, the order in which you register them does
-    # not matter.
-    xmpp = ConfigComponent(config)
-    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():
-        xmpp.process(threaded=False)
-        print("Done")
-    else:
-        print("Unable to connect.")

examples/custom_stanzas/custom_stanza_provider.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+    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
+import getpass
+from optparse import OptionParser
+
+import sleekxmpp
+
+from sleekxmpp import ClientXMPP, Iq
+from sleekxmpp.exceptions import IqError, IqTimeout, XMPPError
+from sleekxmpp.xmlstream import register_stanza_plugin
+from sleekxmpp.xmlstream.handler import Callback
+from sleekxmpp.xmlstream.matcher import StanzaPath
+from stanza import Action
+
+# 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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class ActionBot(sleekxmpp.ClientXMPP):
+
+    """
+    A simple SleekXMPP bot that receives a custom stanza
+    from another client.
+    """
+
+    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 initialize
+        # our roster.
+        self.add_event_handler("session_start", self.start)
+
+        self.registerHandler(
+          Callback('Some custom iq',
+            StanzaPath('iq@type=set/action'),
+            self._handle_action))
+
+        self.add_event_handler('custom_action',
+                self._handle_action_event,
+                threaded=True)
+
+        register_stanza_plugin(Iq, Action)
+
+    def start(self, event):
+        """
+        Process the session_start event.
+
+        Typical actions for the session_start event are
+        requesting the roster and broadcasting an initial
+        presence stanza.
+
+        Arguments:
+            event -- An empty dictionary. The session_start
+                     event does not provide any additional
+                     data.
+        """
+        self.send_presence()
+        self.get_roster()
+
+    def _handle_action(self, iq):
+        """
+        Raise an event for the stanza so that it can be processed in its
+        own thread without blocking the main stanza processing loop.
+        """
+        self.event('custom_action', iq)
+
+    def _handle_action_event(self, iq):
+        """
+        Respond to the custom action event.
+
+        Since one of the actions is to disconnect, this
+        event handler needs to be run in threaded mode, by
+        using `threaded=True` in the `add_event_handler` call.
+        """
+        method = iq['action']['method']
+        param = iq['action']['param']
+
+        if method == 'is_prime' and param == '2':
+            print("got message: %s" % iq)
+            iq.reply()
+            iq['action']['status'] = 'done'
+            iq.send()
+        elif method == 'bye':
+            print("got message: %s" % iq)
+            self.disconnect()
+        else:
+            print("got message: %s" % iq)
+            iq.reply()
+            iq['action']['status'] = 'error'
+            iq.send()
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+
+    # Setup the CommandBot and register plugins. Note that while plugins may
+    # have interdependencies, the order in which you register them does
+    # not matter.
+    xmpp = ActionBot(opts.jid, opts.password)
+    xmpp.register_plugin('xep_0030') # Service Discovery
+    xmpp.register_plugin('xep_0004') # Data Forms
+    xmpp.register_plugin('xep_0050') # Adhoc Commands
+    xmpp.register_plugin('xep_0199', {'keepalive': True, 'frequency':15})
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

examples/custom_stanzas/custom_stanza_user.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+    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
+import getpass
+from optparse import OptionParser
+
+import sleekxmpp
+from sleekxmpp import Iq
+from sleekxmpp.exceptions import XMPPError
+from sleekxmpp.xmlstream import register_stanza_plugin
+
+from stanza import Action
+
+# 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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class ActionUserBot(sleekxmpp.ClientXMPP):
+
+    """
+    A simple SleekXMPP bot that sends a custom action stanza
+    to another client.
+    """
+
+    def __init__(self, jid, password, other):
+        sleekxmpp.ClientXMPP.__init__(self, jid, password)
+
+        self.action_provider = other
+
+        # 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 initialize
+        # our roster.
+        self.add_event_handler("session_start", self.start, threaded=True)
+        self.add_event_handler("message", self.message)
+
+        register_stanza_plugin(Iq, Action)
+
+    def start(self, event):
+        """
+        Process the session_start event.
+
+        Typical actions for the session_start event are
+        requesting the roster and broadcasting an initial
+        presence stanza.
+
+        Arguments:
+            event -- An empty dictionary. The session_start
+                     event does not provide any additional
+                     data.
+        """
+        self.send_presence()
+        self.get_roster()
+
+        self.send_custom_iq()
+
+    def send_custom_iq(self):
+        """Create and send two custom actions.
+
+        If the first action was successful, then send
+        a shutdown command and then disconnect.
+        """
+        iq = self.Iq()
+        iq['to'] = self.action_provider
+        iq['type'] = 'set'
+        iq['action']['method'] = 'is_prime'
+        iq['action']['param'] = '2'
+
+        try:
+            resp = iq.send()
+            if resp['action']['status'] == 'done':
+                #sending bye
+                iq2 = self.Iq()
+                iq2['to'] = self.action_provider
+                iq2['type'] = 'set'
+                iq2['action']['method'] = 'bye'
+                iq2.send(block=False)
+            
+                # The wait=True delays the disconnect until the queue
+                # of stanzas to be sent becomes empty.
+                self.disconnect(wait=True)
+        except XMPPError:
+            print('There was an error sending the custom action.')
+
+    def message(self, msg):
+        """
+        Process incoming message stanzas.
+
+        Arguments:
+            msg -- The received message stanza.
+        """
+        logging.info(msg['body'])
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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")
+    optp.add_option("-o", "--other", dest="other",
+                    help="JID providing custom stanza")
+
+    opts, args = optp.parse_args()
+
+    # Setup logging.
+    logging.basicConfig(level=opts.loglevel,
+                        format='%(levelname)-8s %(message)s')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+    if opts.other is None:
+        opts.other = raw_input("JID Providing custom stanza: ")
+
+    # Setup the CommandBot and register plugins. Note that while plugins may
+    # have interdependencies, the order in which you register them does
+    # not matter.
+    xmpp = ActionUserBot(opts.jid, opts.password, opts.other)
+    xmpp.register_plugin('xep_0030') # Service Discovery
+    xmpp.register_plugin('xep_0004') # Data Forms
+    xmpp.register_plugin('xep_0050') # Adhoc Commands
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

examples/custom_stanzas/stanza.py

@@ -0,0 +1,56 @@
+from sleekxmpp.xmlstream import ElementBase
+
+class Action(ElementBase):
+
+    """
+    A stanza class for XML content of the form:
+
+    <action xmlns="sleekxmpp:custom:actions">
+      <method>X</method>
+      <param>X</param>
+      <status>X</status>
+    </action>
+    """
+   
+    #: The `name` field refers to the basic XML tag name of the
+    #: stanza. Here, the tag name will be 'action'.
+    name = 'action'
+
+    #: The namespace of the main XML tag.
+    namespace = 'sleekxmpp:custom:actions'
+
+    #: The `plugin_attrib` value is the name that can be used
+    #: with a parent stanza to access this stanza. For example
+    #: from an Iq stanza object, accessing:
+    #: 
+    #:     iq['action']
+    #: 
+    #: would reference an Action object, and will even create
+    #: an Action object and append it to the Iq stanza if
+    #: one doesn't already exist.
+    plugin_attrib = 'action'
+
+    #: Stanza objects expose dictionary-like interfaces for
+    #: accessing and manipulating substanzas and other values.
+    #: The set of interfaces defined here are the names of
+    #: these dictionary-like interfaces provided by this stanza
+    #: type. For example, an Action stanza object can use:
+    #:
+    #:     action['method'] = 'foo'
+    #:     print(action['param'])
+    #:     del action['status']
+    #:
+    #: to set, get, or remove its values.
+    interfaces = set(('method', 'param', 'status'))
+
+    #: By default, values in the `interfaces` set are mapped to
+    #: attribute values. This can be changed such that an interface
+    #: maps to a subelement's text value by adding interfaces to
+    #: the sub_interfaces set. For example, here all interfaces
+    #: are marked as sub_interfaces, and so the XML produced will
+    #: look like:
+    #: 
+    #:     <action xmlns="sleekxmpp:custom:actions">
+    #:       <method>foo</method>
+    #:     </action>
+    sub_interfaces = interfaces

examples/disco_browser.py

@@ -10,12 +10,12 @@
 """
 
 import sys
-import time
 import logging
 import getpass
 from optparse import OptionParser
 
 import sleekxmpp
+from sleekxmpp.exceptions import IqError, IqTimeout
 
 
 # Python versions before 3.0 do not use UTF-8 encoding
@@ -23,8 +23,8 @@ import sleekxmpp
 # throughout SleekXMPP, we will set the default encoding
 # ourselves to UTF-8.
 if sys.version_info < (3, 0):
-    reload(sys)
-    sys.setdefaultencoding('utf8')
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
 else:
     raw_input = input
 
@@ -61,16 +61,16 @@ class Disco(sleekxmpp.ClientXMPP):
         # 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
+        # listen for this event so that we we can initialize
         # our roster.
-        self.add_event_handler("session_start", self.start)
+        self.add_event_handler("session_start", self.start, threaded=True)
 
     def start(self, event):
         """
         Process the session_start event.
 
         Typical actions for the session_start event are
-        requesting the roster and broadcasting an intial
+        requesting the roster and broadcasting an initial
         presence stanza.
 
         In this case, we send disco#info and disco#items
@@ -84,50 +84,54 @@ class Disco(sleekxmpp.ClientXMPP):
         self.get_roster()
         self.send_presence()
 
-        if self.get in self.info_types:
-            # By using block=True, the result stanza will be
-            # returned. Execution will block until the reply is
-            # received. Non-blocking options would be to listen
-            # for the disco_info event, or passing a handler
-            # function using the callback parameter.
-            info = self['xep_0030'].get_info(jid=self.target_jid,
-                                             node=self.target_node,
-                                             block=True)
-        if self.get in self.items_types:
-            # The same applies from above. Listen for the
-            # disco_items event or pass a callback function
-            # if you need to process a non-blocking request.
-            items = self['xep_0030'].get_items(jid=self.target_jid,
-                                               node=self.target_node,
-                                               block=True)
+        try:
+            if self.get in self.info_types:
+                # By using block=True, the result stanza will be
+                # returned. Execution will block until the reply is
+                # received. Non-blocking options would be to listen
+                # for the disco_info event, or passing a handler
+                # function using the callback parameter.
+                info = self['xep_0030'].get_info(jid=self.target_jid,
+                                                 node=self.target_node,
+                                                 block=True)
+            elif self.get in self.items_types:
+                # The same applies from above. Listen for the
+                # disco_items event or pass a callback function
+                # if you need to process a non-blocking request.
+                items = self['xep_0030'].get_items(jid=self.target_jid,
+                                                   node=self.target_node,
+                                                   block=True)
+            else:
+                logging.error("Invalid disco request type.")
+                return
+        except IqError as e:
+            logging.error("Entity returned an error: %s" % e.iq['error']['condition'])
+        except IqTimeout:
+            logging.error("No response received.")
         else:
-            logging.error("Invalid disco request type.")
-            self.disconnect()
-            return
-
-        header = 'XMPP Service Discovery: %s' % self.target_jid
-        print(header)
-        print('-' * len(header))
-        if self.target_node != '':
-            print('Node: %s' % self.target_node)
+            header = 'XMPP Service Discovery: %s' % self.target_jid
+            print(header)
             print('-' * len(header))
+            if self.target_node != '':
+                print('Node: %s' % self.target_node)
+                print('-' * len(header))
 
-        if self.get in self.identity_types:
-            print('Identities:')
-            for identity in info['disco_info']['identities']:
-                print('  - %s' % str(identity))
+            if self.get in self.identity_types:
+                print('Identities:')
+                for identity in info['disco_info']['identities']:
+                    print('  - %s' % str(identity))
 
-        if self.get in self.feature_types:
-            print('Features:')
-            for feature in info['disco_info']['features']:
-                print('  - %s' % feature)
+            if self.get in self.feature_types:
+                print('Features:')
+                for feature in info['disco_info']['features']:
+                    print('  - %s' % feature)
 
-        if self.get in self.items_types:
-            print('Items:')
-            for item in items['disco_items']['items']:
-                print('  - %s' % str(item))
-
-        self.disconnect()
+            if self.get in self.items_types:
+                print('Items:')
+                for item in items['disco_items']['items']:
+                    print('  - %s' % str(item))
+        finally:
+            self.disconnect()
 
 
 if __name__ == '__main__':
@@ -188,13 +192,13 @@ if __name__ == '__main__':
 
     # 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
+        # If you do not have the dnspython 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)
+        xmpp.process(block=True)
     else:
         print("Unable to connect.")

examples/download_avatars.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2012  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+import sys
+import logging
+import getpass
+import threading
+from optparse import OptionParser
+
+import sleekxmpp
+from sleekxmpp.exceptions import XMPPError
+
+
+# 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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+FILE_TYPES = {
+    'image/png': 'png',
+    'image/gif': 'gif',
+    'image/jpeg': 'jpg'
+}
+
+
+class AvatarDownloader(sleekxmpp.ClientXMPP):
+
+    """
+    A basic script for downloading the avatars for a user's contacts.
+    """
+
+    def __init__(self, jid, password):
+        sleekxmpp.ClientXMPP.__init__(self, jid, password)
+        self.add_event_handler("session_start", self.start, threaded=True)
+        self.add_event_handler("changed_status", self.wait_for_presences)
+
+        self.add_event_handler('vcard_avatar_update', self.on_vcard_avatar)
+        self.add_event_handler('avatar_metadata_publish', self.on_avatar)
+
+        self.received = set()
+        self.presences_received = threading.Event()
+
+    def start(self, event):
+        """
+        Process the session_start event.
+
+        Typical actions for the session_start event are
+        requesting the roster and broadcasting an initial
+        presence stanza.
+
+        Arguments:
+            event -- An empty dictionary. The session_start
+                     event does not provide any additional
+                     data.
+        """
+        self.send_presence()
+        self.get_roster()
+
+        print('Waiting for presence updates...\n')
+        self.presences_received.wait(15)
+        self.disconnect(wait=True)
+
+    def on_vcard_avatar(self, pres):
+        print("Received vCard avatar update from %s" % pres['from'].bare)
+        try:
+            result = self['xep_0054'].get_vcard(pres['from'], cached=True)
+        except XMPPError:
+            print("Error retrieving avatar for %s" % pres['from'])
+            return
+        avatar = result['vcard_temp']['PHOTO']
+
+        filetype = FILE_TYPES.get(avatar['TYPE'], 'png')
+        filename = 'vcard_avatar_%s_%s.%s' % (
+                pres['from'].bare,
+                pres['vcard_temp_update']['photo'],
+                filetype)
+        with open(filename, 'w+') as img:
+            img.write(avatar['BINVAL'])
+
+    def on_avatar(self, msg):
+        print("Received avatar update from %s" % msg['from'])
+        metadata = msg['pubsub_event']['items']['item']['avatar_metadata']
+        for info in metadata['items']:
+            if not info['url']:
+                try:
+                    result = self['xep_0084'].retrieve_avatar(msg['from'], info['id'])
+                except XMPPError:
+                    print("Error retrieving avatar for %s" % msg['from'])
+                    return
+
+                avatar = result['pubsub']['items']['item']['avatar_data']
+
+                filetype = FILE_TYPES.get(metadata['type'], 'png')
+                filename = 'avatar_%s_%s.%s' % (msg['from'].bare, info['id'], filetype)
+                with open(filename, 'w+') as img:
+                    img.write(avatar['value'])
+            else:
+                # We could retrieve the avatar via HTTP, etc here instead.
+                pass
+
+    def wait_for_presences(self, pres):
+        """
+        Wait to receive updates from all roster contacts.
+        """
+        self.received.add(pres['from'].bare)
+        if len(self.received) >= len(self.client_roster.keys()):
+            self.presences_received.set()
+        else:
+            self.presences_received.clear()
+
+
+if __name__ == '__main__':
+    # 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.ERROR)
+    optp.add_option('-d','--debug', help='set logging to DEBUG',
+                    action='store_const',
+                    dest='loglevel',
+                    const=logging.DEBUG,
+                    default=logging.ERROR)
+    optp.add_option('-v','--verbose', help='set logging to COMM',
+                    action='store_const',
+                    dest='loglevel',
+                    const=5,
+                    default=logging.ERROR)
+
+    # 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')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+
+    xmpp = AvatarDownloader(opts.jid, opts.password)
+    xmpp.register_plugin('xep_0054')
+    xmpp.register_plugin('xep_0153')
+    xmpp.register_plugin('xep_0084')
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+    else:
+        print("Unable to connect.")

examples/echo_client.py

@@ -11,7 +11,6 @@
 
 import sys
 import logging
-import time
 import getpass
 from optparse import OptionParser
 
@@ -22,8 +21,8 @@ import sleekxmpp
 # throughout SleekXMPP, we will set the default encoding
 # ourselves to UTF-8.
 if sys.version_info < (3, 0):
-    reload(sys)
-    sys.setdefaultencoding('utf8')
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
 else:
     raw_input = input
 
@@ -41,7 +40,7 @@ class EchoBot(sleekxmpp.ClientXMPP):
         # 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
+        # listen for this event so that we we can initialize
         # our roster.
         self.add_event_handler("session_start", self.start)
 
@@ -55,7 +54,7 @@ class EchoBot(sleekxmpp.ClientXMPP):
         Process the session_start event.
 
         Typical actions for the session_start event are
-        requesting the roster and broadcasting an intial
+        requesting the roster and broadcasting an initial
         presence stanza.
 
         Arguments:
@@ -123,6 +122,19 @@ if __name__ == '__main__':
     xmpp.register_plugin('xep_0060') # PubSub
     xmpp.register_plugin('xep_0199') # XMPP Ping
 
+    # If you are connecting to Facebook and wish to use the
+    # X-FACEBOOK-PLATFORM authentication mechanism, you will need
+    # your API key and an access token. Then you'll set:
+    # xmpp.credentials['api_key'] = 'THE_API_KEY'
+    # xmpp.credentials['access_token'] = 'THE_ACCESS_TOKEN'
+
+    # If you are connecting to MSN, then you will need an
+    # access token, and it does not matter what JID you
+    # specify other than that the domain is 'messenger.live.com',
+    # so '_@messenger.live.com' will work. You can specify
+    # the access token as so:
+    # xmpp.credentials['access_token'] = 'THE_ACCESS_TOKEN'
+
     # If you are working with an OpenFire server, you may need
     # to adjust the SSL version used:
     # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
@@ -132,14 +144,14 @@ if __name__ == '__main__':
 
     # 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
+        # If you do not have the dnspython 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)
+        xmpp.process(block=True)
         print("Done")
     else:
         print("Unable to connect.")

examples/echo_component.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+    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
+import getpass
+from optparse import OptionParser
+
+import sleekxmpp
+from sleekxmpp.componentxmpp import ComponentXMPP
+
+# 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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class EchoComponent(ComponentXMPP):
+
+    """
+    A simple SleekXMPP component that echoes messages.
+    """
+
+    def __init__(self, jid, secret, server, port):
+        ComponentXMPP.__init__(self, jid, secret, server, port)
+
+        # You don't need a session_start handler, but that is
+        # where you would broadcast initial presence.
+
+        # 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 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.
+
+        Since a component may send messages from any number of JIDs,
+        it is best to always include a from JID.
+
+        Arguments:
+            msg -- The received message stanza. See the documentation
+                   for stanza objects and the Message stanza to see
+                   how it may be used.
+        """
+        # The reply method will use the messages 'to' JID as the
+        # outgoing reply's 'from' JID.
+        msg.reply("Thanks for sending\n%(body)s" % msg).send()
+
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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")
+    optp.add_option("-s", "--server", dest="server",
+                    help="server to connect to")
+    optp.add_option("-P", "--port", dest="port",
+                    help="port to connect to")
+
+    opts, args = optp.parse_args()
+
+    if opts.jid is None:
+        opts.jid = raw_input("Component JID: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+    if opts.server is None:
+        opts.server = raw_input("Server: ")
+    if opts.port is None:
+        opts.port = int(raw_input("Port: "))
+
+    # Setup logging.
+    logging.basicConfig(level=opts.loglevel,
+                        format='%(levelname)-8s %(message)s')
+
+    # Setup the EchoComponent and register plugins. Note that while plugins
+    # may have interdependencies, the order in which you register them does
+    # not matter.
+    xmpp = EchoComponent(opts.jid, opts.password, opts.server, opts.port)
+    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():
+        xmpp.process(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

examples/gtalk_custom_domain.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+    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
+import getpass
+from optparse import OptionParser
+
+import sleekxmpp
+
+import ssl
+from sleekxmpp.xmlstream import cert
+
+
+# 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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class GTalkBot(sleekxmpp.ClientXMPP):
+
+    """
+    A demonstration of using SleekXMPP with accounts from a Google Apps
+    account with a custom domain, because it requires custom certificate
+    validation.
+    """
+
+    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 initialize
+        # 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)
+
+        # Using a Google Apps custom domain, the certificate
+        # does not contain the custom domain, just the GTalk
+        # server name. So we will need to process invalid
+        # certifcates ourselves and check that it really
+        # is from Google.
+        self.add_event_handler("ssl_invalid_cert", self.invalid_cert)
+
+    def invalid_cert(self, pem_cert):
+        der_cert = ssl.PEM_cert_to_DER_cert(pem_cert)
+        try:
+            cert.verify('talk.google.com', der_cert)
+            logging.debug("CERT: Found GTalk certificate")
+        except cert.CertificateError as err:
+            log.error(err.message)
+            self.disconnect(send_close=False)
+
+    def start(self, event):
+        """
+        Process the session_start event.
+
+        Typical actions for the session_start event are
+        requesting the roster and broadcasting an initial
+        presence stanza.
+
+        Arguments:
+            event -- An empty dictionary. The session_start
+                     event does not provide any additional
+                     data.
+        """
+        self.send_presence()
+        self.get_roster()
+
+    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.
+        """
+        if msg['type'] in ('chat', 'normal'):
+            msg.reply("Thanks for sending\n%(body)s" % msg).send()
+
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+
+    # Setup the GTalkBot and register plugins. Note that while plugins may
+    # have interdependencies, the order in which you register them does
+    # not matter.
+    xmpp = GTalkBot(opts.jid, opts.password)
+    xmpp.register_plugin('xep_0030') # Service Discovery
+    xmpp.register_plugin('xep_0004') # Data Forms
+    xmpp.register_plugin('xep_0060') # PubSub
+    xmpp.register_plugin('xep_0199') # XMPP Ping
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

examples/ibb_transfer/ibb_receiver.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+    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
+import getpass
+from optparse import OptionParser
+
+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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class IBBReceiver(sleekxmpp.ClientXMPP):
+
+    """
+    A basic example of creating and using an in-band bytestream.
+    """
+
+    def __init__(self, jid, password):
+        sleekxmpp.ClientXMPP.__init__(self, jid, password)
+
+        self.register_plugin('xep_0030') # Service Discovery
+        self.register_plugin('xep_0047', {
+            'accept_stream': self.accept_stream
+        }) # In-band Bytestreams
+
+        # 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 initialize
+        # our roster.
+        self.add_event_handler("session_start", self.start)
+
+        self.add_event_handler("ibb_stream_start", self.stream_opened)
+        self.add_event_handler("ibb_stream_data", self.stream_data)
+
+    def start(self, event):
+        """
+        Process the session_start event.
+
+        Typical actions for the session_start event are
+        requesting the roster and broadcasting an initial
+        presence stanza.
+
+        Arguments:
+            event -- An empty dictionary. The session_start
+                     event does not provide any additional
+                     data.
+        """
+        self.send_presence()
+        self.get_roster()
+
+    def accept_stream(self, iq):
+        """
+        Check that it is ok to accept a stream request. 
+
+        Controlling stream acceptance can be done via either:
+            - setting 'auto_accept' to False in the plugin
+              configuration. The default is True.
+            - setting 'accept_stream' to a function which accepts
+              an Iq stanza as its argument, like this one.
+
+        The accept_stream function will be used if it exists, and the
+        auto_accept value will be used otherwise.
+        """
+        return True
+
+    def stream_opened(self, stream):
+        # NOTE: IBB streams are bi-directional, so the original sender is
+        # now the opened stream's receiver.
+        print('Stream opened: %s from %s' % (stream.sid, stream.receiver))
+
+        # You could run a loop reading from the stream using stream.recv(),
+        # or use the ibb_stream_data event.
+
+    def stream_data(self, event):
+        print(event['data'])
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+
+    xmpp = IBBReceiver(opts.jid, opts.password)
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

examples/ibb_transfer/ibb_sender.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+    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
+import getpass
+from optparse import OptionParser
+
+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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class IBBSender(sleekxmpp.ClientXMPP):
+
+    """
+    A basic example of creating and using an in-band bytestream.
+    """
+
+    def __init__(self, jid, password, receiver, filename):
+        sleekxmpp.ClientXMPP.__init__(self, jid, password)
+
+        self.receiver = receiver
+        self.filename = filename
+
+        # 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 initialize
+        # our roster.
+        self.add_event_handler("session_start", self.start)
+
+    def start(self, event):
+        """
+        Process the session_start event.
+
+        Typical actions for the session_start event are
+        requesting the roster and broadcasting an initial
+        presence stanza.
+
+        Arguments:
+            event -- An empty dictionary. The session_start
+                     event does not provide any additional
+                     data.
+        """
+        self.send_presence()
+        self.get_roster()
+
+        # For the purpose of demonstration, we'll set a very small block
+        # size. The default block size is 4096. We'll also use a window
+        # allowing sending multiple blocks at a time; in this case, three
+        # block transfers may be in progress at any time.
+        stream = self['xep_0047'].open_stream(self.receiver)
+
+        with open(self.filename) as f:
+            data = f.read()
+            stream.sendall(data)
+
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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")
+    optp.add_option("-r", "--receiver", dest="receiver",
+                    help="JID to use")
+    optp.add_option("-f", "--file", dest="filename",
+                    help="JID to use")
+
+    opts, args = optp.parse_args()
+
+    # Setup logging.
+    logging.basicConfig(level=opts.loglevel,
+                        format='%(levelname)-8s %(message)s')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+    if opts.receiver is None:
+        opts.receiver = raw_input("Receiver: ")
+    if opts.filename is None:
+        opts.filename = raw_input("File path: ")
+
+    # Setup the EchoBot and register plugins. Note that while plugins may
+    # have interdependencies, the order in which you register them does
+    # not matter.
+    xmpp = IBBSender(opts.jid, opts.password, opts.receiver, opts.filename)
+    xmpp.register_plugin('xep_0030') # Service Discovery
+    xmpp.register_plugin('xep_0004') # Data Forms
+    xmpp.register_plugin('xep_0047') # In-band Bytestreams
+    xmpp.register_plugin('xep_0060') # PubSub
+    xmpp.register_plugin('xep_0199') # XMPP Ping
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

examples/muc.py

@@ -11,7 +11,7 @@
 
 import sys
 import logging
-import time
+import getpass
 from optparse import OptionParser
 
 import sleekxmpp
@@ -21,8 +21,8 @@ import sleekxmpp
 # throughout SleekXMPP, we will set the default encoding
 # ourselves to UTF-8.
 if sys.version_info < (3, 0):
-    reload(sys)
-    sys.setdefaultencoding('utf8')
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
 else:
     raw_input = input
 
@@ -44,7 +44,7 @@ class MUCBot(sleekxmpp.ClientXMPP):
         # 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
+        # listen for this event so that we we can initialize
         # our roster.
         self.add_event_handler("session_start", self.start)
 
@@ -68,7 +68,7 @@ class MUCBot(sleekxmpp.ClientXMPP):
         Process the session_start event.
 
         Typical actions for the session_start event are
-        requesting the roster and broadcasting an intial
+        requesting the roster and broadcasting an initial
         presence stanza.
 
         Arguments:
@@ -76,8 +76,8 @@ class MUCBot(sleekxmpp.ClientXMPP):
                      event does not provide any additional
                      data.
         """
-        self.getRoster()
-        self.sendPresence()
+        self.get_roster()
+        self.send_presence()
         self.plugin['xep_0045'].joinMUC(self.room,
                                         self.nick,
                                         # If a room password is needed, use:
@@ -161,9 +161,14 @@ if __name__ == '__main__':
     logging.basicConfig(level=opts.loglevel,
                         format='%(levelname)-8s %(message)s')
 
-    if None in [opts.jid, opts.password, opts.room, opts.nick]:
-        optp.print_help()
-        sys.exit(1)
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+    if opts.room is None:
+        opts.room = raw_input("MUC room: ")
+    if opts.nick is None:
+        opts.nick = raw_input("MUC nickname: ")
 
     # Setup the MUCBot and register plugins. Note that while plugins may
     # have interdependencies, the order in which you register them does
@@ -175,14 +180,14 @@ if __name__ == '__main__':
 
     # 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
+        # If you do not have the dnspython 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)
+        xmpp.process(block=True)
         print("Done")
     else:
         print("Unable to connect.")

examples/ping.py

@@ -11,7 +11,6 @@
 
 import sys
 import logging
-import time
 import getpass
 from optparse import OptionParser
 
@@ -22,8 +21,8 @@ import sleekxmpp
 # throughout SleekXMPP, we will set the default encoding
 # ourselves to UTF-8.
 if sys.version_info < (3, 0):
-    reload(sys)
-    sys.setdefaultencoding('utf8')
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
 else:
     raw_input = input
 
@@ -44,16 +43,16 @@ class PingTest(sleekxmpp.ClientXMPP):
         # 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
+        # listen for this event so that we we can initialize
         # our roster.
-        self.add_event_handler("session_start", self.start)
+        self.add_event_handler("session_start", self.start, threaded=True)
 
     def start(self, event):
         """
         Process the session_start event.
 
         Typical actions for the session_start event are
-        requesting the roster and broadcasting an intial
+        requesting the roster and broadcasting an initial
         presence stanza.
 
         Arguments:
@@ -72,7 +71,7 @@ class PingTest(sleekxmpp.ClientXMPP):
             self.disconnect()
             sys.exit(1)
         else:
-            logging.info("Success! RTT: %s" % str(result))
+            logging.info("Success! RTT: %s", str(result))
             self.disconnect()
 
 
@@ -129,14 +128,14 @@ if __name__ == '__main__':
 
     # 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
+        # If you do not have the dnspython 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)
+        xmpp.process(block=True)
         print("Done")
     else:
         print("Unable to connect.")

examples/proxy_echo_client.py

@@ -11,7 +11,6 @@
 
 import sys
 import logging
-import time
 import getpass
 from optparse import OptionParser
 
@@ -22,8 +21,8 @@ import sleekxmpp
 # throughout SleekXMPP, we will set the default encoding
 # ourselves to UTF-8.
 if sys.version_info < (3, 0):
-    reload(sys)
-    sys.setdefaultencoding('utf8')
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
 else:
     raw_input = input
 
@@ -41,7 +40,7 @@ class EchoBot(sleekxmpp.ClientXMPP):
         # 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
+        # listen for this event so that we we can initialize
         # our roster.
         self.add_event_handler("session_start", self.start)
 
@@ -55,7 +54,7 @@ class EchoBot(sleekxmpp.ClientXMPP):
         Process the session_start event.
 
         Typical actions for the session_start event are
-        requesting the roster and broadcasting an intial
+        requesting the roster and broadcasting an initial
         presence stanza.
 
         Arguments:
@@ -156,14 +155,14 @@ if __name__ == '__main__':
 
     # 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
+        # If you do not have the dnspython 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)
+        xmpp.process(block=True)
         print("Done")
     else:
         print("Unable to connect.")

examples/pubsub_client.py

@@ -0,0 +1,198 @@
+import sys
+import logging
+import getpass
+from optparse import OptionParser
+
+import sleekxmpp
+from sleekxmpp.xmlstream import ET, tostring
+
+
+# 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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class PubsubClient(sleekxmpp.ClientXMPP):
+
+    def __init__(self, jid, password, server, 
+                       node=None, action='list', data=''):
+        super(PubsubClient, self).__init__(jid, password)
+
+        self.register_plugin('xep_0030')
+        self.register_plugin('xep_0059')
+        self.register_plugin('xep_0060')
+
+        self.actions = ['nodes', 'create', 'delete', 
+                        'publish', 'get', 'retract',
+                        'purge', 'subscribe', 'unsubscribe']
+
+        self.action = action
+        self.node = node
+        self.data = data
+        self.pubsub_server = server
+
+        self.add_event_handler('session_start', self.start, threaded=True)
+
+    def start(self, event):
+        self.get_roster()
+        self.send_presence()
+
+        try:
+            getattr(self, self.action)()
+        except:
+            logging.error('Could not execute: %s' % self.action)
+        self.disconnect()
+
+    def nodes(self):
+        try:
+            result = self['xep_0060'].get_nodes(self.pubsub_server, self.node)
+            for item in result['disco_items']['items']:
+                print('  - %s' % str(item))
+        except:
+            logging.error('Could not retrieve node list.')
+
+    def create(self):
+        try:
+            self['xep_0060'].create_node(self.pubsub_server, self.node)
+        except:
+            logging.error('Could not create node: %s' % self.node)
+
+    def delete(self):
+        try:
+            self['xep_0060'].delete_node(self.pubsub_server, self.node)
+            print('Deleted node: %s' % self.node)
+        except:
+            logging.error('Could not delete node: %s' % self.node)
+
+    def publish(self):
+        payload = ET.fromstring("<test xmlns='test'>%s</test>" % self.data)
+        try:
+            result = self['xep_0060'].publish(self.pubsub_server, self.node, payload=payload)
+            id = result['pubsub']['publish']['item']['id']
+            print('Published at item id: %s' % id)
+        except:
+            logging.error('Could not publish to: %s' % self.node)
+
+    def get(self):
+        try:
+            result = self['xep_0060'].get_item(self.pubsub_server, self.node, self.data)
+            for item in result['pubsub']['items']['substanzas']:
+                print('Retrieved item %s: %s' % (item['id'], tostring(item['payload'])))
+        except:
+            logging.error('Could not retrieve item %s from node %s' % (self.data, self.node))
+
+    def retract(self):
+        try:
+            result = self['xep_0060'].retract(self.pubsub_server, self.node, self.data)
+            print('Retracted item %s from node %s' % (self.data, self.node))
+        except:
+            logging.error('Could not retract item %s from node %s' % (self.data, self.node))
+
+    def purge(self):
+        try:
+            result = self['xep_0060'].purge(self.pubsub_server, self.node)
+            print('Purged all items from node %s' % self.node)
+        except:
+            logging.error('Could not purge items from node %s' % self.node)
+
+    def subscribe(self):
+        try:
+            result = self['xep_0060'].subscribe(self.pubsub_server, self.node)
+            print('Subscribed %s to node %s' % (self.boundjid.bare, self.node))
+        except:
+            logging.error('Could not subscribe %s to node %s' % (self.boundjid.bare, self.node))
+
+    def unsubscribe(self):
+        try:
+            result = self['xep_0060'].unsubscribe(self.pubsub_server, self.node)
+            print('Unsubscribed %s from node %s' % (self.boundjid.bare, self.node))
+        except:
+            logging.error('Could not unsubscribe %s from node %s' % (self.boundjid.bare, self.node))
+
+
+
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+    optp.version = '%%prog 0.1'
+    optp.usage = "Usage: %%prog [options] <jid> " + \
+                             'nodes|create|delete|purge|subscribe|unsubscribe|publish|retract|get' + \
+                             ' [<node> <data>]'
+
+    optp.add_option('-q','--quiet', help='set logging to ERROR',
+                    action='store_const',
+                    dest='loglevel',
+                    const=logging.ERROR,
+                    default=logging.ERROR)
+    optp.add_option('-d','--debug', help='set logging to DEBUG',
+                    action='store_const',
+                    dest='loglevel',
+                    const=logging.DEBUG,
+                    default=logging.ERROR)
+    optp.add_option('-v','--verbose', help='set logging to COMM',
+                    action='store_const',
+                    dest='loglevel',
+                    const=5,
+                    default=logging.ERROR)
+
+    # 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')
+
+    if len(args) < 2:
+        optp.print_help()
+        exit()
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+
+    if len(args) == 2:
+        args = (args[0], args[1], '', '', '')
+    elif len(args) == 3:
+        args = (args[0], args[1], args[2], '', '')
+    elif len(args) == 4:
+        args = (args[0], args[1], args[2], args[3], '')
+
+
+    # Setup the Pubsub client
+    xmpp = PubsubClient(opts.jid, opts.password,
+                        server=args[0],
+                        node=args[2],
+                        action=args[1],
+                        data=args[3])
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+    else:
+        print("Unable to connect.")

examples/pubsub_events.py

@@ -0,0 +1,151 @@
+import sys
+import logging
+import getpass
+from optparse import OptionParser
+
+import sleekxmpp
+from sleekxmpp.xmlstream import ET, tostring
+from sleekxmpp.xmlstream.matcher import StanzaPath
+from sleekxmpp.xmlstream.handler import Callback
+
+
+# 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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class PubsubEvents(sleekxmpp.ClientXMPP):
+
+    def __init__(self, jid, password):
+        super(PubsubEvents, self).__init__(jid, password)
+
+        self.register_plugin('xep_0030')
+        self.register_plugin('xep_0059')
+        self.register_plugin('xep_0060')
+
+        self.add_event_handler('session_start', self.start)
+
+        # Some services may require configuration to allow
+        # sending delete, configuration, or subscription  events.
+        self.add_event_handler('pubsub_publish', self._publish)
+        self.add_event_handler('pubsub_retract', self._retract)
+        self.add_event_handler('pubsub_purge', self._purge)
+        self.add_event_handler('pubsub_delete', self._delete)
+        self.add_event_handler('pubsub_config', self._config)
+        self.add_event_handler('pubsub_subscription', self._subscription)
+
+        # Want to use nicer, more specific pubsub event names?
+        # self['xep_0060'].map_node_event('node_name', 'event_prefix')
+        # self.add_event_handler('event_prefix_publish', handler)
+        # self.add_event_handler('event_prefix_retract', handler)
+        # self.add_event_handler('event_prefix_purge', handler)
+        # self.add_event_handler('event_prefix_delete', handler)
+
+    def start(self, event):
+        self.get_roster()
+        self.send_presence()
+
+    def _publish(self, msg):
+        """Handle receiving a publish item event."""
+        print('Published item %s to %s:' % (
+            msg['pubsub_event']['items']['item']['id'],
+            msg['pubsub_event']['items']['node']))
+        data = msg['pubsub_event']['items']['item']['payload']
+        if data is not None:
+            print(tostring(data))
+        else:
+            print('No item content')
+
+    def _retract(self, msg):
+        """Handle receiving a retract item event."""
+        print('Retracted item %s from %s' % (
+            msg['pubsub_event']['items']['retract']['id'],
+            msg['pubsub_event']['items']['node']))
+
+    def _purge(self, msg):
+        """Handle receiving a node purge event."""
+        print('Purged all items from %s' % (
+            msg['pubsub_event']['purge']['node']))
+
+    def _delete(self, msg):
+        """Handle receiving a node deletion event."""
+        print('Deleted node %s' % (
+           msg['pubsub_event']['delete']['node']))
+ 
+    def _config(self, msg):
+        """Handle receiving a node configuration event."""
+        print('Configured node %s:' % (
+            msg['pubsub_event']['configuration']['node']))
+        print(msg['pubsub_event']['configuration']['form'])
+
+    def _subscription(self, msg):
+        """Handle receiving a node subscription event."""
+        print('Subscription change for node %s:' % (
+            msg['pubsub_event']['subscription']['node']))
+        print(msg['pubsub_event']['subscription'])
+
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+
+    logging.info("Run this in conjunction with the pubsub_client.py " + \
+                 "example to watch events happen as you give commands.")
+
+    # Setup the PubsubEvents listener
+    xmpp = PubsubEvents(opts.jid, opts.password)
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

examples/register_account.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+    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
+import getpass
+from optparse import OptionParser
+
+import sleekxmpp
+from sleekxmpp.exceptions import IqError, IqTimeout
+
+# 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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class RegisterBot(sleekxmpp.ClientXMPP):
+
+    """
+    A basic bot that will attempt to register an account
+    with an XMPP server.
+
+    NOTE: This follows the very basic registration workflow
+          from XEP-0077. More advanced server registration
+          workflows will need to check for data forms, etc.
+    """
+
+    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 initialize
+        # our roster.
+        self.add_event_handler("session_start", self.start, threaded=True)
+
+        # The register event provides an Iq result stanza with
+        # a registration form from the server. This may include
+        # the basic registration fields, a data form, an 
+        # out-of-band URL, or any combination. For more advanced
+        # cases, you will need to examine the fields provided
+        # and respond accordingly. SleekXMPP provides plugins
+        # for data forms and OOB links that will make that easier.
+        self.add_event_handler("register", self.register, threaded=True)
+
+    def start(self, event):
+        """
+        Process the session_start event.
+
+        Typical actions for the session_start event are
+        requesting the roster and broadcasting an initial
+        presence stanza.
+
+        Arguments:
+            event -- An empty dictionary. The session_start
+                     event does not provide any additional
+                     data.
+        """
+        self.send_presence()
+        self.get_roster()
+
+        # We're only concerned about registering, so nothing more to do here.
+        self.disconnect()
+
+    def register(self, iq):
+        """
+        Fill out and submit a registration form.
+
+        The form may be composed of basic registration fields, a data form,
+        an out-of-band link, or any combination thereof. Data forms and OOB
+        links can be checked for as so:
+
+        if iq.match('iq/register/form'):
+            # do stuff with data form
+            # iq['register']['form']['fields']
+        if iq.match('iq/register/oob'):
+            # do stuff with OOB URL
+            # iq['register']['oob']['url']
+
+        To get the list of basic registration fields, you can use:
+            iq['register']['fields']
+        """
+        resp = self.Iq()
+        resp['type'] = 'set'
+        resp['register']['username'] = self.boundjid.user
+        resp['register']['password'] = self.password
+
+        try:
+            resp.send(now=True)
+            logging.info("Account created for %s!" % self.boundjid)
+        except IqError as e:
+            logging.error("Could not register account: %s" % 
+                    e.iq['error']['text'])
+            self.disconnect()
+        except IqTimeout:
+            logging.error("No response from server.")
+            self.disconnect()
+
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+
+    # Setup the RegisterBot and register plugins. Note that while plugins may
+    # have interdependencies, the order in which you register them does
+    # not matter.
+    xmpp = RegisterBot(opts.jid, opts.password)
+    xmpp.register_plugin('xep_0030') # Service Discovery
+    xmpp.register_plugin('xep_0004') # Data forms
+    xmpp.register_plugin('xep_0066') # Out-of-band Data
+    xmpp.register_plugin('xep_0077') # In-band Registration
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

examples/roster_browser.py

@@ -10,7 +10,6 @@
 """
 
 import sys
-import time
 import logging
 import getpass
 import threading
@@ -25,8 +24,8 @@ from sleekxmpp.exceptions import IqError, IqTimeout
 # throughout SleekXMPP, we will set the default encoding
 # ourselves to UTF-8.
 if sys.version_info < (3, 0):
-    reload(sys)
-    sys.setdefaultencoding('utf8')
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
 else:
     raw_input = input
 
@@ -43,7 +42,7 @@ class RosterBrowser(sleekxmpp.ClientXMPP):
         # 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
+        # listen for this event so that we we can initialize
         # our roster. We need threaded=True so that the
         # session_start handler doesn't block event processing
         # while we wait for presence stanzas to arrive.
@@ -58,7 +57,7 @@ class RosterBrowser(sleekxmpp.ClientXMPP):
         Process the session_start event.
 
         Typical actions for the session_start event are
-        requesting the roster and broadcasting an intial
+        requesting the roster and broadcasting an initial
         presence stanza.
 
         Arguments:
@@ -160,14 +159,14 @@ if __name__ == '__main__':
 
     # 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
+        # If you do not have the dnspython 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)
+        xmpp.process(block=True)
     else:
         print("Unable to connect.")
 

examples/rpc_client_side.py

@@ -16,7 +16,7 @@ class Thermostat(Endpoint):
     def FQN(self):
         return 'thermostat'
     
-    def __init(self, initial_temperature):
+    def __init__(self, initial_temperature):
         self._temperature = initial_temperature
         self._event = threading.Event()        
     
@@ -50,4 +50,4 @@ def main():
     
 if __name__ == '__main__':
     main()
-    
+    

examples/rpc_server_side.py

@@ -15,7 +15,7 @@ class Thermostat(Endpoint):
     def FQN(self):
         return 'thermostat'
     
-    def __init(self, initial_temperature):
+    def __init__(self, initial_temperature):
         self._temperature = initial_temperature
         self._event = threading.Event()        
     
@@ -49,4 +49,4 @@ def main():
     
 if __name__ == '__main__':
     main()
-    
+    

examples/send_client.py

@@ -11,7 +11,6 @@
 
 import sys
 import logging
-import time
 import getpass
 from optparse import OptionParser
 
@@ -22,8 +21,8 @@ import sleekxmpp
 # throughout SleekXMPP, we will set the default encoding
 # ourselves to UTF-8.
 if sys.version_info < (3, 0):
-    reload(sys)
-    sys.setdefaultencoding('utf8')
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
 else:
     raw_input = input
 
@@ -46,16 +45,16 @@ class SendMsgBot(sleekxmpp.ClientXMPP):
         # 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
+        # listen for this event so that we we can initialize
         # our roster.
-        self.add_event_handler("session_start", self.start)
+        self.add_event_handler("session_start", self.start, threaded=True)
 
     def start(self, event):
         """
         Process the session_start event.
 
         Typical actions for the session_start event are
-        requesting the roster and broadcasting an intial
+        requesting the roster and broadcasting an initial
         presence stanza.
 
         Arguments:
@@ -131,14 +130,14 @@ if __name__ == '__main__':
 
     # 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
+        # If you do not have the dnspython 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)
+        xmpp.process(block=True)
         print("Done")
     else:
         print("Unable to connect.")

examples/set_avatar.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2012  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+import os
+import sys
+import imghdr
+import logging
+import getpass
+import threading
+from optparse import OptionParser
+
+import sleekxmpp
+from sleekxmpp.exceptions import XMPPError
+
+
+# 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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class AvatarSetter(sleekxmpp.ClientXMPP):
+
+    """
+    A basic script for downloading the avatars for a user's contacts.
+    """
+
+    def __init__(self, jid, password, filepath):
+        sleekxmpp.ClientXMPP.__init__(self, jid, password)
+
+        self.add_event_handler("session_start", self.start, threaded=True)
+
+        self.filepath = filepath
+
+    def start(self, event):
+        """
+        Process the session_start event.
+
+        Typical actions for the session_start event are
+        requesting the roster and broadcasting an initial
+        presence stanza.
+
+        Arguments:
+            event -- An empty dictionary. The session_start
+                     event does not provide any additional
+                     data.
+        """
+        self.send_presence()
+        self.get_roster()
+
+        avatar_file = None
+        try:
+            avatar_file = open(os.path.expanduser(self.filepath))
+        except IOError:
+            print('Could not find file: %s' % self.filepath)
+            return self.disconnect()
+
+        avatar = avatar_file.read()
+
+        avatar_type = 'image/%s' % imghdr.what('', avatar)
+        avatar_id = self['xep_0084'].generate_id(avatar)
+        avatar_bytes = len(avatar)
+
+        avatar_file.close()
+
+        used_xep84 = False
+        try:
+            print('Publish XEP-0084 avatar data')
+            self['xep_0084'].publish_avatar(avatar)
+            used_xep84 = True
+        except XMPPError:
+            print('Could not publish XEP-0084 avatar')
+
+        try:
+            print('Update vCard with avatar')
+            self['xep_0153'].set_avatar(avatar=avatar, mtype=avatar_type)
+        except XMPPError:
+            print('Could not set vCard avatar')
+
+        if used_xep84:
+            try:
+                print('Advertise XEP-0084 avatar metadata')
+                self['xep_0084'].publish_avatar_metadata([
+                    {'id': avatar_id,
+                     'type': avatar_type,
+                     'bytes': avatar_bytes}
+                    # We could advertise multiple avatars to provide
+                    # options in image type, source (HTTP vs pubsub),
+                    # size, etc.
+                    # {'id': ....}
+                ])
+            except XMPPError:
+                print('Could not publish XEP-0084 metadata')
+
+        print('Wait for presence updates to propagate...')
+        self.schedule('end', 5, self.disconnect, kwargs={'wait': True})
+
+
+if __name__ == '__main__':
+    # 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.ERROR)
+    optp.add_option('-d','--debug', help='set logging to DEBUG',
+                    action='store_const',
+                    dest='loglevel',
+                    const=logging.DEBUG,
+                    default=logging.ERROR)
+    optp.add_option('-v','--verbose', help='set logging to COMM',
+                    action='store_const',
+                    dest='loglevel',
+                    const=5,
+                    default=logging.ERROR)
+
+    # 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")
+    optp.add_option("-f", "--file", dest="filepath",
+                    help="path to the avatar file")
+    opts,args = optp.parse_args()
+
+    # Setup logging.
+    logging.basicConfig(level=opts.loglevel,
+                        format='%(levelname)-8s %(message)s')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+    if opts.filepath is None:
+        opts.filepath = raw_input("Avatar file location: ")
+
+    xmpp = AvatarSetter(opts.jid, opts.password, opts.filepath)
+    xmpp.register_plugin('xep_0054')
+    xmpp.register_plugin('xep_0153')
+    xmpp.register_plugin('xep_0084')
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+    else:
+        print("Unable to connect.")

examples/thirdparty_auth.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+    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
+import getpass
+from optparse import OptionParser
+
+try:
+    from httplib import HTTPSConnection
+    from urllib import urlencode
+except ImportError:
+    from urllib.parse import urlencode
+    from http.client import HTTPSConnection
+
+import sleekxmpp
+from sleekxmpp.xmlstream import JID
+
+# 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):
+    from sleekxmpp.util.misc_ops import setdefaultencoding
+    setdefaultencoding('utf8')
+else:
+    raw_input = input
+
+
+class ThirdPartyAuthBot(sleekxmpp.ClientXMPP):
+
+    """
+    A simple SleekXMPP bot that will echo messages it
+    receives, along with a short thank you message.
+
+    This version uses a thirdpary service for authentication,
+    such as Facebook or Google.
+    """
+
+    def __init__(self, jid, password):
+        sleekxmpp.ClientXMPP.__init__(self, jid, password)
+
+        # The X-GOOGLE-TOKEN mech is ranked lower than PLAIN
+        # due to Google only allowing a single SASL attempt per
+        # connection. So PLAIN will be used for TLS connections,
+        # and X-GOOGLE-TOKEN for non-TLS connections. To use
+        # X-GOOGLE-TOKEN with a TLS connection, explicitly select
+        # it using:
+        #
+        # sleekxmpp.ClientXMPP.__init__(self, jid, password,
+        #                               sasl_mech="X-GOOGLE-TOKEN")
+
+        # 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 initialize
+        # 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 initial
+        presence stanza.
+
+        Arguments:
+            event -- An empty dictionary. The session_start
+                     event does not provide any additional
+                     data.
+        """
+        self.send_presence()
+        self.get_roster()
+
+    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.
+        """
+        if msg['type'] in ('chat', 'normal'):
+            msg.reply("Thanks for sending\n%(body)s" % msg).send()
+
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+
+    
+    access_token = None
+
+    # Since documentation on how to work with Google tokens
+    # can be difficult to find, we'll demo a basic version
+    # here. Note that responses could refer to a Captcha
+    # URL that would require a browser.
+
+    # Using Facebook or MSN's custom authentication requires
+    # a browser, but the process is the same once a token
+    # has been retrieved.
+
+    # Request an access token from Google:
+    try:
+        conn = HTTPSConnection('www.google.com')
+    except:
+        print('Could not connect to Google')
+        sys.exit()
+
+    params = urlencode({
+        'accountType': 'GOOGLE',
+        'service': 'mail',
+        'Email': JID(opts.jid).bare,
+        'Passwd': opts.password
+    })
+    headers = {
+        'Content-Type': 'application/x-www-form-urlencoded' 
+    }
+    try:
+        conn.request('POST', '/accounts/ClientLogin', params, headers)
+        resp = conn.getresponse().read()
+        data = {}
+        for line in resp.split():
+            k, v = line.split(b'=', 1)
+            data[k] = v
+    except Exception as e:
+        print('Could not retrieve login data')
+        sys.exit()
+
+    if b'SID' not in data:
+        print('Required data not found')
+        sys.exit()
+
+
+    params = urlencode({
+        'SID': data[b'SID'],
+        'LSID': data[b'LSID'],
+        'service': 'mail'
+    })
+    try:
+        conn.request('POST', '/accounts/IssueAuthToken', params, headers)
+        resp = conn.getresponse()
+        data = resp.read().split()
+    except:
+        print('Could not retrieve auth data')
+        sys.exit()
+
+    if not data:
+        print('Could not retrieve token')
+        sys.exit()
+
+    access_token = data[0]
+
+
+    # Setup the ThirdPartyAuthBot and register plugins. Note that while plugins
+    # may have interdependencies, the order in which you register them does not
+    # matter.
+
+    # If using MSN, the JID should be "user@messenger.live.com", which will
+    # be overridden on session bind.
+
+    # We're using an access token instead of a password, so we'll use `''` as
+    # a password argument filler.
+
+    xmpp = ThirdPartyAuthBot(opts.jid, '')  
+    xmpp.credentials['access_token'] = access_token
+
+    # The credentials dictionary is used to provide additional authentication
+    # information beyond just a password.
+    
+    xmpp.register_plugin('xep_0030') # Service Discovery
+    xmpp.register_plugin('xep_0004') # Data Forms
+    xmpp.register_plugin('xep_0060') # PubSub
+
+    # MSN will kill connections that have been inactive for even
+    # short periods of time. So use pings to keep the session alive;
+    # whitespace keepalives do not work.
+    xmpp.register_plugin('xep_0199', {'keepalive': True, 'frequency': 60})
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    # Google only allows one SASL attempt per connection, so in order to 
+    # enable the X-GOOGLE-TOKEN mechanism, we'll disable TLS.
+    if xmpp.connect(use_tls=False):
+        # If you do not have the dnspython 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(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

examples/user_location.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python
+
+import sys
+import logging
+import getpass
+from optparse import OptionParser
+
+try:
+    import json
+except ImportError:
+    import simplejson as json
+
+try:
+    import requests
+except ImportError:
+    print('This demo requires the requests package for using HTTP.')
+    sys.exit()
+
+from sleekxmpp import ClientXMPP
+
+
+class LocationBot(ClientXMPP):
+
+    def __init__(self, jid, password):
+        super(LocationBot, self).__init__(jid, password)
+
+        self.add_event_handler('session_start', self.start, threaded=True)
+        self.add_event_handler('user_location_publish', 
+                               self.user_location_publish)
+
+        self.register_plugin('xep_0004')
+        self.register_plugin('xep_0030')
+        self.register_plugin('xep_0060')
+        self.register_plugin('xep_0115')
+        self.register_plugin('xep_0128')
+        self.register_plugin('xep_0163')
+        self.register_plugin('xep_0080')
+
+        self.current_tune = None
+
+    def start(self, event):
+        self.send_presence()
+        self.get_roster()
+        self['xep_0115'].update_caps()
+
+        print("Using freegeoip.net to get geolocation.")
+        r = requests.get('http://freegeoip.net/json/')
+        try:
+            data = json.loads(r.text)
+        except:
+            print("Could not retrieve user location.")
+            self.disconnect()
+            return
+
+        self['xep_0080'].publish_location(
+                lat=data['latitude'],
+                lon=data['longitude'],
+                locality=data['city'],
+                region=data['region_name'],
+                country=data['country_name'],
+                countrycode=data['country_code'],
+                postalcode=data['zipcode'])
+
+    def user_location_publish(self, msg):
+        geo = msg['pubsub_event']['items']['item']['geoloc']
+        print("%s is at:" % msg['from'])
+        for key, val in geo.values.items():
+            if val:
+                print("  %s: %s" % (key, val))
+
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+
+    xmpp = LocationBot(opts.jid, opts.password)
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

examples/user_tune.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python
+
+import sys
+import logging
+import getpass
+from optparse import OptionParser
+
+try:
+    from appscript import *
+except ImportError:
+    print('This demo requires the appscript package to interact with iTunes.')
+    sys.exit()
+
+from sleekxmpp import ClientXMPP
+
+
+class TuneBot(ClientXMPP):
+
+    def __init__(self, jid, password):
+        super(TuneBot, self).__init__(jid, password)
+
+        # Check for the current song every 5 seconds.
+        self.schedule('Check Current Tune', 5, self._update_tune, repeat=True)
+
+        self.add_event_handler('session_start', self.start)
+        self.add_event_handler('user_tune_publish', self.user_tune_publish)
+
+        self.register_plugin('xep_0004')
+        self.register_plugin('xep_0030')
+        self.register_plugin('xep_0060')
+        self.register_plugin('xep_0115')
+        self.register_plugin('xep_0118')
+        self.register_plugin('xep_0128')
+        self.register_plugin('xep_0163')
+
+        self.current_tune = None
+
+    def start(self, event):
+        self.send_presence()
+        self.get_roster()
+        self['xep_0115'].update_caps()
+
+    def _update_tune(self):
+        itunes_count = app('System Events').processes[its.name == 'iTunes'].count()
+        if itunes_count > 0:
+            iTunes = app('iTunes')
+            if iTunes.player_state.get() == k.playing:
+                track = iTunes.current_track.get()
+                length = track.time.get()
+                if ':' in length:
+                    minutes, secs = map(int, length.split(':'))
+                    secs += minutes * 60
+                else:
+                    secs = int(length)
+
+                artist = track.artist.get()
+                title = track.name.get()
+                source = track.album.get()
+                rating = track.rating.get() / 10
+
+                tune = (artist, secs, rating, source, title)
+                if tune != self.current_tune:
+                    self.current_tune = tune
+
+                    # We have a new song playing, so publish it.
+                    self['xep_0118'].publish_tune(
+                            artist=artist,
+                            length=secs,
+                            title=title,
+                            rating=rating,
+                            source=source)
+            else:
+                # No song is playing, clear the user tune.
+                tune = None
+                if tune != self.current_tune:
+                    self.current_tune = tune
+                    self['xep_0118'].stop()
+
+    def user_tune_publish(self, msg):
+        tune = msg['pubsub_event']['items']['item']['tune']
+        print("%s is listening to: %s" % (msg['from'], tune['title']))
+
+
+if __name__ == '__main__':
+    # Setup the command line arguments.
+    optp = OptionParser()
+
+    # 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')
+
+    if opts.jid is None:
+        opts.jid = raw_input("Username: ")
+    if opts.password is None:
+        opts.password = getpass.getpass("Password: ")
+
+    xmpp = TuneBot(opts.jid, opts.password)
+
+    # If you are working with an OpenFire server, you may need
+    # to adjust the SSL version used:
+    # xmpp.ssl_version = ssl.PROTOCOL_SSLv3
+
+    # If you want to verify the SSL certificates offered by a server:
+    # xmpp.ca_certs = "path/to/ca/cert"
+
+    # Connect to the XMPP server and start processing XMPP stanzas.
+    if xmpp.connect():
+        # If you do not have the dnspython 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(block=True)
+        print("Done")
+    else:
+        print("Unable to connect.")

setup.py

@@ -8,7 +8,11 @@
 # file, which you should have received as part of this distribution.
 
 import sys
-from distutils.core import setup, Command
+import codecs
+try:
+    from setuptools import setup, Command
+except ImportError:
+    from distutils.core import setup, Command
 # from ez_setup import use_setuptools
 
 from testall import TestCommand
@@ -28,16 +32,16 @@ from sleekxmpp.version import __version__
 
 VERSION          = __version__
 DESCRIPTION      = 'SleekXMPP is an elegant Python library for XMPP (aka Jabber, Google Talk, etc).'
-with open('README.rst') as readme:
+with codecs.open('README.rst', 'r', encoding='UTF-8') as readme:
     LONG_DESCRIPTION = ''.join(readme)
 
 CLASSIFIERS      = [ 'Intended Audience :: Developers',
                      'License :: OSI Approved :: MIT License',
                      'Programming Language :: Python',
-                     'Programming Language :: Python 2.6',
-                     'Programming Language :: Python 2.7',
-                     'Programming Language :: Python 3.1',
-                     'Programming Language :: Python 3.2',
+                     'Programming Language :: Python :: 2.6',
+                     'Programming Language :: Python :: 2.7',
+                     'Programming Language :: Python :: 3.1',
+                     'Programming Language :: Python :: 3.2',
                      'Topic :: Software Development :: Libraries :: Python Modules',
                    ]
 
@@ -45,6 +49,8 @@ packages     = [ 'sleekxmpp',
                  'sleekxmpp/stanza',
                  'sleekxmpp/test',
                  'sleekxmpp/roster',
+                 'sleekxmpp/util',
+                 'sleekxmpp/util/sasl',
                  'sleekxmpp/xmlstream',
                  'sleekxmpp/xmlstream/matcher',
                  'sleekxmpp/xmlstream/handler',
@@ -53,32 +59,66 @@ packages     = [ 'sleekxmpp',
                  'sleekxmpp/plugins/xep_0004/stanza',
                  'sleekxmpp/plugins/xep_0009',
                  'sleekxmpp/plugins/xep_0009/stanza',
+                 'sleekxmpp/plugins/xep_0012',
+                 'sleekxmpp/plugins/xep_0013',
+                 'sleekxmpp/plugins/xep_0016',
+                 'sleekxmpp/plugins/xep_0027',
                  'sleekxmpp/plugins/xep_0030',
                  'sleekxmpp/plugins/xep_0030/stanza',
+                 'sleekxmpp/plugins/xep_0033',
+                 'sleekxmpp/plugins/xep_0047',
+                 'sleekxmpp/plugins/xep_0049',
                  'sleekxmpp/plugins/xep_0050',
+                 'sleekxmpp/plugins/xep_0054',
                  'sleekxmpp/plugins/xep_0059',
                  'sleekxmpp/plugins/xep_0060',
                  'sleekxmpp/plugins/xep_0060/stanza',
+                 'sleekxmpp/plugins/xep_0065',
                  'sleekxmpp/plugins/xep_0066',
+                 'sleekxmpp/plugins/xep_0077',
                  'sleekxmpp/plugins/xep_0078',
+                 'sleekxmpp/plugins/xep_0080',
+                 'sleekxmpp/plugins/xep_0084',
                  'sleekxmpp/plugins/xep_0085',
                  'sleekxmpp/plugins/xep_0086',
+                 'sleekxmpp/plugins/xep_0091',
                  'sleekxmpp/plugins/xep_0092',
+                 'sleekxmpp/plugins/xep_0107',
+                 'sleekxmpp/plugins/xep_0108',
+                 'sleekxmpp/plugins/xep_0115',
+                 'sleekxmpp/plugins/xep_0118',
                  'sleekxmpp/plugins/xep_0128',
+                 'sleekxmpp/plugins/xep_0131',
+                 'sleekxmpp/plugins/xep_0153',
+                 'sleekxmpp/plugins/xep_0172',
+                 'sleekxmpp/plugins/xep_0184',
+                 'sleekxmpp/plugins/xep_0186',
+                 'sleekxmpp/plugins/xep_0191',
+                 'sleekxmpp/plugins/xep_0198',
                  'sleekxmpp/plugins/xep_0199',
                  'sleekxmpp/plugins/xep_0202',
                  'sleekxmpp/plugins/xep_0203',
+                 'sleekxmpp/plugins/xep_0221',
                  'sleekxmpp/plugins/xep_0224',
+                 'sleekxmpp/plugins/xep_0231',
+                 'sleekxmpp/plugins/xep_0235',
                  'sleekxmpp/plugins/xep_0249',
+                 'sleekxmpp/plugins/xep_0257',
+                 'sleekxmpp/plugins/xep_0258',
+                 'sleekxmpp/plugins/xep_0279',
+                 'sleekxmpp/plugins/xep_0280',
+                 'sleekxmpp/plugins/xep_0297',
+                 'sleekxmpp/plugins/xep_0308',
+                 'sleekxmpp/plugins/xep_0313',
                  'sleekxmpp/features',
                  'sleekxmpp/features/feature_mechanisms',
                  'sleekxmpp/features/feature_mechanisms/stanza',
                  'sleekxmpp/features/feature_starttls',
                  'sleekxmpp/features/feature_bind',
                  'sleekxmpp/features/feature_session',
+                 'sleekxmpp/features/feature_rosterver',
+                 'sleekxmpp/features/feature_preapproval',
                  'sleekxmpp/thirdparty',
-                 'sleekxmpp/thirdparty/suelta',
-                 'sleekxmpp/thirdparty/suelta/mechanisms',
                  ]
 
 setup(
@@ -92,7 +132,7 @@ setup(
     license      = 'MIT',
     platforms    = [ 'any' ],
     packages     = packages,
-    requires     = [ 'dnspython' ],
+    requires     = [ 'dnspython', 'pyasn1', 'pyasn1_modules' ],
     classifiers  = CLASSIFIERS,
     cmdclass     = {'test': TestCommand}
 )

sleekxmpp/__init__.py

@@ -10,6 +10,7 @@ from sleekxmpp.basexmpp import BaseXMPP
 from sleekxmpp.clientxmpp import ClientXMPP
 from sleekxmpp.componentxmpp import ComponentXMPP
 from sleekxmpp.stanza import Message, Presence, Iq
+from sleekxmpp.jid import JID, InvalidJID
 from sleekxmpp.xmlstream.handler import *
 from sleekxmpp.xmlstream import XMLStream, RestartStream
 from sleekxmpp.xmlstream.matcher import *

sleekxmpp/api.py

@@ -0,0 +1,200 @@
+from sleekxmpp.xmlstream import JID
+
+
+class APIWrapper(object):
+
+    def __init__(self, api, name):
+        self.api = api
+        self.name = name
+        if name not in self.api.settings:
+            self.api.settings[name] = {}
+
+    def __getattr__(self, attr):
+        """Curry API management commands with the API name."""
+        if attr == 'name':
+            return self.name
+        elif attr == 'settings':
+            return self.api.settings[self.name]
+        elif attr == 'register':
+            def partial(handler, op, jid=None, node=None, default=False):
+                register = getattr(self.api, attr)
+                return register(handler, self.name, op, jid, node, default)
+            return partial
+        elif attr == 'register_default':
+            def partial(handler, op, jid=None, node=None):
+                return getattr(self.api, attr)(handler, self.name, op)
+            return partial
+        elif attr in ('run', 'restore_default', 'unregister'):
+            def partial(*args, **kwargs):
+                return getattr(self.api, attr)(self.name, *args, **kwargs)
+            return partial
+        return None
+
+    def __getitem__(self, attr):
+        def partial(jid=None, node=None, ifrom=None, args=None):
+            return self.api.run(self.name, attr, jid, node, ifrom, args)
+        return partial
+
+
+class APIRegistry(object):
+
+    def __init__(self, xmpp):
+        self._handlers = {}
+        self._handler_defaults = {}
+        self.xmpp = xmpp
+        self.settings = {}
+
+    def _setup(self, ctype, op):
+        """Initialize the API callback dictionaries.
+
+        :param string ctype: The name of the API to initialize.
+        :param string op: The API operation to initialize.
+        """
+        if ctype not in self.settings:
+            self.settings[ctype] = {}
+        if ctype not in self._handler_defaults:
+            self._handler_defaults[ctype] = {}
+        if ctype not in self._handlers:
+            self._handlers[ctype] = {}
+        if op not in self._handlers[ctype]:
+            self._handlers[ctype][op] = {'global': None,
+                                         'jid': {},
+                                         'node': {}}
+
+    def wrap(self, ctype):
+        """Return a wrapper object that targets a specific API."""
+        return APIWrapper(self, ctype)
+
+    def purge(self, ctype):
+        """Remove all information for a given API."""
+        del self.settings[ctype]
+        del self._handler_defaults[ctype]
+        del self._handlers[ctype]
+
+    def run(self, ctype, op, jid=None, node=None, ifrom=None, args=None):
+        """Execute an API callback, based on specificity.
+
+        The API callback that is executed is chosen based on the combination
+        of the provided JID and node:
+
+        JID   | node  | Handler
+        ==============================
+        Given | Given | Node handler
+        Given | None  | JID handler
+        None  | None  | Global handler
+
+        A node handler is responsible for servicing a single node at a single
+        JID, while a JID handler may respond for any node at a given JID, and
+        the global handler will answer to any JID+node combination.
+
+        Handlers should check that the JID ``ifrom`` is authorized to perform
+        the desired action.
+
+        :param string ctype: The name of the API to use.
+        :param string op: The API operation to perform.
+        :param JID jid: Optionally provide specific JID.
+        :param string node: Optionally provide specific node.
+        :param JID ifrom: Optionally provide the requesting JID.
+        :param tuple args: Optional positional arguments to the handler.
+        """
+        self._setup(ctype, op)
+
+        if not jid:
+            jid = self.xmpp.boundjid
+        elif jid and not isinstance(jid, JID):
+            jid = JID(jid)
+        elif jid == JID(''):
+            jid = self.xmpp.boundjid
+
+        if node is None:
+            node = ''
+
+        if self.xmpp.is_component:
+            if self.settings[ctype].get('component_bare', False):
+                jid = jid.bare
+            else:
+                jid = jid.full
+        else:
+            if self.settings[ctype].get('client_bare', False):
+                jid = jid.bare
+            else:
+                jid = jid.full
+
+        jid = JID(jid)
+
+        handler = self._handlers[ctype][op]['node'].get((jid, node), None)
+        if handler is None:
+            handler = self._handlers[ctype][op]['jid'].get(jid, None)
+        if handler is None:
+            handler = self._handlers[ctype][op].get('global', None)
+
+        if handler:
+            try:
+                return handler(jid, node, ifrom, args)
+            except TypeError:
+                # To preserve backward compatibility, drop the ifrom
+                # parameter for existing handlers that don't understand it.
+                return handler(jid, node, args)
+
+    def register(self, handler, ctype, op, jid=None, node=None, default=False):
+        """Register an API callback, with JID+node specificity.
+
+        The API callback can later be executed based on the
+        specificity of the provided JID+node combination.
+
+        See :meth:`~ApiRegistry.run` for more details.
+
+        :param string ctype: The name of the API to use.
+        :param string op: The API operation to perform.
+        :param JID jid: Optionally provide specific JID.
+        :param string node: Optionally provide specific node.
+        """
+        self._setup(ctype, op)
+        if jid is None and node is None:
+            if handler is None:
+                handler = self._handler_defaults[op]
+            self._handlers[ctype][op]['global'] = handler
+        elif jid is not None and node is None:
+            self._handlers[ctype][op]['jid'][jid] = handler
+        else:
+            self._handlers[ctype][op]['node'][(jid, node)] = handler
+
+        if default:
+            self.register_default(handler, ctype, op)
+
+    def register_default(self, handler, ctype, op):
+        """Register a default, global handler for an operation.
+
+        :param func handler: The default, global handler for the operation.
+        :param string ctype: The name of the API to modify.
+        :param string op: The API operation to use.
+        """
+        self._setup(ctype, op)
+        self._handler_defaults[ctype][op] = handler
+
+    def unregister(self, ctype, op, jid=None, node=None):
+        """Remove an API callback.
+
+        The API callback chosen for removal is based on the
+        specificity of the provided JID+node combination.
+
+        See :meth:`~ApiRegistry.run` for more details.
+
+        :param string ctype: The name of the API to use.
+        :param string op: The API operation to perform.
+        :param JID jid: Optionally provide specific JID.
+        :param string node: Optionally provide specific node.
+        """
+        self._setup(ctype, op)
+        self.register(None, ctype, op, jid, node)
+
+    def restore_default(self, ctype, op, jid=None, node=None):
+        """Reset an API callback to use a default handler.
+
+        :param string ctype: The name of the API to use.
+        :param string op: The API operation to perform.
+        :param JID jid: Optionally provide specific JID.
+        :param string node: Optionally provide specific node.
+        """
+        self.unregister(ctype, op, jid, node)
+        self.register(self._handler_defaults[ctype][op], ctype, op, jid, node)

sleekxmpp/clientxmpp.py

@@ -1,30 +1,27 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.clientxmpp
+    ~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    This module provides XMPP functionality that
+    is specific to client connections.
+
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 from __future__ import absolute_import, unicode_literals
 
 import logging
-import base64
-import sys
-import hashlib
-import random
-import threading
 
-import sleekxmpp
-from sleekxmpp import plugins
-from sleekxmpp import stanza
-from sleekxmpp import features
+from sleekxmpp.stanza import StreamFeatures
 from sleekxmpp.basexmpp import BaseXMPP
-from sleekxmpp.stanza import *
-from sleekxmpp.xmlstream import XMLStream, RestartStream
-from sleekxmpp.xmlstream import StanzaBase, ET, register_stanza_plugin
-from sleekxmpp.xmlstream.matcher import *
-from sleekxmpp.xmlstream.handler import *
+from sleekxmpp.exceptions import XMPPError
+from sleekxmpp.xmlstream import XMLStream
+from sleekxmpp.xmlstream.matcher import StanzaPath, MatchXPath
+from sleekxmpp.xmlstream.handler import Callback
 
 # Flag indicating if DNS SRV records are available for use.
 try:
@@ -41,63 +38,64 @@ log = logging.getLogger(__name__)
 class ClientXMPP(BaseXMPP):
 
     """
-    SleekXMPP's client class. ( Use only for good, not for evil.)
+    SleekXMPP's client class. (Use only for good, not for evil.)
 
-    Typical Use:
-    xmpp = ClientXMPP('user@server.tld/resource', 'password')
-    xmpp.process(block=False) // when block is True, it blocks the current
-    //                           thread. False by default.
+    Typical use pattern:
 
-    Attributes:
+    .. code-block:: python
 
-    Methods:
-        connect          -- Overrides XMLStream.connect.
-        del_roster_item  -- Delete a roster item.
-        get_roster       -- Retrieve the roster from the server.
-        register_feature -- Register a stream feature.
-        update_roster    -- Update a roster item.
+        xmpp = ClientXMPP('user@server.tld/resource', 'password')
+        # ... Register plugins and event handlers ...
+        xmpp.connect()
+        xmpp.process(block=False) # block=True will block the current
+                                  # thread. By default, block=False
+
+    :param jid: The JID of the XMPP user account.
+    :param password: The password for the XMPP user account.
+    :param ssl: **Deprecated.**
+    :param plugin_config: A dictionary of plugin configurations.
+    :param plugin_whitelist: A list of approved plugins that
+                    will be loaded when calling
+                    :meth:`~sleekxmpp.basexmpp.BaseXMPP.register_plugins()`.
+    :param escape_quotes: **Deprecated.**
     """
 
-    def __init__(self, jid, password, ssl=False, plugin_config={},
-                 plugin_whitelist=[], escape_quotes=True):
-        """
-        Create a new SleekXMPP client.
-
-        Arguments:
-            jid              -- The JID of the XMPP user account.
-            password         -- The password for the XMPP user account.
-            ssl              -- Deprecated.
-            plugin_config    -- A dictionary of plugin configurations.
-            plugin_whitelist -- A list of approved plugins that will be loaded
-                                when calling register_plugins.
-            escape_quotes    -- Deprecated.
-        """
+    def __init__(self, jid, password, plugin_config={}, plugin_whitelist=[],
+                 escape_quotes=True, sasl_mech=None, lang='en'):
         BaseXMPP.__init__(self, jid, 'jabber:client')
 
-        self.set_jid(jid)
-        self.password = password
         self.escape_quotes = escape_quotes
         self.plugin_config = plugin_config
         self.plugin_whitelist = plugin_whitelist
         self.default_port = 5222
+        self.default_lang = lang
 
-        self.stream_header = "<stream:stream to='%s' %s %s version='1.0'>" % (
+        self.credentials = {}
+
+        self.password = password
+
+        self.stream_header = "<stream:stream to='%s' %s %s %s %s>" % (
                 self.boundjid.host,
                 "xmlns:stream='%s'" % self.stream_ns,
-                "xmlns='%s'" % self.default_ns)
+                "xmlns='%s'" % self.default_ns,
+                "xml:lang='%s'" % self.default_lang,
+                "version='1.0'")
         self.stream_footer = "</stream:stream>"
 
         self.features = set()
         self._stream_feature_handlers = {}
         self._stream_feature_order = []
 
+        self.dns_service = 'xmpp-client'
+
         #TODO: Use stream state here
         self.authenticated = False
         self.sessionstarted = False
         self.bound = False
         self.bindfail = False
 
-        self.add_event_handler('connected', self._handle_connected)
+        self.add_event_handler('connected', self._reset_connection_state)
+        self.add_event_handler('session_bind', self._handle_session_bind)
 
         self.register_stanza(StreamFeatures)
 
@@ -107,146 +105,154 @@ class ClientXMPP(BaseXMPP):
                          self._handle_stream_features))
         self.register_handler(
                 Callback('Roster Update',
-                         MatchXPath('{%s}iq/{%s}query' % (
-                             self.default_ns,
-                             'jabber:iq:roster')),
+                         StanzaPath('iq@type=set/roster'),
                          self._handle_roster))
 
         # Setup default stream features
         self.register_plugin('feature_starttls')
-        self.register_plugin('feature_mechanisms')
         self.register_plugin('feature_bind')
         self.register_plugin('feature_session')
+        self.register_plugin('feature_rosterver')
+        self.register_plugin('feature_preapproval')
+        self.register_plugin('feature_mechanisms',
+                pconfig={'use_mech': sasl_mech} if sasl_mech else None)
 
-    def connect(self, address=tuple(), reattempt=True, use_tls=True):
-        """
-        Connect to the XMPP server.
+    @property
+    def password(self):
+        return self.credentials.get('password', '')
+
+    @password.setter
+    def password(self, value):
+        self.credentials['password'] = value
+
+    def connect(self, address=tuple(), reattempt=True,
+                use_tls=True, use_ssl=False):
+        """Connect to the XMPP server.
 
         When no address is given, a SRV lookup for the server will
         be attempted. If that fails, the server user in the JID
         will be used.
 
-        Arguments:
-            address   -- A tuple containing the server's host and port.
-            reattempt -- If True, reattempt the connection if an
-                         error occurs. Defaults to True.
-            use_tls   -- Indicates if TLS should be used for the
-                         connection. Defaults to True.
+        :param address   -- A tuple containing the server's host and port.
+        :param reattempt: If ``True``, repeat attempting to connect if an
+                         error occurs. Defaults to ``True``.
+        :param use_tls: Indicates if TLS should be used for the
+                        connection. Defaults to ``True``.
+        :param use_ssl: Indicates if the older SSL connection method
+                        should be used. Defaults to ``False``.
         """
         self.session_started_event.clear()
-        if not address:
+
+        # If an address was provided, disable using DNS SRV lookup;
+        # otherwise, use the domain from the client JID with the standard
+        # XMPP client port and allow SRV lookup.
+        if address:
+            self.dns_service = None
+        else:
             address = (self.boundjid.host, 5222)
+            self.dns_service = 'xmpp-client'
+
+        self._expected_server_name = self.boundjid.host
 
         return XMLStream.connect(self, address[0], address[1],
-                                 use_tls=use_tls, reattempt=reattempt)
-
-    def get_dns_records(self, domain, port=None):
-        """
-        Get the DNS records for a domain.
-        Overriddes XMLStream.get_dns_records to use SRV.
-
-        Arguments:
-            domain -- The domain in question.
-            port   -- If the results don't include a port, use this one.
-        """
-        if port is None:
-            port = self.default_port
-        if DNSPYTHON:
-            try:
-                record = "_xmpp-client._tcp.%s" % domain
-                answers = []
-                for answer in dns.resolver.query(record, dns.rdatatype.SRV):
-                    address = (answer.target.to_text()[:-1], answer.port)
-                    answers.append((address, answer.priority, answer.weight))
-            except (dns.resolver.NXDOMAIN, dns.resolver.NoAnswer):
-                log.warning("No SRV records for %s" % domain)
-                answers = super(ClientXMPP, self).get_dns_records(domain, port)
-            except dns.exception.Timeout:
-                log.warning("DNS resolution timed out " + \
-                            "for SRV record of %s" % domain)
-                answers = super(ClientXMPP, self).get_dns_records(domain, port)
-            return answers
-        else:
-            log.warning("dnspython is not installed -- " + \
-                        "relying on OS A record resolution")
-            return [((domain, port), 0, 0)]
+                                 use_tls=use_tls, use_ssl=use_ssl,
+                                 reattempt=reattempt)
 
     def register_feature(self, name, handler, restart=False, order=5000):
-        """
-        Register a stream feature.
+        """Register a stream feature handler.
 
-        Arguments:
-            name    -- The name of the stream feature.
-            handler -- The function to execute if the feature is received.
-            restart -- Indicates if feature processing should halt with
-                       this feature. Defaults to False.
-            order   -- The relative ordering in which the feature should
-                       be negotiated. Lower values will be attempted
-                       earlier when available.
+        :param name: The name of the stream feature.
+        :param handler: The function to execute if the feature is received.
+        :param restart: Indicates if feature processing should halt with
+                        this feature. Defaults to ``False``.
+        :param order: The relative ordering in which the feature should
+                      be negotiated. Lower values will be attempted
+                      earlier when available.
         """
         self._stream_feature_handlers[name] = (handler, restart)
         self._stream_feature_order.append((order, name))
         self._stream_feature_order.sort()
 
-    def update_roster(self, jid, name=None, subscription=None, groups=[],
-                            block=True, timeout=None, callback=None):
-        """
-        Add or change a roster item.
+    def unregister_feature(self, name, order):
+        if name in self._stream_feature_handlers:
+            del self._stream_feature_handlers[name]
+        self._stream_feature_order.remove((order, name))
+        self._stream_feature_order.sort()
 
-        Arguments:
-            jid          -- The JID of the entry to modify.
-            name         -- The user's nickname for this JID.
-            subscription -- The subscription status. May be one of
-                            'to', 'from', 'both', or 'none'. If set
-                            to 'remove', the entry will be deleted.
-            groups       -- The roster groups that contain this item.
-            block        -- Specify if the roster request will block
-                            until a response is received, or a timeout
-                            occurs. Defaults to True.
-            timeout      -- The length of time (in seconds) to wait
-                            for a response before continuing if blocking
-                            is used. Defaults to self.response_timeout.
-            callback     -- Optional reference to a stream handler function.
-                            Will be executed when the roster is received.
-                            Implies block=False.
+    def update_roster(self, jid, **kwargs):
+        """Add or change a roster item.
+
+        :param jid: The JID of the entry to modify.
+        :param name: The user's nickname for this JID.
+        :param subscription: The subscription status. May be one of
+                             ``'to'``, ``'from'``, ``'both'``, or
+                             ``'none'``. If set to ``'remove'``,
+                             the entry will be deleted.
+        :param groups: The roster groups that contain this item.
+        :param block: Specify if the roster request will block
+                      until a response is received, or a timeout
+                      occurs. Defaults to ``True``.
+        :param timeout: The length of time (in seconds) to wait
+                        for a response before continuing if blocking
+                        is used. Defaults to
+            :attr:`~sleekxmpp.xmlstream.xmlstream.XMLStream.response_timeout`.
+        :param callback: Optional reference to a stream handler function.
+                         Will be executed when the roster is received.
+                         Implies ``block=False``.
         """
-        return self.client_roster.updtae(jid, name, subscription, groups,
+        current = self.client_roster[jid]
+
+        name = kwargs.get('name', current['name'])
+        subscription = kwargs.get('subscription', current['subscription'])
+        groups = kwargs.get('groups', current['groups'])
+
+        block = kwargs.get('block', True)
+        timeout = kwargs.get('timeout', None)
+        callback = kwargs.get('callback', None)
+
+        return self.client_roster.update(jid, name, subscription, groups,
                                          block, timeout, callback)
 
     def del_roster_item(self, jid):
-        """
-        Remove an item from the roster by setting its subscription
-        status to 'remove'.
+        """Remove an item from the roster.
 
-        Arguments:
-            jid -- The JID of the item to remove.
+        This is done by setting its subscription status to ``'remove'``.
+
+        :param jid: The JID of the item to remove.
         """
         return self.client_roster.remove(jid)
 
     def get_roster(self, block=True, timeout=None, callback=None):
-        """
-        Request the roster from the server.
+        """Request the roster from the server.
 
-        Arguments:
-            block    -- Specify if the roster request will block until a
-                        response is received, or a timeout occurs.
-                        Defaults to True.
-            timeout  -- The length of time (in seconds) to wait for a response
+        :param block: Specify if the roster request will block until a
+                      response is received, or a timeout occurs.
+                      Defaults to ``True``.
+        :param timeout: The length of time (in seconds) to wait for a response
                         before continuing if blocking is used.
-                        Defaults to self.response_timeout.
-            callback -- Optional reference to a stream handler function. Will
-                        be executed when the roster is received.
-                        Implies block=False.
+                        Defaults to
+            :attr:`~sleekxmpp.xmlstream.xmlstream.XMLStream.response_timeout`.
+        :param callback: Optional reference to a stream handler function. Will
+                         be executed when the roster is received.
+                         Implies ``block=False``.
         """
         iq = self.Iq()
         iq['type'] = 'get'
         iq.enable('roster')
+        if 'rosterver' in self.features:
+            iq['roster']['ver'] = self.client_roster.version
+
+        if not block and callback is None:
+            callback = lambda resp: self._handle_roster(resp)
+
         response = iq.send(block, timeout, callback)
+        self.event('roster_received', response)
 
-        if callback is None:
-            return self._handle_roster(response, request=True)
+        if block:
+            self._handle_roster(response)
+            return response
 
-    def _handle_connected(self, event=None):
+    def _reset_connection_state(self, event=None):
         #TODO: Use stream state here
         self.authenticated = False
         self.sessionstarted = False
@@ -255,11 +261,9 @@ class ClientXMPP(BaseXMPP):
         self.features = set()
 
     def _handle_stream_features(self, features):
-        """
-        Process the received stream features.
+        """Process the received stream features.
 
-        Arguments:
-            features -- The features stanza.
+        :param features: The features stanza.
         """
         for order, name in self._stream_feature_order:
             if name in features['features']:
@@ -268,33 +272,49 @@ class ClientXMPP(BaseXMPP):
                     # Don't continue if the feature requires
                     # restarting the XML stream.
                     return True
+        log.debug('Finished processing stream features.')
+        self.event('stream_negotiated')
 
-    def _handle_roster(self, iq, request=False):
-        """
-        Update the roster after receiving a roster stanza.
+    def _handle_roster(self, iq):
+        """Update the roster after receiving a roster stanza.
 
-        Arguments:
-            iq      -- The roster stanza.
-            request -- Indicates if this stanza is a response
-                       to a request for the roster.
+        :param iq: The roster stanza.
         """
-        if iq['type'] == 'set' or (iq['type'] == 'result' and request):
-            for jid in iq['roster']['items']:
-                item = iq['roster']['items'][jid]
-                roster = self.roster[iq['to'].bare]
+        if iq['type'] == 'set':
+            if iq['from'].bare and iq['from'].bare != self.boundjid.bare:
+                raise XMPPError(condition='service-unavailable')
+
+        roster = self.client_roster
+        if iq['roster']['ver']:
+            roster.version = iq['roster']['ver']
+        items = iq['roster']['items']
+
+        valid_subscriptions = ('to', 'from', 'both', 'none', 'remove')
+        for jid, item in items.items():
+            if item['subscription'] in valid_subscriptions:
                 roster[jid]['name'] = item['name']
                 roster[jid]['groups'] = item['groups']
-                roster[jid]['from'] = item['subscription'] in ['from', 'both']
-                roster[jid]['to'] = item['subscription'] in ['to', 'both']
+                roster[jid]['from'] = item['subscription'] in ('from', 'both')
+                roster[jid]['to'] = item['subscription'] in ('to', 'both')
                 roster[jid]['pending_out'] = (item['ask'] == 'subscribe')
-            self.event('roster_received', iq)
+
+                roster[jid].save(remove=(item['subscription'] == 'remove'))
 
         self.event("roster_update", iq)
         if iq['type'] == 'set':
-            iq.reply()
-            iq.enable('roster')
-            iq.send()
-        return True
+            resp = self.Iq(stype='result',
+                           sto=iq['from'],
+                           sid=iq['id'])
+            resp.enable('roster')
+            resp.send()
+
+    def _handle_session_bind(self, jid):
+        """Set the client roster to the JID set by the server.
+
+        :param :class:`sleekxmpp.xmlstream.jid.JID` jid: The bound JID as
+            dictated by the server. The same as :attr:`boundjid`.
+        """
+        self.client_roster = self.roster[jid]
 
 
 # To comply with PEP8, method names now use underscores.

sleekxmpp/componentxmpp.py

@@ -1,25 +1,28 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.clientxmpp
+    ~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    This module provides XMPP functionality that
+    is specific to external server component connections.
+
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 from __future__ import absolute_import
 
 import logging
-import base64
 import sys
 import hashlib
 
-from sleekxmpp import plugins
-from sleekxmpp import stanza
 from sleekxmpp.basexmpp import BaseXMPP
-from sleekxmpp.xmlstream import XMLStream, RestartStream
-from sleekxmpp.xmlstream import StanzaBase, ET
-from sleekxmpp.xmlstream.matcher import *
-from sleekxmpp.xmlstream.handler import *
+from sleekxmpp.xmlstream import XMLStream
+from sleekxmpp.xmlstream import ET
+from sleekxmpp.xmlstream.matcher import MatchXPath
+from sleekxmpp.xmlstream.handler import Callback
 
 
 log = logging.getLogger(__name__)
@@ -32,28 +35,22 @@ class ComponentXMPP(BaseXMPP):
 
     Use only for good, not for evil.
 
-    Methods:
-        connect              -- Overrides XMLStream.connect.
-        incoming_filter      -- Overrides XMLStream.incoming_filter.
-        start_stream_handler -- Overrides XMLStream.start_stream_handler.
+    :param jid: The JID of the component.
+    :param secret: The secret or password for the component.
+    :param host: The server accepting the component.
+    :param port: The port used to connect to the server.
+    :param plugin_config: A dictionary of plugin configurations.
+    :param plugin_whitelist: A list of approved plugins that
+                    will be loaded when calling
+                    :meth:`~sleekxmpp.basexmpp.BaseXMPP.register_plugins()`.
+    :param use_jc_ns: Indicates if the ``'jabber:client'`` namespace
+                      should be used instead of the standard
+                      ``'jabber:component:accept'`` namespace.
+                      Defaults to ``False``.
     """
 
-    def __init__(self, jid, secret, host, port,
+    def __init__(self, jid, secret, host=None, port=None,
                  plugin_config={}, plugin_whitelist=[], use_jc_ns=False):
-        """
-        Arguments:
-            jid              -- The JID of the component.
-            secret           -- The secret or password for the component.
-            host             -- The server accepting the component.
-            port             -- The port used to connect to the server.
-            plugin_config    -- A dictionary of plugin configurations.
-            plugin_whitelist -- A list of desired plugins to load
-                                when using register_plugins.
-            use_js_ns        -- Indicates if the 'jabber:client' namespace
-                                should be used instead of the standard
-                                'jabber:component:accept' namespace.
-                                Defaults to False.
-        """
         if use_jc_ns:
             default_ns = 'jabber:client'
         else:
@@ -81,26 +78,48 @@ class ComponentXMPP(BaseXMPP):
         self.add_event_handler('presence_probe',
                                self._handle_probe)
 
-    def connect(self):
-        """
-        Connect to the server.
+    def connect(self, host=None, port=None, use_ssl=False,
+                      use_tls=False, reattempt=True):
+        """Connect to the server.
 
-        Overrides XMLStream.connect.
+        Setting ``reattempt`` to ``True`` will cause connection attempts to
+        be made every second until a successful connection is established.
+
+        :param host: The name of the desired server for the connection.
+                     Defaults to :attr:`server_host`.
+        :param port: Port to connect to on the server.
+                     Defauts to :attr:`server_port`.
+        :param use_ssl: Flag indicating if SSL should be used by connecting
+                        directly to a port using SSL.
+        :param use_tls: Flag indicating if TLS should be used, allowing for
+                        connecting to a port without using SSL immediately and
+                        later upgrading the connection.
+        :param reattempt: Flag indicating if the socket should reconnect
+                          after disconnections.
         """
-        log.debug("Connecting to %s:%s" % (self.server_host,
-                                               self.server_port))
-        return XMLStream.connect(self, self.server_host,
-                                       self.server_port)
+        if host is None:
+            host = self.server_host
+        if port is None:
+            port = self.server_port
+
+        self.server_name = self.boundjid.host
+
+        if use_tls:
+            log.info("XEP-0114 components can not use TLS")
+
+        log.debug("Connecting to %s:%s", host, port)
+        return XMLStream.connect(self, host=host, port=port,
+                                       use_ssl=use_ssl,
+                                       use_tls=False,
+                                       reattempt=reattempt)
 
     def incoming_filter(self, xml):
         """
-        Pre-process incoming XML stanzas by converting any 'jabber:client'
-        namespaced elements to the component's default namespace.
+        Pre-process incoming XML stanzas by converting any
+        ``'jabber:client'`` namespaced elements to the component's
+        default namespace.
 
-        Overrides XMLStream.incoming_filter.
-
-        Arguments:
-            xml -- The XML stanza to pre-process.
+        :param xml: The XML stanza to pre-process.
         """
         if xml.tag.startswith('{jabber:client}'):
             xml.tag = xml.tag.replace('jabber:client', self.default_ns)
@@ -117,10 +136,7 @@ class ComponentXMPP(BaseXMPP):
         Once the streams are established, attempt to handshake
         with the server to be accepted as a component.
 
-        Overrides BaseXMPP.start_stream_handler.
-
-        Arguments:
-            xml -- The incoming stream's root element.
+        :param xml: The incoming stream's root element.
         """
         BaseXMPP.start_stream_handler(self, xml)
 
@@ -136,16 +152,14 @@ class ComponentXMPP(BaseXMPP):
         self.send_xml(handshake, now=True)
 
     def _handle_handshake(self, xml):
-        """
-        The handshake has been accepted.
+        """The handshake has been accepted.
 
-        Arguments:
-            xml -- The reply handshake stanza.
+        :param xml: The reply handshake stanza.
         """
+        self.session_bind_event.set()
         self.session_started_event.set()
+        self.event("session_bind", self.boundjid, direct=True)
         self.event("session_start")
 
-    def _handle_probe(self, presence):
-        pto = presence['to'].bare
-        pfrom = presence['from'].bare
-        self.roster[pto][pfrom].handle_probe(presence)
+    def _handle_probe(self, pres):
+        self.roster[pres['to']][pres['from']].handle_probe(pres)

sleekxmpp/exceptions.py

@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.exceptions
+    ~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 
@@ -13,37 +16,35 @@ class XMPPError(Exception):
     A generic exception that may be raised while processing an XMPP stanza
     to indicate that an error response stanza should be sent.
 
-    The exception method for stanza objects extending RootStanza will create
-    an error stanza and initialize any additional substanzas using the
-    extension information included in the exception.
+    The exception method for stanza objects extending
+    :class:`~sleekxmpp.stanza.rootstanza.RootStanza` will create an error
+    stanza and initialize any additional substanzas using the extension
+    information included in the exception.
 
     Meant for use in SleekXMPP plugins and applications using SleekXMPP.
+
+    Extension information can be included to add additional XML elements
+    to the generated error stanza.
+
+    :param condition: The XMPP defined error condition.
+                      Defaults to ``'undefined-condition'``.
+    :param text: Human readable text describing the error.
+    :param etype: The XMPP error type, such as ``'cancel'`` or ``'modify'``.
+                  Defaults to ``'cancel'``.
+    :param extension: Tag name of the extension's XML content.
+    :param extension_ns: XML namespace of the extensions' XML content.
+    :param extension_args: Content and attributes for the extension
+                           element. Same as the additional arguments to
+                           the :class:`~xml.etree.ElementTree.Element`
+                           constructor.
+    :param clear: Indicates if the stanza's contents should be
+                  removed before replying with an error.
+                  Defaults to ``True``.
     """
 
     def __init__(self, condition='undefined-condition', text=None,
                 etype='cancel', extension=None, extension_ns=None,
                 extension_args=None, clear=True):
-        """
-        Create a new XMPPError exception.
-
-        Extension information can be included to add additional XML elements
-        to the generated error stanza.
-
-        Arguments:
-            condition      -- The XMPP defined error condition.
-                              Defaults to 'undefined-condition'.
-            text           -- Human readable text describing the error.
-            etype          -- The XMPP error type, such as cancel or modify.
-                              Defaults to 'cancel'.
-            extension      -- Tag name of the extension's XML content.
-            extension_ns   -- XML namespace of the extensions' XML content.
-            extension_args -- Content and attributes for the extension
-                              element. Same as the additional arguments to
-                              the ET.Element constructor.
-            clear          -- Indicates if the stanza's contents should be
-                              removed before replying with an error.
-                              Defaults to True.
-        """
         if extension_args is None:
             extension_args = {}
 
@@ -68,8 +69,11 @@ class IqTimeout(XMPPError):
                 condition='remote-server-timeout',
                 etype='cancel')
 
+        #: The :class:`~sleekxmpp.stanza.iq.Iq` stanza whose response
+        #: did not arrive before the timeout expired.
         self.iq = iq
 
+
 class IqError(XMPPError):
 
     """
@@ -83,4 +87,5 @@ class IqError(XMPPError):
                 text=iq['error']['text'],
                 etype=iq['error']['type'])
 
+        #: The :class:`~sleekxmpp.stanza.iq.Iq` error result stanza.
         self.iq = iq

sleekxmpp/features/__init__.py

@@ -6,4 +6,11 @@
     See the file LICENSE for copying permission.
 """
 
-__all__ = ['feature_starttls', 'feature_mechanisms', 'feature_bind']
+__all__ = [
+    'feature_starttls',
+    'feature_mechanisms',
+    'feature_bind',
+    'feature_session',
+    'feature_rosterver',
+    'feature_preapproval'
+]

sleekxmpp/features/feature_bind/__init__.py

@@ -6,5 +6,14 @@
     See the file LICENSE for copying permission.
 """
 
-from sleekxmpp.features.feature_bind.bind import feature_bind
+from sleekxmpp.plugins.base import register_plugin
+
+from sleekxmpp.features.feature_bind.bind import FeatureBind
 from sleekxmpp.features.feature_bind.stanza import Bind
+
+
+register_plugin(FeatureBind)
+
+
+# Retain some backwards compatibility
+feature_bind = FeatureBind

sleekxmpp/features/feature_bind/bind.py

@@ -8,25 +8,24 @@
 
 import logging
 
+from sleekxmpp.jid import JID
 from sleekxmpp.stanza import Iq, StreamFeatures
 from sleekxmpp.features.feature_bind import stanza
 from sleekxmpp.xmlstream import register_stanza_plugin
-from sleekxmpp.xmlstream.matcher import *
-from sleekxmpp.xmlstream.handler import *
-from sleekxmpp.plugins.base import base_plugin
+from sleekxmpp.plugins import BasePlugin, register_plugin
 
 
 log = logging.getLogger(__name__)
 
 
-class feature_bind(base_plugin):
+class FeatureBind(BasePlugin):
+
+    name = 'feature_bind'
+    description = 'RFC 6120: Stream Feature: Resource Binding'
+    dependencies = set()
+    stanza = stanza
 
     def plugin_init(self):
-        self.name = 'Bind Resource'
-        self.rfc = '6120'
-        self.description = 'Resource Binding Stream Feature'
-        self.stanza = stanza
-
         self.xmpp.register_feature('bind',
                 self._handle_bind_resource,
                 restart=False,
@@ -42,7 +41,7 @@ class feature_bind(base_plugin):
         Arguments:
             features -- The stream features stanza.
         """
-        log.debug("Requesting resource: %s" % self.xmpp.boundjid.resource)
+        log.debug("Requesting resource: %s", self.xmpp.boundjid.resource)
         iq = self.xmpp.Iq()
         iq['type'] = 'set'
         iq.enable('bind')
@@ -50,12 +49,14 @@ class feature_bind(base_plugin):
             iq['bind']['resource'] = self.xmpp.boundjid.resource
         response = iq.send(now=True)
 
-        self.xmpp.set_jid(response['bind']['jid'])
+        self.xmpp.boundjid = JID(response['bind']['jid'], cache_lock=True)
         self.xmpp.bound = True
+        self.xmpp.event('session_bind', self.xmpp.boundjid, direct=True)
+        self.xmpp.session_bind_event.set()
 
         self.xmpp.features.add('bind')
 
-        log.info("Node set to: %s" % self.xmpp.boundjid.full)
+        log.info("Node set to: %s", self.xmpp.boundjid.full)
 
         if 'session' not in features['features']:
             log.debug("Established Session")

sleekxmpp/features/feature_bind/stanza.py

@@ -6,8 +6,7 @@
     See the file LICENSE for copying permission.
 """
 
-from sleekxmpp.stanza import Iq, StreamFeatures
-from sleekxmpp.xmlstream import ElementBase, ET, register_stanza_plugin
+from sleekxmpp.xmlstream import ElementBase
 
 
 class Bind(ElementBase):

sleekxmpp/features/feature_mechanisms/__init__.py

@@ -6,8 +6,17 @@
     See the file LICENSE for copying permission.
 """
 
-from sleekxmpp.features.feature_mechanisms.mechanisms import feature_mechanisms
+from sleekxmpp.plugins.base import register_plugin
+
+from sleekxmpp.features.feature_mechanisms.mechanisms import FeatureMechanisms
 from sleekxmpp.features.feature_mechanisms.stanza import Mechanisms
 from sleekxmpp.features.feature_mechanisms.stanza import Auth
 from sleekxmpp.features.feature_mechanisms.stanza import Success
 from sleekxmpp.features.feature_mechanisms.stanza import Failure
+
+
+register_plugin(FeatureMechanisms)
+
+
+# Retain some backwards compatibility
+feature_mechanisms = FeatureMechanisms

sleekxmpp/features/feature_mechanisms/mechanisms.py

@@ -6,52 +6,56 @@
     See the file LICENSE for copying permission.
 """
 
+import sys
+import ssl
 import logging
 
-from sleekxmpp.thirdparty import suelta
-
+from sleekxmpp.util import sasl
+from sleekxmpp.util.stringprep_profiles import StringPrepError
 from sleekxmpp.stanza import StreamFeatures
 from sleekxmpp.xmlstream import RestartStream, register_stanza_plugin
-from sleekxmpp.xmlstream.matcher import *
-from sleekxmpp.xmlstream.handler import *
-from sleekxmpp.plugins.base import base_plugin
+from sleekxmpp.plugins import BasePlugin
+from sleekxmpp.xmlstream.matcher import MatchXPath
+from sleekxmpp.xmlstream.handler import Callback
 from sleekxmpp.features.feature_mechanisms import stanza
 
 
 log = logging.getLogger(__name__)
 
 
-class feature_mechanisms(base_plugin):
+class FeatureMechanisms(BasePlugin):
+
+    name = 'feature_mechanisms'
+    description = 'RFC 6120: Stream Feature: SASL'
+    dependencies = set()
+    stanza = stanza
+    default_config = {
+        'use_mech': None,
+        'use_mechs': None,
+        'min_mech': None,
+        'sasl_callback': None,
+        'security_callback': None,
+        'encrypted_plain': True,
+        'unencrypted_plain': False,
+        'unencrypted_digest': False,
+        'unencrypted_cram': False,
+        'unencrypted_scram': True,
+        'order': 100
+    }
 
     def plugin_init(self):
-        self.name = 'SASL Mechanisms'
-        self.rfc = '6120'
-        self.description = "SASL Stream Feature"
-        self.stanza = stanza
+        if not self.use_mech and not self.xmpp.requested_jid.user:
+            self.use_mech = 'ANONYMOUS'
 
-        self.use_mech = self.config.get('use_mech', None)
+        if self.sasl_callback is None:
+            self.sasl_callback = self._default_credentials
 
-        def tls_active():
-            return 'starttls' in self.xmpp.features
-
-        def basic_callback(mech, values):
-            if 'username' in values:
-                values['username'] = self.xmpp.boundjid.user
-            if 'password' in values:
-                values['password'] = self.xmpp.password
-            mech.fulfill(values)
-
-        sasl_callback = self.config.get('sasl_callback', None)
-        if sasl_callback is None:
-            sasl_callback = basic_callback
+        if self.security_callback is None:
+            self.security_callback = self._default_security
 
         self.mech = None
-        self.sasl = suelta.SASL(self.xmpp.boundjid.domain, 'xmpp',
-                                username=self.xmpp.boundjid.user,
-                                sec_query=suelta.sec_query_allow,
-                                request_values=sasl_callback,
-                                tls_active=tls_active,
-                                mech=self.use_mech)
+        self.mech_list = set()
+        self.attempted_mechs = set()
 
         register_stanza_plugin(StreamFeatures, stanza.Mechanisms)
 
@@ -60,19 +64,18 @@ class feature_mechanisms(base_plugin):
         self.xmpp.register_stanza(stanza.Auth)
         self.xmpp.register_stanza(stanza.Challenge)
         self.xmpp.register_stanza(stanza.Response)
+        self.xmpp.register_stanza(stanza.Abort)
 
         self.xmpp.register_handler(
                 Callback('SASL Success',
                          MatchXPath(stanza.Success.tag_name()),
                          self._handle_success,
-                         instream=True,
-                         once=True))
+                         instream=True))
         self.xmpp.register_handler(
                 Callback('SASL Failure',
                          MatchXPath(stanza.Failure.tag_name()),
                          self._handle_fail,
-                         instream=True,
-                         once=True))
+                         instream=True))
         self.xmpp.register_handler(
                 Callback('SASL Challenge',
                          MatchXPath(stanza.Challenge.tag_name()),
@@ -81,7 +84,52 @@ class feature_mechanisms(base_plugin):
         self.xmpp.register_feature('mechanisms',
                 self._handle_sasl_auth,
                 restart=True,
-                order=self.config.get('order', 100))
+                order=self.order)
+
+    def _default_credentials(self, required_values, optional_values):
+        creds = self.xmpp.credentials
+        result = {}
+        values = required_values.union(optional_values)
+        for value in values:
+            if value == 'username':
+                result[value] = self.xmpp.requested_jid.user
+            elif value == 'password':
+                result[value] = creds['password']
+            elif value == 'authzid':
+                result[value] = creds.get('authzid', '')
+            elif value == 'email':
+                jid = self.xmpp.requested_jid.bare
+                result[value] = creds.get('email', jid)
+            elif value == 'channel_binding':
+                if sys.version_info >= (3, 3):
+                    result[value] = self.xmpp.socket.get_channel_binding()
+                else:
+                    result[value] = None
+            elif value == 'host':
+                result[value] = self.xmpp.requested_jid.domain
+            elif value == 'realm':
+                result[value] = self.xmpp.requested_jid.domain
+            elif value == 'service-name':
+                result[value] = self.xmpp._service_name
+            elif value == 'service':
+                result[value] = 'xmpp'
+            elif value in creds:
+                result[value] = creds[value]
+        return result
+
+    def _default_security(self, values):
+        result = {}
+        for value in values:
+            if value == 'encrypted':
+                if 'starttls' in self.xmpp.features:
+                    result[value] = True
+                elif isinstance(self.xmpp.socket, ssl.SSLSocket):
+                    result[value] = True
+                else:
+                    result[value] = False
+            else:
+                result[value] = self.config.get(value, False)
+        return result
 
     def _handle_sasl_auth(self, features):
         """
@@ -95,35 +143,100 @@ class feature_mechanisms(base_plugin):
             # server has incorrectly offered it again.
             return False
 
-        mech_list = features['mechanisms']
-        self.mech = self.sasl.choose_mechanism(mech_list)
+        enforce_limit = False
+        limited_mechs = self.use_mechs
 
-        if self.mech is not None:
-            resp = stanza.Auth(self.xmpp)
-            resp['mechanism'] = self.mech.name
-            resp['value'] = self.mech.process()
-            resp.send(now=True)
-        else:
+        if limited_mechs is None:
+            limited_mechs = set()
+        elif limited_mechs and not isinstance(limited_mechs, set):
+            limited_mechs = set(limited_mechs)
+            enforce_limit = True
+
+        if self.use_mech:
+            limited_mechs.add(self.use_mech)
+            enforce_limit = True
+
+        if enforce_limit:
+            self.use_mechs = limited_mechs
+
+        self.mech_list = set(features['mechanisms'])
+
+        return self._send_auth()
+
+    def _send_auth(self):
+        mech_list = self.mech_list - self.attempted_mechs
+        try:
+            self.mech = sasl.choose(mech_list,
+                                    self.sasl_callback,
+                                    self.security_callback,
+                                    limit=self.use_mechs,
+                                    min_mech=self.min_mech)
+        except sasl.SASLNoAppropriateMechanism:
             log.error("No appropriate login method.")
             self.xmpp.event("no_auth", direct=True)
+            self.attempted_mechs = set()
+            return self.xmpp.disconnect()
+
+        resp = stanza.Auth(self.xmpp)
+        resp['mechanism'] = self.mech.name
+        try:
+            resp['value'] = self.mech.process()
+        except sasl.SASLCancelled:
+            self.attempted_mechs.add(self.mech.name)
+            self._send_auth()
+        except sasl.SASLFailed:
+            self.attempted_mechs.add(self.mech.name)
+            self._send_auth()
+        except sasl.SASLMutualAuthFailed:
+            log.error("Mutual authentication failed! " + \
+                      "A security breach is possible.")
+            self.attempted_mechs.add(self.mech.name)
             self.xmpp.disconnect()
+        except StringPrepError:
+            log.exception("A credential value did not pass SASLprep.")
+            self.xmpp.disconnect()
+        else:
+            resp.send(now=True)
+
         return True
 
     def _handle_challenge(self, stanza):
         """SASL challenge received. Process and send response."""
         resp = self.stanza.Response(self.xmpp)
-        resp['value'] = self.mech.process(stanza['value'])
-        resp.send(now=True)
+        try:
+            resp['value'] = self.mech.process(stanza['value'])
+        except sasl.SASLCancelled:
+            self.stanza.Abort(self.xmpp).send()
+        except sasl.SASLFailed:
+            self.stanza.Abort(self.xmpp).send()
+        except sasl.SASLMutualAuthFailed:
+            log.error("Mutual authentication failed! " + \
+                      "A security breach is possible.")
+            self.attempted_mechs.add(self.mech.name)
+            self.xmpp.disconnect()
+        else:
+            resp.send(now=True)
 
     def _handle_success(self, stanza):
         """SASL authentication succeeded. Restart the stream."""
-        self.xmpp.authenticated = True
-        self.xmpp.features.add('mechanisms')
-        raise RestartStream()
+        try:
+            final = self.mech.process(stanza['value'])
+        except sasl.SASLMutualAuthFailed:
+            log.error("Mutual authentication failed! " + \
+                      "A security breach is possible.")
+            self.attempted_mechs.add(self.mech.name)
+            self.xmpp.disconnect()
+        else:
+            self.attempted_mechs = set()
+            self.xmpp.authenticated = True
+            self.xmpp.features.add('mechanisms')
+            self.xmpp.event('auth_success', stanza, direct=True)
+            raise RestartStream()
 
     def _handle_fail(self, stanza):
         """SASL authentication failed. Disconnect and shutdown."""
-        log.info("Authentication failed: %s" % stanza['condition'])
+        self.attempted_mechs.add(self.mech.name)
+        log.info("Authentication failed: %s", stanza['condition'])
         self.xmpp.event("failed_auth", stanza, direct=True)
-        self.xmpp.disconnect()
+        self._send_auth()
         return True

sleekxmpp/features/feature_mechanisms/stanza/__init__.py

@@ -13,3 +13,4 @@ from sleekxmpp.features.feature_mechanisms.stanza.success import Success
 from sleekxmpp.features.feature_mechanisms.stanza.failure import Failure
 from sleekxmpp.features.feature_mechanisms.stanza.challenge import Challenge
 from sleekxmpp.features.feature_mechanisms.stanza.response import Response
+from sleekxmpp.features.feature_mechanisms.stanza.abort import Abort

sleekxmpp/features/feature_mechanisms/stanza/abort.py

@@ -0,0 +1,24 @@
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2011  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+from sleekxmpp.xmlstream import StanzaBase
+
+
+class Abort(StanzaBase):
+
+    """
+    """
+
+    name = 'abort'
+    namespace = 'urn:ietf:params:xml:ns:xmpp-sasl'
+    interfaces = set()
+    plugin_attrib = name
+
+    def setup(self, xml):
+        StanzaBase.setup(self, xml)
+        self.xml.tag = self.tag_name()

sleekxmpp/features/feature_mechanisms/stanza/auth.py

@@ -8,11 +8,8 @@
 
 import base64
 
-from sleekxmpp.thirdparty.suelta.util import bytes
-
-from sleekxmpp.stanza import StreamFeatures
-from sleekxmpp.xmlstream import ElementBase, StanzaBase, ET
-from sleekxmpp.xmlstream import register_stanza_plugin
+from sleekxmpp.util import bytes
+from sleekxmpp.xmlstream import StanzaBase
 
 
 class Auth(StanzaBase):
@@ -25,15 +22,28 @@ class Auth(StanzaBase):
     interfaces = set(('mechanism', 'value'))
     plugin_attrib = name
 
+    #: Some SASL mechs require sending values as is,
+    #: without converting base64.
+    plain_mechs = set(['X-MESSENGER-OAUTH2'])
+
     def setup(self, xml):
         StanzaBase.setup(self, xml)
         self.xml.tag = self.tag_name()
 
     def get_value(self):
-        return base64.b64decode(bytes(self.xml.text))
+        if not self['mechanism'] in self.plain_mechs:
+            return base64.b64decode(bytes(self.xml.text))
+        else:
+            return self.xml.text
 
     def set_value(self, values):
-        self.xml.text = bytes(base64.b64encode(values)).decode('utf-8')
+        if not self['mechanism'] in self.plain_mechs:
+            if values:
+                self.xml.text = bytes(base64.b64encode(values)).decode('utf-8')
+            else:
+                self.xml.text = '='
+        else:
+            self.xml.text = bytes(values).decode('utf-8')
 
     def del_value(self):
         self.xml.text = ''

sleekxmpp/features/feature_mechanisms/stanza/challenge.py

@@ -8,11 +8,8 @@
 
 import base64
 
-from sleekxmpp.thirdparty.suelta.util import bytes
-
-from sleekxmpp.stanza import StreamFeatures
-from sleekxmpp.xmlstream import ElementBase, StanzaBase, ET
-from sleekxmpp.xmlstream import register_stanza_plugin
+from sleekxmpp.util import bytes
+from sleekxmpp.xmlstream import StanzaBase
 
 
 class Challenge(StanzaBase):
@@ -33,7 +30,10 @@ class Challenge(StanzaBase):
         return base64.b64decode(bytes(self.xml.text))
 
     def set_value(self, values):
-        self.xml.text = bytes(base64.b64encode(values)).decode('utf-8')
+        if values:
+            self.xml.text = bytes(base64.b64encode(values)).decode('utf-8')
+        else:
+            self.xml.text = '='
 
     def del_value(self):
         self.xml.text = ''

sleekxmpp/features/feature_mechanisms/stanza/failure.py

@@ -6,9 +6,7 @@
     See the file LICENSE for copying permission.
 """
 
-from sleekxmpp.stanza import StreamFeatures
-from sleekxmpp.xmlstream import ElementBase, StanzaBase, ET
-from sleekxmpp.xmlstream import register_stanza_plugin
+from sleekxmpp.xmlstream import StanzaBase, ET
 
 
 class Failure(StanzaBase):
@@ -49,7 +47,7 @@ class Failure(StanzaBase):
 
     def get_condition(self):
         """Return the condition element's name."""
-        for child in self.xml.getchildren():
+        for child in self.xml:
             if "{%s}" % self.namespace in child.tag:
                 cond = child.tag.split('}', 1)[-1]
                 if cond in self.conditions:
@@ -70,7 +68,7 @@ class Failure(StanzaBase):
 
     def del_condition(self):
         """Remove the condition element."""
-        for child in self.xml.getchildren():
+        for child in self.xml:
             if "{%s}" % self.condition_ns in child.tag:
                 tag = child.tag.split('}', 1)[-1]
                 if tag in self.conditions:

sleekxmpp/features/feature_mechanisms/stanza/mechanisms.py

@@ -6,9 +6,7 @@
     See the file LICENSE for copying permission.
 """
 
-from sleekxmpp.stanza import StreamFeatures
-from sleekxmpp.xmlstream import ElementBase, StanzaBase, ET
-from sleekxmpp.xmlstream import register_stanza_plugin
+from sleekxmpp.xmlstream import ElementBase, ET
 
 
 class Mechanisms(ElementBase):

sleekxmpp/features/feature_mechanisms/stanza/response.py

@@ -8,11 +8,8 @@
 
 import base64
 
-from sleekxmpp.thirdparty.suelta.util import bytes
-
-from sleekxmpp.stanza import StreamFeatures
-from sleekxmpp.xmlstream import ElementBase, StanzaBase, ET
-from sleekxmpp.xmlstream import register_stanza_plugin
+from sleekxmpp.util import bytes
+from sleekxmpp.xmlstream import StanzaBase
 
 
 class Response(StanzaBase):
@@ -33,7 +30,10 @@ class Response(StanzaBase):
         return base64.b64decode(bytes(self.xml.text))
 
     def set_value(self, values):
-        self.xml.text = bytes(base64.b64encode(values)).decode('utf-8')
+        if values:
+            self.xml.text = bytes(base64.b64encode(values)).decode('utf-8')
+        else:
+            self.xml.text = '='
 
     def del_value(self):
         self.xml.text = ''

sleekxmpp/features/feature_mechanisms/stanza/success.py

@@ -6,10 +6,10 @@
     See the file LICENSE for copying permission.
 """
 
-from sleekxmpp.stanza import StreamFeatures
-from sleekxmpp.xmlstream import ElementBase, StanzaBase, ET
-from sleekxmpp.xmlstream import register_stanza_plugin
+import base64
 
+from sleekxmpp.util import bytes
+from sleekxmpp.xmlstream import StanzaBase
 
 class Success(StanzaBase):
 
@@ -18,9 +18,21 @@ class Success(StanzaBase):
 
     name = 'success'
     namespace = 'urn:ietf:params:xml:ns:xmpp-sasl'
-    interfaces = set()
+    interfaces = set(['value'])
     plugin_attrib = name
 
     def setup(self, xml):
         StanzaBase.setup(self, xml)
         self.xml.tag = self.tag_name()
+
+    def get_value(self):
+        return base64.b64decode(bytes(self.xml.text))
+
+    def set_value(self, values):
+        if values:
+            self.xml.text = bytes(base64.b64encode(values)).decode('utf-8')
+        else:
+            self.xml.text = '='
+
+    def del_value(self):
+        self.xml.text = ''

sleekxmpp/features/feature_preapproval/__init__.py

@@ -0,0 +1,15 @@
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2012  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+from sleekxmpp.plugins.base import register_plugin
+
+from sleekxmpp.features.feature_preapproval.preapproval import FeaturePreApproval
+from sleekxmpp.features.feature_preapproval.stanza import PreApproval
+
+
+register_plugin(FeaturePreApproval)

sleekxmpp/features/feature_preapproval/preapproval.py

@@ -0,0 +1,42 @@
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2012  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+import logging
+
+from sleekxmpp.stanza import Iq, StreamFeatures
+from sleekxmpp.features.feature_preapproval import stanza
+from sleekxmpp.xmlstream import register_stanza_plugin
+from sleekxmpp.plugins.base import BasePlugin
+
+
+log = logging.getLogger(__name__)
+
+
+class FeaturePreApproval(BasePlugin):
+
+    name = 'feature_preapproval'
+    description = 'RFC 6121: Stream Feature: Subscription Pre-Approval'
+    dependences = set()
+    stanza = stanza
+
+    def plugin_init(self):
+        self.xmpp.register_feature('preapproval',
+                self._handle_preapproval,
+                restart=False,
+                order=9001)
+
+        register_stanza_plugin(StreamFeatures, stanza.PreApproval)
+
+    def _handle_preapproval(self, features):
+        """Save notice that the server support subscription pre-approvals.
+
+        Arguments:
+            features -- The stream features stanza.
+        """
+        log.debug("Server supports subscription pre-approvals.")
+        self.xmpp.features.add('preapproval')

sleekxmpp/features/feature_preapproval/stanza.py

@@ -0,0 +1,17 @@
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2012  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+from sleekxmpp.xmlstream import ElementBase
+
+
+class PreApproval(ElementBase):
+
+    name = 'sub'
+    namespace = 'urn:xmpp:features:pre-approval'
+    interfaces = set()
+    plugin_attrib = 'preapproval'

sleekxmpp/features/feature_rosterver/__init__.py

@@ -0,0 +1,19 @@
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2012  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+from sleekxmpp.plugins.base import register_plugin
+
+from sleekxmpp.features.feature_rosterver.rosterver import FeatureRosterVer
+from sleekxmpp.features.feature_rosterver.stanza import RosterVer
+
+
+register_plugin(FeatureRosterVer)
+
+
+# Retain some backwards compatibility
+feature_rosterver = FeatureRosterVer

sleekxmpp/features/feature_rosterver/rosterver.py

@@ -0,0 +1,42 @@
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2012  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+import logging
+
+from sleekxmpp.stanza import Iq, StreamFeatures
+from sleekxmpp.features.feature_rosterver import stanza
+from sleekxmpp.xmlstream import register_stanza_plugin
+from sleekxmpp.plugins.base import BasePlugin
+
+
+log = logging.getLogger(__name__)
+
+
+class FeatureRosterVer(BasePlugin):
+
+    name = 'feature_rosterver'
+    description = 'RFC 6121: Stream Feature: Roster Versioning'
+    dependences = set()
+    stanza = stanza
+
+    def plugin_init(self):
+        self.xmpp.register_feature('rosterver',
+                self._handle_rosterver,
+                restart=False,
+                order=9000)
+
+        register_stanza_plugin(StreamFeatures, stanza.RosterVer)
+
+    def _handle_rosterver(self, features):
+        """Enable using roster versioning.
+
+        Arguments:
+            features -- The stream features stanza.
+        """
+        log.debug("Enabling roster versioning.")
+        self.xmpp.features.add('rosterver')

sleekxmpp/features/feature_rosterver/stanza.py

@@ -0,0 +1,17 @@
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2012  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+from sleekxmpp.xmlstream import ElementBase
+
+
+class RosterVer(ElementBase):
+
+    name = 'ver'
+    namespace = 'urn:xmpp:features:rosterver'
+    interfaces = set()
+    plugin_attrib = 'rosterver'

sleekxmpp/features/feature_session/__init__.py

@@ -6,5 +6,14 @@
     See the file LICENSE for copying permission.
 """
 
-from sleekxmpp.features.feature_session.session import feature_session
+from sleekxmpp.plugins.base import register_plugin
+
+from sleekxmpp.features.feature_session.session import FeatureSession
 from sleekxmpp.features.feature_session.stanza import Session
+
+
+register_plugin(FeatureSession)
+
+
+# Retain some backwards compatibility
+feature_session = FeatureSession

sleekxmpp/features/feature_session/session.py

@@ -10,9 +10,7 @@ import logging
 
 from sleekxmpp.stanza import Iq, StreamFeatures
 from sleekxmpp.xmlstream import register_stanza_plugin
-from sleekxmpp.xmlstream.matcher import *
-from sleekxmpp.xmlstream.handler import *
-from sleekxmpp.plugins.base import base_plugin
+from sleekxmpp.plugins import BasePlugin
 
 from sleekxmpp.features.feature_session import stanza
 
@@ -20,14 +18,14 @@ from sleekxmpp.features.feature_session import stanza
 log = logging.getLogger(__name__)
 
 
-class feature_session(base_plugin):
+class FeatureSession(BasePlugin):
+
+    name = 'feature_session'
+    description = 'RFC 3920: Stream Feature: Start Session'
+    dependencies = set()
+    stanza = stanza
 
     def plugin_init(self):
-        self.name = 'Start Session'
-        self.rfc = '3920'
-        self.description = 'Start Session Stream Feature'
-        self.stanza = stanza
-
         self.xmpp.register_feature('session',
                 self._handle_start_session,
                 restart=False,
@@ -46,7 +44,7 @@ class feature_session(base_plugin):
         iq = self.xmpp.Iq()
         iq['type'] = 'set'
         iq.enable('session')
-        response = iq.send(now=True)
+        iq.send(now=True)
 
         self.xmpp.features.add('session')
 

sleekxmpp/features/feature_session/stanza.py

@@ -6,8 +6,7 @@
     See the file LICENSE for copying permission.
 """
 
-from sleekxmpp.stanza import Iq, StreamFeatures
-from sleekxmpp.xmlstream import ElementBase, ET, register_stanza_plugin
+from sleekxmpp.xmlstream import ElementBase
 
 
 class Session(ElementBase):

sleekxmpp/features/feature_starttls/__init__.py

@@ -6,5 +6,14 @@
     See the file LICENSE for copying permission.
 """
 
-from sleekxmpp.features.feature_starttls.starttls import feature_starttls
+from sleekxmpp.plugins.base import register_plugin
+
+from sleekxmpp.features.feature_starttls.starttls import FeatureSTARTTLS
 from sleekxmpp.features.feature_starttls.stanza import *
+
+
+register_plugin(FeatureSTARTTLS)
+
+
+# Retain some backwards compatibility
+feature_starttls = FeatureSTARTTLS

sleekxmpp/features/feature_starttls/stanza.py

@@ -6,9 +6,7 @@
     See the file LICENSE for copying permission.
 """
 
-from sleekxmpp.stanza import StreamFeatures
 from sleekxmpp.xmlstream import StanzaBase, ElementBase
-from sleekxmpp.xmlstream import register_stanza_plugin
 
 
 class STARTTLS(ElementBase):