Update version and README for 1.0 release.

Fix a typo in several files.

.gitignore

@@ -4,3 +4,5 @@ dist/
 MANIFEST
 docs/_build/
 *.swp
+.tox/
+.coverage

MANIFEST.in

@@ -0,0 +1,6 @@
+include README.rst
+include LICENSE
+include testall.py
+recursive-include docs Makefile *.bat *.py *.rst *.css *.ttf *.png
+recursive-include examples *.py
+recursive-include tests *.py

README.rst

@@ -34,7 +34,8 @@ SleekXMPP's design goals and philosphy are:
 
 Get the Code
 ------------
-.. code-block:: sh
+
+Get the latest stable version from PyPI::
 
     pip install sleekxmpp
 
@@ -43,7 +44,16 @@ 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**
+**Latest Release**
+    - `1.0 <http://github.com/fritzy/SleekXMPP/zipball/1.0>`_
+
+**Develop Releases**
+    - `Latest Develop Version <http://github.com/fritzy/SleekXMPP/zipball/develop>`_
+
+**Older Stable Releases**
+    - `1.0 RC3 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC3>`_  
+    - `1.0 RC2 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC2>`_  
+    - `1.0 RC1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC1>`_  
     - `1.0 Beta6.1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta6.1>`_  
     - `1.0 Beta5 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta5>`_
     - `1.0 Beta4 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta4>`_
@@ -51,9 +61,15 @@ The latest source code for SleekXMPP may be found on `Github
     - `1.0 Beta2 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta2>`_
     - `1.0 Beta1 <http://github.com/fritzy/SleekXMPP/zipball/1.0-Beta1>`_
 
-**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
+install the ``python3`` branch::
 
+    git clone http://github.com/rthalley/dnspython
+    cd dnspython
+    git checkout python3
+    python3 setup.py install
 
 Discussion
 ----------
@@ -68,7 +84,6 @@ help with SleekXMPP.
 
 Documentation and Testing
 -------------------------
-
 Documentation can be found both inline in the code, and as a Sphinx project in ``/docs``.
 To generate the Sphinx documentation, follow the commands below. The HTML output will
 be in ``docs/_build/html``::
@@ -84,7 +99,6 @@ To run the test suite for SleekXMPP::
 
 The SleekXMPP Boilerplate
 -------------------------
-
 Projects using SleekXMPP tend to follow a basic pattern for setting up client/component
 connections and configuration. Here is the gist of the boilerplate needed for a SleekXMPP
 based project. See the documetation or examples directory for more detailed archetypes for
@@ -101,13 +115,21 @@ 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.register_plugin('xep_0030') # Service Discovery
+            self.register_plugin('xep_0199') # XMPP Ping
+
+            # If you are working with an OpenFire server, you will
+            # need to use a different SSL version:
+            # import ssl
+            # self.ssl_version = ssl.PROTOCOL_SSLv3
+
+        def session_start(self, event):
             self.send_presence()
 
-            # Most get_* methods from plugins use Iq stanzas, which
+            # Most get_*/set_* methods from plugins use Iq stanzas, which
             # can generate IqError and IqTimeout exceptions
             try:
                 self.get_roster()
@@ -132,17 +154,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 useuterborg Larsson version:
-        # xmppissl_version = ssl.PROTOCOL_SSLv3
-
-        if xmpp.connect():
-            xmpp.process(block=True)
-        else:
-            print("Unable to connect.")
+        xmpp.connect()
+        xmpp.process(block=True)
 
 
 Credits
@@ -152,8 +165,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

@@ -122,14 +122,14 @@ if __name__ == '__main__':
 	logging.basicConfig(level=opts.loglevel, format='%(levelname)-8s %(message)s')
 
 	#load xml config
-	logging.info("Loading config file: %s" % opts.configfile)
+	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'))
+	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'))
+	logging.info("Account 2 is %s" , config.get('account2', 'jid'))
 	xmpp2 = TestClient(config.get('account2','jid'), config.get('account2','pass'))
 	
 	xmpp1.registerPlugin('xep_0004')

conn_tests/test_pubsubserver.py

@@ -186,14 +186,14 @@ if __name__ == '__main__':
 	logging.basicConfig(level=opts.loglevel, format='%(levelname)-8s %(message)s')
 
 	#load xml config
-	logging.info("Loading config file: %s" % opts.configfile)
+	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'))
+	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'))
+	logging.info("Account 2 is %s" , config.get('account2', 'jid'))
 	xmpp2 = TestClient(config.get('account2','jid'), config.get('account2','pass'))
 	
 	xmpp1.registerPlugin('xep_0004')

conn_tests/testpubsub.py

@@ -329,11 +329,11 @@ if __name__ == '__main__':
 	logging.basicConfig(level=opts.loglevel, format='%(levelname)-8s %(message)s')
 
 	#load xml config
-	logging.info("Loading config file: %s" % opts.configfile)
+	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'])
+	logging.info("Logging in as %s" , config.attrib['jid'])
 	
 	
 	plugin_config = {}

docs/_static/pygments.css

@@ -1,70 +0,0 @@
-.highlight .hll { background-color: #ffffcc }
-.highlight  { background: #000000; color: #f6f3e8; }
-.highlight .c { color: #7C7C7C; } /* Comment */
-.highlight .err { color: #f6f3e8; } /* Error */
-.highlight .g { color: #f6f3e8; } /* Generic */
-.highlight .k { color: #00ADEE; } /* Keyword */
-.highlight .l { color: #f6f3e8; } /* Literal */
-.highlight .n { color: #f6f3e8; } /* Name */
-.highlight .o { color: #f6f3e8; } /* Operator */
-.highlight .x { color: #f6f3e8; } /* Other */
-.highlight .p { color: #f6f3e8; } /* Punctuation */
-.highlight .cm { color: #7C7C7C; } /* Comment.Multiline */
-.highlight .cp { color: #96CBFE; } /* Comment.Preproc */
-.highlight .c1 { color: #7C7C7C; } /* Comment.Single */
-.highlight .cs { color: #7C7C7C; } /* Comment.Special */
-.highlight .gd { color: #f6f3e8; } /* Generic.Deleted */
-.highlight .ge { color: #f6f3e8; } /* Generic.Emph */
-.highlight .gr { color: #ffffff; background-color: #ff0000 } /* Generic.Error */
-.highlight .gh { color: #f6f3e8; font-weight: bold; } /* Generic.Heading */
-.highlight .gi { color: #f6f3e8; } /* Generic.Inserted */
-.highlight .go { color: #070707; } /* Generic.Output */
-.highlight .gp { color: #f6f3e8; } /* Generic.Prompt */
-.highlight .gs { color: #f6f3e8; } /* Generic.Strong */
-.highlight .gu { color: #f6f3e8; font-weight: bold; } /* Generic.Subheading */
-.highlight .gt { color: #ffffff; font-weight: bold; background-color: #FF6C60 } /* Generic.Traceback */
-.highlight .kc { color: #6699CC; } /* Keyword.Constant */
-.highlight .kd { color: #6699CC; } /* Keyword.Declaration */
-.highlight .kn { color: #6699CC; } /* Keyword.Namespace */
-.highlight .kp { color: #6699CC; } /* Keyword.Pseudo */
-.highlight .kr { color: #6699CC; } /* Keyword.Reserved */
-.highlight .kt { color: #FFFFB6; } /* Keyword.Type */
-.highlight .ld { color: #f6f3e8; } /* Literal.Date */
-.highlight .m { color: #FF73FD; } /* Literal.Number */
-.highlight .s { color: #F46DBA;/*#A8FF60;*/ } /* Literal.String */
-.highlight .na { color: #f6f3e8; } /* Name.Attribute */
-.highlight .nb { color: #f6f3e8; } /* Name.Builtin */
-.highlight .nc { color: #f6f3e8; } /* Name.Class */
-.highlight .no { color: #99CC99; } /* Name.Constant */
-.highlight .nd { color: #f6f3e8; } /* Name.Decorator */
-.highlight .ni { color: #E18964; } /* Name.Entity */
-.highlight .ne { color: #f6f3e8; } /* Name.Exception */
-.highlight .nf { color: #F64DBA; } /* Name.Function */
-.highlight .nl { color: #f6f3e8; } /* Name.Label */
-.highlight .nn { color: #f6f3e8; } /* Name.Namespace */
-.highlight .nx { color: #f6f3e8; } /* Name.Other */
-.highlight .py { color: #f6f3e8; } /* Name.Property */
-.highlight .nt { color: #00ADEE; } /* Name.Tag */
-.highlight .nv { color: #C6C5FE; } /* Name.Variable */
-.highlight .ow { color: #ffffff; } /* Operator.Word */
-.highlight .w { color: #f6f3e8; } /* Text.Whitespace */
-.highlight .mf { color: #FF73FD; } /* Literal.Number.Float */
-.highlight .mh { color: #FF73FD; } /* Literal.Number.Hex */
-.highlight .mi { color: #FF73FD; } /* Literal.Number.Integer */
-.highlight .mo { color: #FF73FD; } /* Literal.Number.Oct */
-.highlight .sb { color: #A8FF60; } /* Literal.String.Backtick */
-.highlight .sc { color: #A8FF60; } /* Literal.String.Char */
-.highlight .sd { color: #A8FF60; } /* Literal.String.Doc */
-.highlight .s2 { color: #A8FF60; } /* Literal.String.Double */
-.highlight .se { color: #A8FF60; } /* Literal.String.Escape */
-.highlight .sh { color: #A8FF60; } /* Literal.String.Heredoc */
-.highlight .si { color: #A8FF60; } /* Literal.String.Interpol */
-.highlight .sx { color: #A8FF60; } /* Literal.String.Other */
-.highlight .sr { color: #A8FF60; } /* Literal.String.Regex */
-.highlight .s1 { color: #A8FF60; } /* Literal.String.Single */
-.highlight .ss { color: #A8FF60; } /* Literal.String.Symbol */
-.highlight .bp { color: #f6f3e8; } /* Name.Builtin.Pseudo */
-.highlight .vc { color: #C6C5FE; } /* Name.Variable.Class */
-.highlight .vg { color: #C6C5FE; } /* Name.Variable.Global */
-.highlight .vi { color: #C6C5FE; } /* Name.Variable.Instance */
-.highlight .il { color: #FF73FD; } /* Literal.Number.Integer.Long */

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

@@ -1,69 +0,0 @@
-{#
-    haiku/layout.html
-    ~~~~~~~~~~~~~~~~~
-
-    Sphinx layout template for the haiku theme.
-
-    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-#}
-{% extends "basic/layout.html" %}
-{% set script_files = script_files + ['_static/theme_extras.js'] %}
-{% set css_files = css_files + ['_static/print.css'] %}
-
-{# do not display relbars #}
-{% block relbar1 %}{% endblock %}
-{% block relbar2 %}{% endblock %}
-
-{% macro nav() %}
-        <p>
-        {%- block haikurel1 %}
-        {%- endblock %}
-        {%- if prev %}
-        «&#160;&#160;<a href="{{ prev.link|e }}">{{ prev.title }}</a>
-        &#160;&#160;::&#160;&#160;
-        {%- endif %}
-        <a class="uplink" href="{{ pathto(master_doc) }}">{{ _('Contents') }}</a>
-        {%- if next %}
-        &#160;&#160;::&#160;&#160;
-        <a href="{{ next.link|e }}">{{ next.title }}</a>&#160;&#160;»
-        {%- endif %}
-        {%- block haikurel2 %}
-        {%- endblock %}
-        </p>
-{% endmacro %}
-
-{% block content %}
-      <div class="header">
-        {%- block haikuheader %}
-        {%- if theme_full_logo != "false" %}
-        <a href="{{ pathto('index') }}">
-          <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
-        </a>
-        {%- else %}
-        {%- 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>
-        <h2 class="heading"><span>{{ shorttitle|e }}</span></h2>
-        {%- endif %}
-        {%- endblock %}
-      </div>
-      <div class="topnav">
-      {{ nav() }}
-      </div>
-      <div class="content">
-        {#{%- if display_toc %}
-        <div id="toc">
-          <h3>Table Of Contents</h3>
-          {{ toc }}
-        </div>
-        {%- endif %}#}
-        {% block body %}{% endblock %}
-      </div>
-      <div class="bottomnav">
-      {{ nav() }}
-      </div>
-{% endblock %}

docs/api/basexmpp.rst

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

docs/api/clientxmpp.rst

@@ -1,19 +1,8 @@
 ==========
-clientxmpp
+ClientXMPP
 ==========
 
 .. module:: sleekxmpp.clientxmpp
 
-.. autodata:: SRV_SUPPORT
-
 .. 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.0RC3'
 
 # 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 = []
@@ -91,7 +91,7 @@ pygments_style = 'default'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'haiku'
+html_theme = 'nature'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -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/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/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 RC3 <http://github.com/fritzy/SleekXMPP/zipball/1.0-RC3>`_  
 
     **Develop Releases**
         - `Latest Develop Version <http://github.com/fritzy/SleekXMPP/zipball/develop>`_
@@ -84,8 +79,10 @@ Tutorials, FAQs, and How To Guides
 .. toctree::
     :maxdepth: 1
    
+    faq
     xeps
     xmpp_tdg
+    howto/stanzas
     create_plugin
     features
     sasl
@@ -113,8 +110,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
 ---------------

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
 
@@ -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
 
@@ -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/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/disco_browser.py

@@ -10,7 +10,6 @@
 """
 
 import sys
-import time
 import logging
 import getpass
 from optparse import OptionParser
@@ -61,7 +60,7 @@ 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)
 
@@ -70,7 +69,7 @@ class Disco(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.
 
         In this case, we send disco#info and disco#items
@@ -188,13 +187,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/echo_client.py

@@ -11,7 +11,6 @@
 
 import sys
 import logging
-import time
 import getpass
 from optparse import OptionParser
 
@@ -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:
@@ -132,14 +131,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):
+    reload(sys)
+    sys.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/muc.py

@@ -11,7 +11,7 @@
 
 import sys
 import logging
-import time
+import getpass
 from optparse import OptionParser
 
 import sleekxmpp
@@ -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:
@@ -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
 
@@ -44,7 +43,7 @@ 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)
 
@@ -53,7 +52,7 @@ class PingTest(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 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
 
@@ -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/roster_browser.py

@@ -10,7 +10,6 @@
 """
 
 import sys
-import time
 import logging
 import getpass
 import threading
@@ -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/send_client.py

@@ -11,7 +11,6 @@
 
 import sys
 import logging
-import time
 import getpass
 from optparse import OptionParser
 
@@ -46,7 +45,7 @@ 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)
 
@@ -55,7 +54,7 @@ class SendMsgBot(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:
@@ -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.")

setup.py

@@ -4,16 +4,18 @@
 # Copyright (C) 2007-2011 Nathanael C. Fritz
 # All Rights Reserved
 #
-# This software is licensed as described in the README file,
-# which you should have received as part of this distribution.
-#
+# This software is licensed as described in the README.rst and LICENSE
+# file, which you should have received as part of this distribution.
 
-# from ez_setup import use_setuptools
-from distutils.core import setup
 import sys
+try:
+    from setuptools import setup, Command
+except ImportError:
+    from distutils.core import setup, Command
+# from ez_setup import use_setuptools
 
-import sleekxmpp
-
+from testall import TestCommand
+from sleekxmpp.version import __version__
 # if 'cygwin' in sys.platform.lower():
 #     min_version = '0.6c6'
 # else:
@@ -27,18 +29,18 @@ import sleekxmpp
 #
 # from setuptools import setup, find_packages, Extension, Feature
 
-VERSION          = sleekxmpp.__version__
+VERSION          = __version__
 DESCRIPTION      = 'SleekXMPP is an elegant Python library for XMPP (aka Jabber, Google Talk, etc).'
 with open('README.rst') as readme:
-    LONG_DESCRIPTION = '\n'.join(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',
                    ]
 
@@ -93,5 +95,7 @@ setup(
     license      = 'MIT',
     platforms    = [ 'any' ],
     packages     = packages,
-    requires     = [ 'tlslite', 'pythondns' ],
+    requires     = [ 'dnspython' ],
+    classifiers  = CLASSIFIERS,
+    cmdclass     = {'test': TestCommand}
 )

sleekxmpp/__init__.py

@@ -15,5 +15,4 @@ from sleekxmpp.xmlstream import XMLStream, RestartStream
 from sleekxmpp.xmlstream.matcher import *
 from sleekxmpp.xmlstream.stanzabase import StanzaBase, ET
 
-__version__ = '1.0rc1'
-__version_info__ = (1, 0, 0, 'rc1', 0)
+from sleekxmpp.version import __version__, __version_info__

sleekxmpp/basexmpp.py

@@ -1,9 +1,15 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.basexmpp
+    ~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    This module provides the common XMPP functionality
+    for both clients and components.
+
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 from __future__ import with_statement, unicode_literals
@@ -43,74 +49,59 @@ class BaseXMPP(XMLStream):
     with XMPP. It also provides a plugin mechanism to easily extend
     and add support for new XMPP features.
 
-    Attributes:
-       auto_authorize   -- Manage automatically accepting roster
-                           subscriptions.
-       auto_subscribe   -- Manage automatically requesting mutual
-                           subscriptions.
-       is_component     -- Indicates if this stream is for an XMPP component.
-       jid              -- The XMPP JID for this stream.
-       plugin           -- A dictionary of loaded plugins.
-       plugin_config    -- A dictionary of plugin configurations.
-       plugin_whitelist -- A list of approved plugins.
-       sentpresence     -- Indicates if an initial presence has been sent.
-       roster           -- A dictionary containing subscribed JIDs and
-                           their presence statuses.
-
-    Methods:
-       Iq                      -- Factory for creating an Iq stanzas.
-       Message                 -- Factory for creating Message stanzas.
-       Presence                -- Factory for creating Presence stanzas.
-       get                     -- Return a plugin given its name.
-       make_iq                 -- Create and initialize an Iq stanza.
-       make_iq_error           -- Create an Iq stanza of type 'error'.
-       make_iq_get             -- Create an Iq stanza of type 'get'.
-       make_iq_query           -- Create an Iq stanza with a given query.
-       make_iq_result          -- Create an Iq stanza of type 'result'.
-       make_iq_set             -- Create an Iq stanza of type 'set'.
-       make_message            -- Create and initialize a Message stanza.
-       make_presence           -- Create and initialize a Presence stanza.
-       make_query_roster       -- Create a roster query.
-       process                 -- Overrides XMLStream.process.
-       register_plugin         -- Load and configure a plugin.
-       register_plugins        -- Load and configure multiple plugins.
-       send_message            -- Create and send a Message stanza.
-       send_presence           -- Create and send a Presence stanza.
-       send_presence_subscribe -- Send a subscription request.
+    :param default_ns: Ensure that the correct default XML namespace
+                       is used during initialization.
     """
 
     def __init__(self, jid='', default_ns='jabber:client'):
-        """
-        Adapt an XML stream for use with XMPP.
-
-        Arguments:
-            default_ns -- Ensure that the correct default XML namespace
-                          is used during initialization.
-        """
         XMLStream.__init__(self)
 
-        # To comply with PEP8, method names now use underscores.
-        # Deprecated method names are re-mapped for backwards compatibility.
         self.default_ns = default_ns
         self.stream_ns = 'http://etherx.jabber.org/streams'
         self.namespace_map[self.stream_ns] = 'stream'
 
+        #: An identifier for the stream as given by the server.
+        self.stream_id = None
+
+        #: The JabberID (JID) used by this connection. 
         self.boundjid = JID(jid)
 
+        #: A dictionary mapping plugin names to plugins.
         self.plugin = {}
+
+        #: Configuration options for whitelisted plugins.
+        #: If a plugin is registered without any configuration,
+        #: and there is an entry here, it will be used.
         self.plugin_config = {}
+
+        #: A list of plugins that will be loaded if
+        #: :meth:`register_plugins` is called.
         self.plugin_whitelist = []
 
+        #: The main roster object. This roster supports multiple
+        #: owner JIDs, as in the case for components. For clients
+        #: which only have a single JID, see :attr:`client_roster`.
         self.roster = roster.Roster(self)
         self.roster.add(self.boundjid.bare)
+
+        #: The single roster for the bound JID. This is the
+        #: equivalent of::
+        #:
+        #:     self.roster[self.boundjid.bare]
         self.client_roster = self.roster[self.boundjid.bare]
 
+        #: The distinction between clients and components can be
+        #: important, primarily for choosing how to handle the
+        #: ``'to'`` and ``'from'`` JIDs of stanzas.
         self.is_component = False
-        self.auto_authorize = True
-        self.auto_subscribe = True
 
+        #: Flag indicating that the initial presence broadcast has
+        #: been sent. Until this happens, some servers may not
+        #: behave as expected when sending stanzas.
         self.sentpresence = False
 
+        #: A reference to :mod:`sleekxmpp.stanza` to make accessing
+        #: stanza classes easier.
         self.stanza = sleekxmpp.stanza
 
         self.register_handler(
@@ -164,40 +155,36 @@ class BaseXMPP(XMLStream):
         register_stanza_plugin(Message, HTMLIM)
 
     def start_stream_handler(self, xml):
-        """
-        Save the stream ID once the streams have been established.
+        """Save the stream ID once the streams have been established.
 
-        Overrides XMLStream.start_stream_handler.
-
-        Arguments:
-            xml -- The incoming stream's root element.
+        :param xml: The incoming stream's root element.
         """
         self.stream_id = xml.get('id', '')
 
     def process(self, *args, **kwargs):
-        """
-        Overrides XMLStream.process.
-
-        Initialize the XML streams and begin processing events.
+        """Initialize plugins and begin processing the XML stream.
 
         The number of threads used for processing stream events is determined
-        by HANDLER_THREADS.
+        by :data:`HANDLER_THREADS`.
 
-        Arguments:
-            block -- If block=False then event dispatcher will run
-                     in a separate thread, allowing for the stream to be
-                     used in the background for another application.
-                     Otherwise, process(block=True) blocks the current thread.
-                     Defaults to False.
+        :param bool block: If ``False``, then event dispatcher will run
+                    in a separate thread, allowing for the stream to be
+                    used in the background for another application.
+                    Otherwise, ``process(block=True)`` blocks the current
+                    thread. Defaults to ``False``.
+        :param bool threaded: **DEPRECATED**
+                    If ``True``, then event dispatcher will run
+                    in a separate thread, allowing for the stream to be
+                    used in the background for another application.
+                    Defaults to ``True``. This does **not** mean that no
+                    threads are used at all if ``threaded=False``.
 
-            **threaded is deprecated and included for API compatibility**
-            threaded -- If threaded=True then event dispatcher will run
-                        in a separate thread, allowing for the stream to be
-                        used in the background for another application.
-                        Defaults to True.
+        Regardless of these threading options, these threads will 
+        always exist:
 
-            Event handlers and the send queue will be threaded
-            regardless of these parameters.
+        - The event queue processor
+        - The send queue processor
+        - The scheduler
         """
         for name in self.plugin:
             if not self.plugin[name].post_inited:
@@ -205,15 +192,13 @@ class BaseXMPP(XMLStream):
         return XMLStream.process(self, *args, **kwargs)
 
     def register_plugin(self, plugin, pconfig={}, module=None):
-        """
-        Register and configure  a plugin for use in this stream.
+        """Register and configure  a plugin for use in this stream.
 
-        Arguments:
-            plugin  -- The name of the plugin class. Plugin names must
+        :param plugin: The name of the plugin class. Plugin names must
                        be unique.
-            pconfig -- A dictionary of configuration data for the plugin.
-                       Defaults to an empty dictionary.
-            module  -- Optional refence to the module containing the plugin
+        :param pconfig: A dictionary of configuration data for the plugin.
+                        Defaults to an empty dictionary.
+        :param module: Optional refence to the module containing the plugin
                        class if using custom plugins.
         """
         try:
@@ -242,25 +227,24 @@ class BaseXMPP(XMLStream):
             self.plugin[plugin] = getattr(module, plugin)(self, pconfig)
 
             # Let XEP/RFC implementing plugins have some extra logging info.
-            spec = '(CUSTOM) '
+            spec = '(CUSTOM) %s'
             if self.plugin[plugin].xep:
                 spec = "(XEP-%s) " % self.plugin[plugin].xep
             elif self.plugin[plugin].rfc:
                 spec = "(RFC-%s) " % self.plugin[plugin].rfc
 
             desc = (spec, self.plugin[plugin].description)
-            log.debug("Loaded Plugin %s%s" % desc)
+            log.debug("Loaded Plugin %s %s" % desc)
         except:
             log.exception("Unable to load plugin: %s", plugin)
 
     def register_plugins(self):
-        """
-        Register and initialize all built-in plugins.
+        """Register and initialize all built-in plugins.
 
         Optionally, the list of plugins loaded may be limited to those
-        contained in self.plugin_whitelist.
+        contained in :attr:`plugin_whitelist`.
 
-        Plugin configurations stored in self.plugin_config will be used.
+        Plugin configurations stored in :attr:`plugin_config` will be used.
         """
         if self.plugin_whitelist:
             plugin_list = self.plugin_whitelist
@@ -279,19 +263,15 @@ class BaseXMPP(XMLStream):
             self.plugin[plugin].post_init()
 
     def __getitem__(self, key):
-        """
-        Return a plugin given its name, if it has been registered.
-        """
+        """Return a plugin given its name, if it has been registered."""
         if key in self.plugin:
             return self.plugin[key]
         else:
-            log.warning("""Plugin "%s" is not loaded.""" % key)
+            log.warning("Plugin '%s' is not loaded.", key)
             return False
 
     def get(self, key, default):
-        """
-        Return a plugin given its name, if it has been registered.
-        """
+        """Return a plugin given its name, if it has been registered."""
         return self.plugin.get(key, default)
 
     def Message(self, *args, **kwargs):
@@ -307,16 +287,18 @@ class BaseXMPP(XMLStream):
         return Presence(self, *args, **kwargs)
 
     def make_iq(self, id=0, ifrom=None, ito=None, itype=None, iquery=None):
-        """
-        Create a new Iq stanza with a given Id and from JID.
+        """Create a new Iq stanza with a given Id and from JID.
 
-        Arguments:
-            id     -- An ideally unique ID value for this stanza thread.
-                      Defaults to 0.
-            ifrom  -- The from JID to use for this stanza.
-            ito    -- The destination JID for this stanza.
-            itype  -- The Iq's type, one of: get, set, result, or error.
-            iquery -- Optional namespace for adding a query element.
+        :param id: An ideally unique ID value for this stanza thread.
+                   Defaults to 0.
+        :param ifrom: The from :class:`~sleekxmpp.xmlstream.jid.JID` 
+                      to use for this stanza.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param itype: The :class:`~sleekxmpp.stanza.iq.Iq`'s type, 
+                      one of: ``'get'``, ``'set'``, ``'result'``,
+                      or ``'error'``.
+        :param iquery: Optional namespace for adding a query element.
         """
         iq = self.Iq()
         iq['id'] = str(id)
@@ -327,17 +309,17 @@ class BaseXMPP(XMLStream):
         return iq
 
     def make_iq_get(self, queryxmlns=None, ito=None, ifrom=None, iq=None):
-        """
-        Create an Iq stanza of type 'get'.
+        """Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type ``'get'``.
 
         Optionally, a query element may be added.
 
-        Arguments:
-            queryxmlns -- The namespace of the query to use.
-            ito        -- The destination JID for this stanza.
-            ifrom      -- The from JID to use for this stanza.
-            iq         -- Optionally use an existing stanza instead
-                          of generating a new one.
+        :param queryxmlns: The namespace of the query to use.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
+                      to use for this stanza.
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
         """
         if not iq:
             iq = self.Iq()
@@ -351,14 +333,16 @@ class BaseXMPP(XMLStream):
 
     def make_iq_result(self, id=None, ito=None, ifrom=None, iq=None):
         """
-        Create an Iq stanza of type 'result' with the given ID value.
+        Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type 
+        ``'result'`` with the given ID value.
 
-        Arguments:
-            id    -- An ideally unique ID value. May use self.new_id().
-            ito   -- The destination JID for this stanza.
-            ifrom -- The from JID to use for this stanza.
-            iq    -- Optionally use an existing stanza instead
-                     of generating a new one.
+        :param id: An ideally unique ID value. May use :meth:`new_id()`.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
+                      to use for this stanza.
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
         """
         if not iq:
             iq = self.Iq()
@@ -374,17 +358,22 @@ class BaseXMPP(XMLStream):
 
     def make_iq_set(self, sub=None, ito=None, ifrom=None, iq=None):
         """
-        Create an Iq stanza of type 'set'.
+        Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type ``'set'``.
 
         Optionally, a substanza may be given to use as the
         stanza's payload.
 
-        Arguments:
-            sub   -- A stanza or XML object to use as the Iq's payload.
-            ito   -- The destination JID for this stanza.
-            ifrom -- The from JID to use for this stanza.
-            iq    -- Optionally use an existing stanza instead
-                     of generating a new one.
+        :param sub: Either an 
+                    :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                    stanza object or an
+                    :class:`~xml.etree.ElementTree.Element` XML object 
+                    to use as the :class:`~sleekxmpp.stanza.iq.Iq`'s payload.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
+                      to use for this stanza.
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
         """
         if not iq:
             iq = self.Iq()
@@ -401,19 +390,20 @@ class BaseXMPP(XMLStream):
                       condition='feature-not-implemented',
                       text=None, ito=None, ifrom=None, iq=None):
         """
-        Create an Iq stanza of type 'error'.
+        Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type ``'error'``.
 
-        Arguments:
-            id        -- An ideally unique ID value. May use self.new_id().
-            type      -- The type of the error, such as 'cancel' or 'modify'.
-                         Defaults to 'cancel'.
-            condition -- The error condition.
-                         Defaults to 'feature-not-implemented'.
-            text      -- A message describing the cause of the error.
-            ito       -- The destination JID for this stanza.
-            ifrom     -- The from JID to use for this stanza.
-            iq        -- Optionally use an existing stanza instead
-                         of generating a new one.
+        :param id: An ideally unique ID value. May use :meth:`new_id()`.
+        :param type: The type of the error, such as ``'cancel'`` or 
+                     ``'modify'``. Defaults to ``'cancel'``.
+        :param condition: The error condition. Defaults to 
+                          ``'feature-not-implemented'``.
+        :param text: A message describing the cause of the error.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
+                      to use for this stanza.
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
         """
         if not iq:
             iq = self.Iq()
@@ -429,15 +419,16 @@ class BaseXMPP(XMLStream):
 
     def make_iq_query(self, iq=None, xmlns='', ito=None, ifrom=None):
         """
-        Create or modify an Iq stanza to use the given
-        query namespace.
+        Create or modify an :class:`~sleekxmpp.stanza.iq.Iq` stanza 
+        to use the given query namespace.
 
-        Arguments:
-            iq    -- Optional Iq stanza to modify. A new
-                     stanza is created otherwise.
-            xmlns -- The query's namespace.
-            ito   -- The destination JID for this stanza.
-            ifrom -- The from JID to use for this stanza.
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
+        :param xmlns: The query's namespace.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
+                      to use for this stanza.
         """
         if not iq:
             iq = self.Iq()
@@ -449,12 +440,10 @@ class BaseXMPP(XMLStream):
         return iq
 
     def make_query_roster(self, iq=None):
-        """
-        Create a roster query element.
+        """Create a roster query element.
 
-        Arguments:
-            iq -- Optional Iq stanza to modify. A new stanza
-                  is created otherwise.
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
         """
         if iq:
             iq['query'] = 'jabber:iq:roster'
@@ -463,18 +452,19 @@ class BaseXMPP(XMLStream):
     def make_message(self, mto, mbody=None, msubject=None, mtype=None,
                      mhtml=None, mfrom=None, mnick=None):
         """
-        Create and initialize a new Message stanza.
+        Create and initialize a new 
+        :class:`~sleekxmpp.stanza.message.Message` stanza.
 
-        Arguments:
-            mto      -- The recipient of the message.
-            mbody    -- The main contents of the message.
-            msubject -- Optional subject for the message.
-            mtype    -- The message's type, such as 'chat' or 'groupchat'.
-            mhtml    -- Optional HTML body content.
-            mfrom    -- The sender of the message. if sending from a client,
-                        be aware that some servers require that the full JID
-                        of the sender be used.
-            mnick    -- Optional nickname of the sender.
+        :param mto: The recipient of the message.
+        :param mbody: The main contents of the message.
+        :param msubject: Optional subject for the message.
+        :param mtype: The message's type, such as ``'chat'`` or
+                      ``'groupchat'``.
+        :param mhtml: Optional HTML body content in the form of a string.
+        :param mfrom: The sender of the message. if sending from a client,
+                      be aware that some servers require that the full JID
+                      of the sender be used.
+        :param mnick: Optional nickname of the sender.
         """
         message = self.Message(sto=mto, stype=mtype, sfrom=mfrom)
         message['body'] = mbody
@@ -488,16 +478,16 @@ class BaseXMPP(XMLStream):
     def make_presence(self, pshow=None, pstatus=None, ppriority=None,
                       pto=None, ptype=None, pfrom=None, pnick=None):
         """
-        Create and initialize a new Presence stanza.
+        Create and initialize a new 
+        :class:`~sleekxmpp.stanza.presence.Presence` stanza.
 
-        Arguments:
-            pshow     -- The presence's show value.
-            pstatus   -- The presence's status message.
-            ppriority -- This connections' priority.
-            pto       -- The recipient of a directed presence.
-            ptype     -- The type of presence, such as 'subscribe'.
-            pfrom     -- The sender of the presence.
-            pnick     -- Optional nickname of the presence's sender.
+        :param pshow: The presence's show value.
+        :param pstatus: The presence's status message.
+        :param ppriority: This connection's priority.
+        :param pto: The recipient of a directed presence.
+        :param ptype: The type of presence, such as ``'subscribe'``.
+        :param pfrom: The sender of the presence.
+        :param pnick: Optional nickname of the presence's sender.
         """
         presence = self.Presence(stype=ptype, sfrom=pfrom, sto=pto)
         if pshow is not None:
@@ -512,18 +502,19 @@ class BaseXMPP(XMLStream):
     def send_message(self, mto, mbody, msubject=None, mtype=None,
                      mhtml=None, mfrom=None, mnick=None):
         """
-        Create, initialize, and send a Message stanza.
+        Create, initialize, and send a new 
+        :class:`~sleekxmpp.stanza.message.Message` stanza.
 
-        Arguments:
-            mto      -- The recipient of the message.
-            mbody    -- The main contents of the message.
-            msubject -- Optional subject for the message.
-            mtype    -- The message's type, such as 'chat' or 'groupchat'.
-            mhtml    -- Optional HTML body content.
-            mfrom    -- The sender of the message. if sending from a client,
-                        be aware that some servers require that the full JID
-                        of the sender be used.
-            mnick    -- Optional nickname of the sender.
+        :param mto: The recipient of the message.
+        :param mbody: The main contents of the message.
+        :param msubject: Optional subject for the message.
+        :param mtype: The message's type, such as ``'chat'`` or
+                      ``'groupchat'``.
+        :param mhtml: Optional HTML body content in the form of a string.
+        :param mfrom: The sender of the message. if sending from a client,
+                      be aware that some servers require that the full JID
+                      of the sender be used.
+        :param mnick: Optional nickname of the sender.
         """
         self.make_message(mto, mbody, msubject, mtype,
                           mhtml, mfrom, mnick).send()
@@ -531,16 +522,16 @@ class BaseXMPP(XMLStream):
     def send_presence(self, pshow=None, pstatus=None, ppriority=None,
                       pto=None, pfrom=None, ptype=None, pnick=None):
         """
-        Create, initialize, and send a Presence stanza.
+        Create, initialize, and send a new 
+        :class:`~sleekxmpp.stanza.presence.Presence` stanza.
 
-        Arguments:
-            pshow     -- The presence's show value.
-            pstatus   -- The presence's status message.
-            ppriority -- This connections' priority.
-            pto       -- The recipient of a directed presence.
-            ptype     -- The type of presence, such as 'subscribe'.
-            pfrom     -- The sender of the presence.
-            pnick     -- Optional nickname of the presence's sender.
+        :param pshow: The presence's show value.
+        :param pstatus: The presence's status message.
+        :param ppriority: This connection's priority.
+        :param pto: The recipient of a directed presence.
+        :param ptype: The type of presence, such as ``'subscribe'``.
+        :param pfrom: The sender of the presence.
+        :param pnick: Optional nickname of the presence's sender.
         """
         # Python2.6 chokes on Unicode strings for dict keys.
         args = {str('pto'): pto,
@@ -558,13 +549,14 @@ class BaseXMPP(XMLStream):
     def send_presence_subscription(self, pto, pfrom=None,
                                    ptype='subscribe', pnick=None):
         """
-        Create, initialize, and send a Presence stanza of type 'subscribe'.
+        Create, initialize, and send a new 
+        :class:`~sleekxmpp.stanza.presence.Presence` stanza of
+        type ``'subscribe'``.
 
-        Arguments:
-            pto   -- The recipient of a directed presence.
-            pfrom -- The sender of the presence.
-            ptype -- The type of presence. Defaults to 'subscribe'.
-            pnick -- Nickname of the presence's sender.
+        :param pto: The recipient of a directed presence.
+        :param pfrom: The sender of the presence.
+        :param ptype: The type of presence, such as ``'subscribe'``.
+        :param pnick: Optional nickname of the presence's sender.
         """
         presence = self.makePresence(ptype=ptype,
                                      pfrom=pfrom,
@@ -577,9 +569,7 @@ class BaseXMPP(XMLStream):
 
     @property
     def jid(self):
-        """
-        Attribute accessor for bare jid
-        """
+        """Attribute accessor for bare jid"""
         log.warning("jid property deprecated. Use boundjid.bare")
         return self.boundjid.bare
 
@@ -590,9 +580,7 @@ class BaseXMPP(XMLStream):
 
     @property
     def fulljid(self):
-        """
-        Attribute accessor for full jid
-        """
+        """Attribute accessor for full jid"""
         log.warning("fulljid property deprecated. Use boundjid.full")
         return self.boundjid.full
 
@@ -603,9 +591,7 @@ class BaseXMPP(XMLStream):
 
     @property
     def resource(self):
-        """
-        Attribute accessor for jid resource
-        """
+        """Attribute accessor for jid resource"""
         log.warning("resource property deprecated. Use boundjid.resource")
         return self.boundjid.resource
 
@@ -616,9 +602,7 @@ class BaseXMPP(XMLStream):
 
     @property
     def username(self):
-        """
-        Attribute accessor for jid usernode
-        """
+        """Attribute accessor for jid usernode"""
         log.warning("username property deprecated. Use boundjid.user")
         return self.boundjid.user
 
@@ -629,9 +613,7 @@ class BaseXMPP(XMLStream):
 
     @property
     def server(self):
-        """
-        Attribute accessor for jid host
-        """
+        """Attribute accessor for jid host"""
         log.warning("server property deprecated. Use boundjid.host")
         return self.boundjid.server
 
@@ -640,9 +622,35 @@ class BaseXMPP(XMLStream):
         log.warning("server property deprecated. Use boundjid.host")
         self.boundjid.server = value
 
+    @property
+    def auto_authorize(self):
+        """Auto accept or deny subscription requests.
+
+        If ``True``, auto accept subscription requests.
+        If ``False``, auto deny subscription requests.
+        If ``None``, don't automatically respond.
+        """
+        return self.roster.auto_authorize
+
+    @auto_authorize.setter
+    def auto_authorize(self, value):
+        self.roster.auto_authorize = value
+
+    @property
+    def auto_subscribe(self):
+        """Auto send requests for mutual subscriptions.
+
+        If ``True``, auto send mutual subscription requests.
+        """
+        return self.roster.auto_subscribe
+
+    @auto_subscribe.setter
+    def auto_subscribe(self, value):
+        self.roster.auto_subscribe = value
+
     def set_jid(self, jid):
         """Rip a JID apart and claim it as our own."""
-        log.debug("setting jid to %s" % jid)
+        log.debug("setting jid to %s", jid)
         self.boundjid.full = jid
 
     def getjidresource(self, fulljid):
@@ -676,17 +684,16 @@ class BaseXMPP(XMLStream):
         self.roster[pto][pfrom].handle_unavailable(presence)
 
     def _handle_new_subscription(self, stanza):
-        """
-        Attempt to automatically handle subscription requests.
+        """Attempt to automatically handle subscription requests.
 
         Subscriptions will be approved if the request is from
-        a whitelisted JID, of self.auto_authorize is True. They
-        will be rejected if self.auto_authorize is False. Setting
-        self.auto_authorize to None will disable automatic
+        a whitelisted JID, of :attr:`auto_authorize` is True. They
+        will be rejected if :attr:`auto_authorize` is False. Setting
+        :attr:`auto_authorize` to ``None`` will disable automatic
         subscription handling (except for whitelisted JIDs).
 
         If a subscription is accepted, a request for a mutual
-        subscription will be sent if self.auto_subscribe is True.
+        subscription will be sent if :attr:`auto_subscribe` is ``True``.
         """
         roster = self.roster[stanza['to'].bare]
         item = self.roster[stanza['to'].bare][stanza['from'].bare]
@@ -725,8 +732,7 @@ class BaseXMPP(XMLStream):
         self.roster[pto][pfrom].handle_unsubscribed(presence)
 
     def _handle_presence(self, presence):
-        """
-        Process incoming presence stanzas.
+        """Process incoming presence stanzas.
 
         Update the roster with presence information.
         """
@@ -741,26 +747,21 @@ class BaseXMPP(XMLStream):
              not presence['type'] in presence.showtypes:
             return
 
-        self.event("changed_status", presence)
-
     def exception(self, exception):
-        """
-        Process any uncaught exceptions, notably IqError and
-        IqTimeout exceptions.
+        """Process any uncaught exceptions, notably 
+        :class:`~sleekxmpp.exceptions.IqError` and
+        :class:`~sleekxmpp.exceptions.IqTimeout` exceptions.
 
-        Overrides XMLStream.exception.
-
-        Arguments:
-            exception -- An unhandled exception object.
+        :param exception: An unhandled :class:`Exception` object.
         """
         if isinstance(exception, IqError):
             iq = exception.iq
-            log.error('%s: %s' % (iq['error']['condition'],
-                                  iq['error']['text']))
+            log.error('%s: %s', iq['error']['condition'],
+                                iq['error']['text'])
             log.warning('You should catch IqError exceptions')
         elif isinstance(exception, IqTimeout):
             iq = exception.iq
-            log.error('Request timed out: %s' % iq)
+            log.error('Request timed out: %s', iq)
             log.warning('You should catch IqTimeout exceptions')
         else:
             log.exception(exception)

sleekxmpp/clientxmpp.py

@@ -1,9 +1,15 @@
+# -*- 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
@@ -41,37 +47,30 @@ 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.
-        """
+                 plugin_whitelist=[], escape_quotes=True, sasl_mech=None):
         BaseXMPP.__init__(self, jid, 'jabber:client')
 
         self.set_jid(jid)
@@ -114,40 +113,40 @@ class ClientXMPP(BaseXMPP):
 
         # 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_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.
+    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:
             address = (self.boundjid.host, 5222)
 
         return XMLStream.connect(self, address[0], address[1],
-                                 use_tls=use_tls, reattempt=reattempt)
+                                 use_tls=use_tls, use_ssl=use_ssl,
+                                 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.
+        """Get the DNS records for a domain, including SRV records.
 
-        Arguments:
-            domain -- The domain in question.
-            port   -- If the results don't include a port, use this one.
+        :param domain: The domain in question.
+        :param port: If the results don't include a port, use this one.
         """
         if port is None:
             port = self.default_port
@@ -159,11 +158,11 @@ class ClientXMPP(BaseXMPP):
                     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)
+                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)
+                            "for SRV record of %s", domain)
                 answers = super(ClientXMPP, self).get_dns_records(domain, port)
             return answers
         else:
@@ -172,17 +171,15 @@ class ClientXMPP(BaseXMPP):
             return [((domain, port), 0, 0)]
 
     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))
@@ -190,53 +187,51 @@ class ClientXMPP(BaseXMPP):
 
     def update_roster(self, jid, name=None, subscription=None, groups=[],
                             block=True, timeout=None, callback=None):
-        """
-        Add or change a roster item.
+        """Add or change a roster item.
 
-        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.
+        :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,
+        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.
+        
+        This is done by setting its subscription status to ``'remove'``.
 
-        Arguments:
-            jid -- The JID of the item 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'
@@ -254,19 +249,10 @@ class ClientXMPP(BaseXMPP):
         self.bindfail = False
         self.features = set()
 
-        def session_timeout():
-            if not self.session_started_event.isSet():
-                log.debug("Session start has taken more than 15 seconds")
-                self.disconnect(reconnect=self.auto_reconnect)
-
-        self.schedule("session timeout checker", 15, session_timeout)
-
     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']:
@@ -277,13 +263,12 @@ class ClientXMPP(BaseXMPP):
                     return True
 
     def _handle_roster(self, iq, request=False):
-        """
-        Update the roster after receiving a roster stanza.
+        """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.
+        :param request: Indicates if this stanza is a response
+                        to a request for the roster, and not an
+                        empty acknowledgement from the server.
         """
         if iq['type'] == 'set' or (iq['type'] == 'result' and request):
             for jid in iq['roster']['items']:

sleekxmpp/componentxmpp.py

@@ -1,9 +1,15 @@
+# -*- 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
@@ -32,28 +38,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 +81,42 @@ 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=True, 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
+        log.debug("Connecting to %s:%s", host, port)
+        return XMLStream.connect(self, host=host, port=port,
+                                       use_ssl=use_ssl,
+                                       use_tls=use_tls,
+                                       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 +133,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,11 +149,9 @@ 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_started_event.set()
         self.event("session_start")

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,6 +69,8 @@ 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 +86,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/feature_bind/bind.py

@@ -42,7 +42,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')
@@ -55,7 +55,7 @@ class feature_bind(base_plugin):
 
         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_mechanisms/mechanisms.py

@@ -123,7 +123,7 @@ class feature_mechanisms(base_plugin):
 
     def _handle_fail(self, stanza):
         """SASL authentication failed. Disconnect and shutdown."""
-        log.info("Authentication failed: %s" % stanza['condition'])
+        log.info("Authentication failed: %s", stanza['condition'])
         self.xmpp.event("failed_auth", stanza, direct=True)
         self.xmpp.disconnect()
         return True

sleekxmpp/features/feature_starttls/starttls.py

@@ -58,8 +58,8 @@ class feature_starttls(base_plugin):
             self.xmpp.send(features['starttls'], now=True)
             return True
         else:
-            log.warning("The module tlslite is required to log in" +\
-                            " to some servers, and has not been found.")
+            log.warning("The module tlslite is required to log in" + \
+                        " to some servers, and has not been found.")
             return False
 
     def _handle_starttls_proceed(self, proceed):

sleekxmpp/plugins/gmail_notify.py

@@ -121,7 +121,7 @@ class gmail_notify(base.base_plugin):
     def handle_gmail(self, iq):
         mailbox = iq['mailbox']
         approx = ' approximately' if mailbox['estimated'] else ''
-        log.info('Gmail: Received%s %s emails' % (approx, mailbox['total-matched']))
+        log.info('Gmail: Received%s %s emails', approx, mailbox['total-matched'])
         self.last_result_time = mailbox['result-time']
         self.xmpp.event('gmail_messages', iq)
 
@@ -140,7 +140,7 @@ class gmail_notify(base.base_plugin):
         if query is None:
             log.info("Gmail: Checking for new emails")
         else:
-            log.info('Gmail: Searching for emails matching: "%s"' % query)
+            log.info('Gmail: Searching for emails matching: "%s"', query)
         iq = self.xmpp.Iq()
         iq['type'] = 'get'
         iq['to'] = self.xmpp.boundjid.bare

sleekxmpp/plugins/jobs.py

@@ -43,7 +43,7 @@ class jobs(base.base_plugin):
 		iq['psstate']['payload'] = state
 		result = iq.send()
 		if result is None or type(result) == bool or result['type'] != 'result':
-			log.error("Unable to change %s:%s to %s" % (node, jobid, state))
+			log.error("Unable to change %s:%s to %s", node, jobid, state)
 			return False
 		return True
 

sleekxmpp/plugins/xep_0004/stanza/form.py

@@ -96,11 +96,11 @@ class Form(ElementBase):
         self.xml.append(itemXML)
         reported_vars = self['reported'].keys()
         for var in reported_vars:
-            fieldXML = ET.Element('{%s}field' % FormField.namespace)
-            itemXML.append(fieldXML)
-            field = FormField(xml=fieldXML)
+            field = FormField()
+            field._type = self['reported'][var]['type']
             field['var'] = var
             field['value'] = values.get(var, None)
+            itemXML.append(field.xml)
 
     def add_reported(self, var, ftype=None, label='', desc='', **kwargs):
         kwtype = kwargs.get('type', None)
@@ -159,7 +159,7 @@ class Form(ElementBase):
         items = []
         itemsXML = self.xml.findall('{%s}item' % self.namespace)
         for itemXML in itemsXML:
-            item = {}
+            item = OrderedDict()
             fieldsXML = itemXML.findall('{%s}field' % FormField.namespace)
             for fieldXML in fieldsXML:
                 field = FormField(xml=fieldXML)
@@ -168,7 +168,7 @@ class Form(ElementBase):
         return items
 
     def get_reported(self):
-        fields = {}
+        fields = OrderedDict()
         xml = self.xml.findall('{%s}reported/{%s}field' % (self.namespace,
                                      FormField.namespace))
         for field in xml:
@@ -177,7 +177,7 @@ class Form(ElementBase):
         return fields
 
     def get_values(self):
-        values = {}
+        values = OrderedDict()
         fields = self['fields']
         for var in fields:
             values[var] = fields[var]['value']

sleekxmpp/plugins/xep_0009/binding.py

@@ -42,46 +42,46 @@ def py2xml(*args):
 
 def _py2xml(*args):
     for x in args:
-        val = ET.Element("value")
+        val = ET.Element("{%s}value" % _namespace)
         if x is None:
-            nil = ET.Element("nil")
+            nil = ET.Element("{%s}nil" % _namespace)
             val.append(nil)
         elif type(x) is int:
-            i4 = ET.Element("i4")
+            i4 = ET.Element("{%s}i4" % _namespace)
             i4.text = str(x)
             val.append(i4)
         elif type(x) is bool:
-            boolean = ET.Element("boolean")
+            boolean = ET.Element("{%s}boolean" % _namespace)
             boolean.text = str(int(x))
             val.append(boolean)
         elif type(x) is str:
-            string = ET.Element("string")
+            string = ET.Element("{%s}string" % _namespace)
             string.text = x
             val.append(string)
         elif type(x) is float:
-            double = ET.Element("double")
+            double = ET.Element("{%s}double" % _namespace)
             double.text = str(x)
             val.append(double)
         elif type(x) is rpcbase64:
-            b64 = ET.Element("Base64")
+            b64 = ET.Element("{%s}base64" % _namespace)
             b64.text = x.encoded()
             val.append(b64)
         elif type(x) is rpctime:
-            iso = ET.Element("dateTime.iso8601")
+            iso = ET.Element("{%s}dateTime.iso8601" % _namespace)
             iso.text = str(x)
             val.append(iso)
         elif type(x) in (list, tuple):
-            array = ET.Element("array")
-            data = ET.Element("data")
+            array = ET.Element("{%s}array" % _namespace)
+            data = ET.Element("{%s}data" % _namespace)
             for y in x:
                 data.append(_py2xml(y))
             array.append(data)
             val.append(array)
         elif type(x) is dict:
-            struct = ET.Element("struct")
+            struct = ET.Element("{%s}struct" % _namespace)
             for y in x.keys():
-                member = ET.Element("member")
-                name = ET.Element("name")
+                member = ET.Element("{%s}member" % _namespace)
+                name = ET.Element("{%s}name" % _namespace)
                 name.text = y
                 member.append(name)
                 member.append(_py2xml(x[y]))
@@ -105,15 +105,18 @@ def _xml2py(value):
     if value.find('{%s}int' % namespace) is not None:
         return int(value.find('{%s}int' % namespace).text)
     if value.find('{%s}boolean' % namespace) is not None:
-        return bool(value.find('{%s}boolean' % namespace).text)
+        return bool(int(value.find('{%s}boolean' % namespace).text))
     if value.find('{%s}string' % namespace) is not None:
         return value.find('{%s}string' % namespace).text
     if value.find('{%s}double' % namespace) is not None:
         return float(value.find('{%s}double' % namespace).text)
-    if value.find('{%s}Base64') is not None:
-        return rpcbase64(value.find('Base64' % namespace).text)
-    if value.find('{%s}dateTime.iso8601') is not None:
-        return rpctime(value.find('{%s}dateTime.iso8601'))
+    if value.find('{%s}base64' % namespace) is not None:
+        return rpcbase64(value.find('{%s}base64' % namespace).text.encode())
+    if value.find('{%s}Base64' % namespace) is not None:
+        # Older versions of XEP-0009 used Base64
+        return rpcbase64(value.find('{%s}Base64' % namespace).text.encode())
+    if value.find('{%s}dateTime.iso8601' % namespace) is not None:
+        return rpctime(value.find('{%s}dateTime.iso8601' % namespace).text)
     if value.find('{%s}struct' % namespace) is not None:
         struct = {}
         for member in value.find('{%s}struct' % namespace).findall('{%s}member' % namespace):
@@ -135,13 +138,13 @@ class rpcbase64(object):
         self.data = data
 
     def decode(self):
-        return base64.decodestring(self.data)
+        return base64.b64decode(self.data)
 
     def __str__(self):
-        return self.decode()
+        return self.decode().decode()
 
     def encoded(self):
-        return self.data
+        return self.data.decode()
 
 
 

sleekxmpp/plugins/xep_0009/remote.py

@@ -20,7 +20,7 @@ log = logging.getLogger(__name__)
 
 def _intercept(method, name, public):
     def _resolver(instance, *args, **kwargs):
-        log.debug("Locally calling %s.%s with arguments %s." % (instance.FQN(), method.__name__, args))
+        log.debug("Locally calling %s.%s with arguments %s.", instance.FQN(), method.__name__, args)
         try:
             value = method(instance, *args, **kwargs)
             if value == NotImplemented:
@@ -113,6 +113,9 @@ class ACL:
     def check(cls, rules, jid, resource):
         if rules is None:
             return cls.DENY                  # No rules means no access!
+        jid = str(jid)     # Check the string representation of the JID.
+        if not jid:
+            return cls.DENY                  # Can't check an empty JID.
         for rule in rules:
             policy = cls._check(rule, jid, resource)
             if policy is not None:
@@ -381,7 +384,7 @@ class Proxy(Endpoint):
                 try:
                     if attribute._rpc:
                         def _remote_call(*args, **kwargs):
-                            log.debug("Remotely calling '%s.%s' with arguments %s." % (self._endpoint.FQN(), attribute._rpc_name, args))
+                            log.debug("Remotely calling '%s.%s' with arguments %s.", self._endpoint.FQN(), attribute._rpc_name, args)
                             return self._endpoint.session._call_remote(self._endpoint.target_jid, "%s.%s" % (self._endpoint.FQN(), attribute._rpc_name), self._callback, *args, **kwargs)
                         return _remote_call
                 except:
@@ -449,7 +452,7 @@ class RemoteSession(object):
         self._event.wait()
 
     def _notify(self, event):
-        log.debug("RPC Session as %s started." % self._client.boundjid.full)
+        log.debug("RPC Session as %s started.", self._client.boundjid.full)
         self._client.sendPresence()
         self._event.set()
         pass
@@ -461,7 +464,7 @@ class RemoteSession(object):
         if name is None:
             name = method.__name__
         key = "%s.%s" % (endpoint, name)
-        log.debug("Registering call handler for %s (%s)." % (key, method))
+        log.debug("Registering call handler for %s (%s).", key, method)
         with self._lock:
             if key in self._entries:
                 raise KeyError("A handler for %s has already been regisered!" % endpoint)
@@ -469,7 +472,7 @@ class RemoteSession(object):
         return key
 
     def _register_acl(self, endpoint, acl):
-        log.debug("Registering ACL %s for endpoint %s." % (repr(acl), endpoint))
+        log.debug("Registering ACL %s for endpoint %s.", repr(acl), endpoint)
         with self._lock:
             self._acls[endpoint] = acl
 
@@ -562,7 +565,7 @@ class RemoteSession(object):
             iq.send()
             return future.get_value(30)
         else:
-            log.debug("[RemoteSession] _call_remote %s" % callback)
+            log.debug("[RemoteSession] _call_remote %s", callback)
             self._register_callback(pid, callback)
             iq.send()
 
@@ -601,11 +604,11 @@ class RemoteSession(object):
             error.send()
         except Exception as e:
             if isinstance(e, KeyError):
-                log.error("No handler available for %s!" % pmethod)
+                log.error("No handler available for %s!", pmethod)
                 error = self._client.plugin['xep_0009']._item_not_found(iq)
             else:
                 traceback.print_exc(file=sys.stderr)
-                log.error("An unexpected problem occurred invoking method %s!" % pmethod)
+                log.error("An unexpected problem occurred invoking method %s!", pmethod)
                 error = self._client.plugin['xep_0009']._undefined_condition(iq)
             #! print "[REMOTE.PY] _handle_remote_procedure_call AN ERROR SHOULD BE SENT NOW %s " % e
             error.send()
@@ -699,10 +702,10 @@ class Remote(object):
             with Remote._lock:
                 del cls._sessions[client.boundjid.bare]
         result = RemoteSession(client, _session_close_callback)
-        client.plugin['xep_0009'].xmpp.add_event_handler('jabber_rpc_method_call', result._on_jabber_rpc_method_call)
-        client.plugin['xep_0009'].xmpp.add_event_handler('jabber_rpc_method_response', result._on_jabber_rpc_method_response)
-        client.plugin['xep_0009'].xmpp.add_event_handler('jabber_rpc_method_fault', result._on_jabber_rpc_method_fault)
-        client.plugin['xep_0009'].xmpp.add_event_handler('jabber_rpc_error', result._on_jabber_rpc_error)
+        client.plugin['xep_0009'].xmpp.add_event_handler('jabber_rpc_method_call', result._on_jabber_rpc_method_call, threaded=True)
+        client.plugin['xep_0009'].xmpp.add_event_handler('jabber_rpc_method_response', result._on_jabber_rpc_method_response, threaded=True)
+        client.plugin['xep_0009'].xmpp.add_event_handler('jabber_rpc_method_fault', result._on_jabber_rpc_method_fault, threaded=True)
+        client.plugin['xep_0009'].xmpp.add_event_handler('jabber_rpc_error', result._on_jabber_rpc_error, threaded=True)
         if callback is None:
             start_event_handler = result._notify
         else:

sleekxmpp/plugins/xep_0009/rpc.py

@@ -128,22 +128,22 @@ class xep_0009(base.base_plugin):
     def _handle_method_call(self, iq):
         type = iq['type']
         if type == 'set':
-            log.debug("Incoming Jabber-RPC call from %s" % iq['from'])
+            log.debug("Incoming Jabber-RPC call from %s", iq['from'])
             self.xmpp.event('jabber_rpc_method_call', iq)
         else:
             if type == 'error' and ['rpc_query'] is None:
                 self.handle_error(iq)
             else:
-                log.debug("Incoming Jabber-RPC error from %s" % iq['from'])
+                log.debug("Incoming Jabber-RPC error from %s", iq['from'])
                 self.xmpp.event('jabber_rpc_error', iq)
 
     def _handle_method_response(self, iq):
         if iq['rpc_query']['method_response']['fault'] is not None:
-            log.debug("Incoming Jabber-RPC fault from %s" % iq['from'])
+            log.debug("Incoming Jabber-RPC fault from %s", iq['from'])
             #self._on_jabber_rpc_method_fault(iq)
             self.xmpp.event('jabber_rpc_method_fault', iq)
         else:
-            log.debug("Incoming Jabber-RPC response from %s" % iq['from'])
+            log.debug("Incoming Jabber-RPC response from %s", iq['from'])
             self.xmpp.event('jabber_rpc_method_response', iq)
 
     def _handle_error(self, iq):

sleekxmpp/plugins/xep_0012.py

@@ -71,10 +71,10 @@ class xep_0012(base.base_plugin):
 
     def handle_last_activity_query(self, iq):
         if iq['type'] == 'get':
-            log.debug("Last activity requested by %s" % iq['from'])
+            log.debug("Last activity requested by %s", iq['from'])
             self.xmpp.event('last_activity_request', iq)
         elif iq['type'] == 'result':
-            log.debug("Last activity result from %s" % iq['from'])
+            log.debug("Last activity result from %s", iq['from'])
             self.xmpp.event('last_activity', iq)
 
     def handle_last_activity(self, iq):

sleekxmpp/plugins/xep_0030/disco.py

@@ -268,7 +268,7 @@ class xep_0030(base_plugin):
         """
         if local or jid is None:
             log.debug("Looking up local disco#info data " + \
-                      "for %s, node %s." % (jid, node))
+                      "for %s, node %s.", jid, node)
             info = self._run_node_handler('get_info', jid, node, kwargs)
             return self._fix_default_info(info)
 
@@ -542,7 +542,7 @@ class xep_0030(base_plugin):
         """
         if iq['type'] == 'get':
             log.debug("Received disco info query from " + \
-                      "<%s> to <%s>." % (iq['from'], iq['to']))
+                      "<%s> to <%s>.", iq['from'], iq['to'])
             if self.xmpp.is_component:
                 jid = iq['to'].full
             else:
@@ -551,14 +551,17 @@ class xep_0030(base_plugin):
                                           jid,
                                           iq['disco_info']['node'],
                                           iq)
-            iq.reply()
-            if info:
-                info = self._fix_default_info(info)
-                iq.set_payload(info.xml)
-            iq.send()
+            if isinstance(info, Iq):
+                info.send()
+            else:
+                iq.reply()
+                if info:
+                    info = self._fix_default_info(info)
+                    iq.set_payload(info.xml)
+                iq.send()
         elif iq['type'] == 'result':
             log.debug("Received disco info result from" + \
-                      "%s to %s." % (iq['from'], iq['to']))
+                      "%s to %s.", iq['from'], iq['to'])
             self.xmpp.event('disco_info', iq)
 
     def _handle_disco_items(self, iq):
@@ -572,21 +575,25 @@ class xep_0030(base_plugin):
         """
         if iq['type'] == 'get':
             log.debug("Received disco items query from " + \
-                      "<%s> to <%s>." % (iq['from'], iq['to']))
+                      "<%s> to <%s>.", iq['from'], iq['to'])
             if self.xmpp.is_component:
                 jid = iq['to'].full
             else:
                 jid = iq['to'].bare
             items = self._run_node_handler('get_items',
                                           jid,
-                                          iq['disco_items']['node'])
-            iq.reply()
-            if items:
-                iq.set_payload(items.xml)
-            iq.send()
+                                          iq['disco_items']['node'],
+                                          iq)
+            if isinstance(items, Iq):
+                items.send()
+            else:
+                iq.reply()
+                if items:
+                    iq.set_payload(items.xml)
+                iq.send()
         elif iq['type'] == 'result':
             log.debug("Received disco items result from" + \
-                      "%s to %s." % (iq['from'], iq['to']))
+                      "%s to %s.", iq['from'], iq['to'])
             self.xmpp.event('disco_items', iq)
 
     def _fix_default_info(self, info):

sleekxmpp/plugins/xep_0045.py

@@ -14,6 +14,7 @@ from .. stanza.presence import Presence
 from .. xmlstream.handler.callback import Callback
 from .. xmlstream.matcher.xpath import MatchXPath
 from .. xmlstream.matcher.xmlmask import MatchXMLMask
+from sleekxmpp.exceptions import IqError, IqTimeout
 
 
 log = logging.getLogger(__name__)
@@ -126,7 +127,7 @@ class xep_0045(base.base_plugin):
     def handle_groupchat_invite(self, inv):
         """ Handle an invite into a muc.
         """
-        logging.debug("MUC invite to %s from %s: %s" % (inv['from'], inv["from"], inv))
+        logging.debug("MUC invite to %s from %s: %s", inv['from'], inv["from"], inv)
         if inv['from'] not in self.rooms.keys():
             self.xmpp.event("groupchat_invite", inv)
 
@@ -148,7 +149,7 @@ class xep_0045(base.base_plugin):
             if entry['nick'] not in self.rooms[entry['room']]:
                 got_online = True
             self.rooms[entry['room']][entry['nick']] = entry
-        log.debug("MUC presence from %s/%s : %s" % (entry['room'],entry['nick'], entry))
+        log.debug("MUC presence from %s/%s : %s", entry['room'],entry['nick'], entry)
         self.xmpp.event("groupchat_presence", pr)
         self.xmpp.event("muc::%s::presence" % entry['room'], pr)
         if got_offline:
@@ -222,10 +223,10 @@ class xep_0045(base.base_plugin):
             return False
         return True
 
-    def joinMUC(self, room, nick, maxhistory="0", password='', wait=False, pstatus=None, pshow=None):
+    def joinMUC(self, room, nick, maxhistory="0", password='', wait=False, pstatus=None, pshow=None, pfrom=None):
         """ Join the specified room, requesting 'maxhistory' lines of history.
         """
-        stanza = self.xmpp.makePresence(pto="%s/%s" % (room, nick), pstatus=pstatus, pshow=pshow)
+        stanza = self.xmpp.makePresence(pto="%s/%s" % (room, nick), pstatus=pstatus, pshow=pshow, pfrom=pfrom)
         x = ET.Element('{http://jabber.org/protocol/muc}x')
         if password:
             passelement = ET.Element('password')
@@ -271,7 +272,7 @@ class xep_0045(base.base_plugin):
             return False
         return True
 
-    def setAffiliation(self, room, jid=None, nick=None, affiliation='member'):
+    def setAffiliation(self, room, jid=None, nick=None, affiliation='member', ifrom=None):
         """ Change room affiliation."""
         if affiliation not in ('outcast', 'member', 'admin', 'owner', 'none'):
             raise TypeError
@@ -283,6 +284,7 @@ class xep_0045(base.base_plugin):
         query.append(item)
         iq = self.xmpp.makeIqSet(query)
         iq['to'] = room
+        iq['from'] = ifrom
         # For now, swallow errors to preserve existing API
         try:
             result = iq.send()
@@ -306,13 +308,13 @@ class xep_0045(base.base_plugin):
         msg.append(x)
         self.xmpp.send(msg)
 
-    def leaveMUC(self, room, nick, msg=''):
+    def leaveMUC(self, room, nick, msg='', pfrom=None):
         """ Leave the specified room.
         """
         if msg:
-            self.xmpp.sendPresence(pshow='unavailable', pto="%s/%s" % (room, nick), pstatus=msg)
+            self.xmpp.sendPresence(pshow='unavailable', pto="%s/%s" % (room, nick), pstatus=msg, pfrom=pfrom)
         else:
-            self.xmpp.sendPresence(pshow='unavailable', pto="%s/%s" % (room, nick))
+            self.xmpp.sendPresence(pshow='unavailable', pto="%s/%s" % (room, nick), pfrom=pfrom)
         del self.rooms[room]
 
     def getRoomConfig(self, room, ifrom=''):
@@ -331,12 +333,13 @@ class xep_0045(base.base_plugin):
             raise ValueError
         return self.xmpp.plugin['xep_0004'].buildForm(form)
 
-    def cancelConfig(self, room):
+    def cancelConfig(self, room, ifrom=None):
         query = ET.Element('{http://jabber.org/protocol/muc#owner}query')
         x = ET.Element('{jabber:x:data}x', type='cancel')
         query.append(x)
         iq = self.xmpp.makeIqSet(query)
         iq['to'] = room
+        iq['from'] = ifrom
         iq.send()
 
     def setRoomConfig(self, room, config, ifrom=''):

sleekxmpp/plugins/xep_0050/adhoc.py

@@ -17,6 +17,7 @@ from sleekxmpp.xmlstream import register_stanza_plugin, JID
 from sleekxmpp.plugins.base import base_plugin
 from sleekxmpp.plugins.xep_0050 import stanza
 from sleekxmpp.plugins.xep_0050 import Command
+from sleekxmpp.plugins.xep_0004 import Form
 
 
 log = logging.getLogger(__name__)
@@ -92,7 +93,8 @@ class xep_0050(base_plugin):
                          StanzaPath('iq@type=set/command'),
                          self._handle_command))
 
-        register_stanza_plugin(Iq, stanza.Command)
+        register_stanza_plugin(Iq, Command)
+        register_stanza_plugin(Command, Form)
 
         self.xmpp.add_event_handler('command_execute',
                                     self._handle_command_start,
@@ -147,7 +149,7 @@ class xep_0050(base_plugin):
         Access control may be implemented in the provided handler.
 
         Command workflow is done across a sequence of command handlers. The
-        first handler is given the intial Iq stanza of the request in order
+        first handler is given the initial Iq stanza of the request in order
         to support access control. Subsequent handlers are given only the
         payload items of the command. All handlers will receive the command's
         session data.
@@ -211,8 +213,7 @@ class xep_0050(base_plugin):
         key = (iq['to'].full, node)
         name, handler = self.commands.get(key, ('Not found', None))
         if not handler:
-            log.debug('Command not found: %s, %s' % (key, self.commands))
-
+            log.debug('Command not found: %s, %s', key, self.commands)
         initial_session = {'id': sessionid,
                            'from': iq['from'],
                            'to': iq['to'],
@@ -431,8 +432,7 @@ class xep_0050(base_plugin):
         iq = self.xmpp.Iq()
         iq['type'] = 'set'
         iq['to'] = jid
-        if ifrom:
-            iq['from'] = ifrom
+        iq['from'] = ifrom
         iq['command']['node'] = node
         iq['command']['action'] = action
         if sessionid is not None:
@@ -482,9 +482,8 @@ class xep_0050(base_plugin):
         iq = self.xmpp.Iq()
         iq['type'] = 'set'
         iq['to'] = jid
-        if ifrom:
-            iq['from'] = ifrom
-            session['from'] = ifrom
+        iq['from'] = ifrom
+        session['from'] = ifrom
         iq['command']['node'] = node
         iq['command']['action'] = 'execute'
         sessionid = 'client:pending_' + iq['id']

sleekxmpp/plugins/xep_0060/pubsub.py

@@ -1,16 +1,23 @@
-from __future__ import with_statement
-from sleekxmpp.plugins import base
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2011  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
 import logging
-#from xml.etree import cElementTree as ET
-from sleekxmpp.xmlstream.stanzabase import registerStanzaPlugin, ElementBase, ET
+
+from sleekxmpp.xmlstream import JID
+from sleekxmpp.plugins.base import base_plugin
 from sleekxmpp.plugins.xep_0060 import stanza
-from sleekxmpp.plugins.xep_0004 import Form
 
 
 log = logging.getLogger(__name__)
 
 
-class xep_0060(base.base_plugin):
+class xep_0060(base_plugin):
+
     """
     XEP-0060 Publish Subscribe
     """
@@ -18,111 +25,426 @@ class xep_0060(base.base_plugin):
     def plugin_init(self):
         self.xep = '0060'
         self.description = 'Publish-Subscribe'
+        self.stanza = stanza
 
-    def create_node(self, jid, node, config=None, ntype=None):
-        iq = IQ(sto=jid, stype='set', sfrom=self.xmpp.jid)
+    def create_node(self, jid, node, config=None, ntype=None, ifrom=None,
+                    block=True, callback=None, timeout=None):
+        """
+        Create and configure a new pubsub node.
+
+        A server MAY use a different name for the node than the one provided,
+        so be sure to check the result stanza for a server assigned name.
+
+        If no configuration form is provided, the node will be created using
+        the server's default configuration. To get the default configuration
+        use get_node_config().
+
+        Arguments:
+            jid      -- The JID of the pubsub service.
+            node     -- Optional name of the node to create. If no name is
+                        provided, the server MAY generate a node ID for you.
+                        The server can also assign a different name than the
+                        one you provide; check the result stanza to see if
+                        the server assigned a name.
+            config   -- Optional XEP-0004 data form of configuration settings.
+            ntype    -- The type of node to create. Servers typically default
+                        to using 'leaf' if no type is provided.
+            ifrom    -- Specify the sender's JID.
+            block    -- Specify if the send call 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 exiting the send call if blocking is used.
+                        Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+            callback -- Optional reference to a stream handler function. Will
+                        be executed when a reply stanza is received.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
         iq['pubsub']['create']['node'] = node
-        if ntype is None:
-            ntype = 'leaf'
+
         if config is not None:
-            if 'FORM_TYPE' in submitform.field:
-                config.field['FORM_TYPE'].setValue('http://jabber.org/protocol/pubsub#node_config')
+            form_type = 'http://jabber.org/protocol/pubsub#node_config'
+            if 'FORM_TYPE' in config['fields']:
+                config.field['FORM_TYPE']['value'] = form_type
             else:
-                config.addField('FORM_TYPE', 'hidden', value='http://jabber.org/protocol/pubsub#node_config')
-            if 'pubsub#node_type' in submitform.field:
-                config.field['pubsub#node_type'].setValue(ntype)
-            else:
-                config.addField('pubsub#node_type', value=ntype)
-            iq['pubsub']['configure']['form'] = config
-        return iq.send()
+                config.add_field(var='FORM_TYPE',
+                                 ftype='hidden',
+                                 value=form_type)
+            if ntype:
+                if 'pubsub#node_type' in config['fields']:
+                    config.field['pubsub#node_type']['value'] = ntype
+                else:
+                    config.add_field(var='pubsub#node_type', value=ntype)
+            iq['pubsub']['configure'].append(config)
 
-    def subscribe(self, jid, node, bare=True, subscribee=None):
-        iq = IQ(sto=jid, sfrom=self.xmpp.jid, stype='set')
+        return iq.send(block=block, callback=callback, timeout=timeout)
+
+    def subscribe(self, jid, node, bare=True, subscribee=None, options=None,
+                  ifrom=None, block=True, callback=None, timeout=None):
+        """
+        Subscribe to updates from a pubsub node.
+
+        The rules for determining the JID that is subscribing to the node are:
+            1. If subscribee is given, use that as provided.
+            2. If ifrom was given, use the bare or full version based on bare.
+            3. Otherwise, use self.xmpp.boundjid based on bare.
+
+        Arguments:
+            jid        -- The pubsub service JID.
+            node       -- The node to subscribe to.
+            bare       -- Indicates if the subscribee is a bare or full JID.
+                          Defaults to True for a bare JID.
+            subscribee -- The JID that is subscribing to the node.
+            options    --
+            ifrom      -- Specify the sender's JID.
+            block      -- Specify if the send call 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 exiting the send call if blocking is used.
+                          Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+            callback   -- Optional reference to a stream handler function. Will
+                          be executed when a reply stanza is received.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
         iq['pubsub']['subscribe']['node'] = node
-        if subscribee is None:
-            if bare:
-                iq['pubsub']['subscribe']['jid'] = self.xmpp.jid.bare
-            else:
-                iq['pubsub']['subscribe']['jid'] = self.xmpp.jid.full
-        else:
-            iq['pubsub']['subscribe']['jid'] = subscribee
-        return iq.send()
 
-    def unsubscribe(self, jid, node, subid=None, bare=True, subscribee=None):
-        iq = IQ(sto=jid, sfrom=self.xmpp.jid, stype='set')
+        if subscribee is None:
+            if ifrom:
+                if bare:
+                    subscribee = JID(ifrom).bare
+                else:
+                    subscribee = ifrom
+            else:
+                if bare:
+                    subscribee = self.xmpp.boundjid.bare
+                else:
+                    subscribee = self.xmpp.boundjid
+
+        iq['pubsub']['subscribe']['jid'] = subscribee
+        if options is not None:
+            iq['pubsub']['options'].append(options)
+        return iq.send(block=block, callback=callback, timeout=timeout)
+
+    def unsubscribe(self, jid, node, subid=None, bare=True, subscribee=None,
+                    ifrom=None, block=True, callback=None, timeout=None):
+        """
+        Unubscribe from updates from a pubsub node.
+
+        The rules for determining the JID that is unsubscribing
+        from the node are:
+            1. If subscribee is given, use that as provided.
+            2. If ifrom was given, use the bare or full version based on bare.
+            3. Otherwise, use self.xmpp.boundjid based on bare.
+
+        Arguments:
+            jid        -- The pubsub service JID.
+            node       -- The node to subscribe to.
+            subid      -- The specific subscription, if multiple subscriptions
+                          exist for this JID/node combination.
+            bare       -- Indicates if the subscribee is a bare or full JID.
+                          Defaults to True for a bare JID.
+            subscribee -- The JID that is subscribing to the node.
+            ifrom      -- Specify the sender's JID.
+            block      -- Specify if the send call 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 exiting the send call if blocking is used.
+                          Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+            callback   -- Optional reference to a stream handler function. Will
+                          be executed when a reply stanza is received.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
         iq['pubsub']['unsubscribe']['node'] = node
-        if subscribee is None:
-            if bare:
-                iq['pubsub']['unsubscribe']['jid'] = self.xmpp.jid.bare
-            else:
-                iq['pubsub']['unsubscribe']['jid'] = self.xmpp.jid.full
-        else:
-            iq['pubsub']['unsubscribe']['jid'] = subscribee
-        if subid is not None:
-            iq['pubsub']['unsubscribe']['subid'] = subid
-        return iq.send()
 
-    def get_node_config(self, jid, node=None): # if no node, then grab default
-        iq = IQ(sto=jid, sfrom=self.xmpp.jid, stype='get')
+        if subscribee is None:
+            if ifrom:
+                if bare:
+                    subscribee = JID(ifrom).bare
+                else:
+                    subscribee = ifrom
+            else:
+                if bare:
+                    subscribee = self.xmpp.boundjid.bare
+                else:
+                    subscribee = self.xmpp.boundjid
+
+        iq['pubsub']['unsubscribe']['jid'] = subscribee
+        iq['pubsub']['unsubscribe']['subid'] = subid
+        return iq.send(block=block, callback=callback, timeout=timeout)
+
+    def get_subscriptions(self, jid, node=None, ifrom=None, block=True,
+                          callback=None, timeout=None):
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
+        iq['pubsub']['subscriptions']['node'] = node
+        return iq.send(block=block, callback=callback, timeout=timeout)
+
+    def get_affiliations(self, jid, node=None, ifrom=None, block=True,
+                         callback=None, timeout=None):
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
+        iq['pubsub']['affiliations']['node'] = node
+        return iq.send(block=block, callback=callback, timeout=timeout)
+
+    def get_subscription_options(self, jid, node=None, user_jid=None, ifrom=None,
+                                 block=True, callback=None, timeout=None):
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
+        if user_jid is None:
+            iq['pubsub']['default']['node'] = node
+        else:
+            iq['pubsub']['options']['node'] = node
+            iq['pubsub']['options']['jid'] = user_jid
+        return iq.send(block=block, callback=callback, timeout=timeout)
+
+    def set_subscription_options(self, jid, node, user_jid, options,
+                                 ifrom=None, block=True, callback=None,
+                                 timeout=None):
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
+        iq['pubsub']['options']['node'] = node
+        iq['pubsub']['options']['jid'] = user_jid
+        iq['pubsub']['options'].append(options)
+        return iq.send(block=block, callback=callback, timeout=timeout)
+
+    def get_node_config(self, jid, node=None, ifrom=None, block=True,
+                        callback=None, timeout=None):
+        """
+        Retrieve the configuration for a node, or the pubsub service's
+        default configuration for new nodes.
+
+        Arguments:
+            jid      -- The JID of the pubsub service.
+            node     -- The node to retrieve the configuration for. If None,
+                        the default configuration for new nodes will be
+                        requested. Defaults to None.
+            ifrom    -- Specify the sender's JID.
+            block    -- Specify if the send call 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 exiting the send call if blocking is used.
+                        Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+            callback -- Optional reference to a stream handler function. Will
+                        be executed when a reply stanza is received.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
         if node is None:
             iq['pubsub_owner']['default']
         else:
             iq['pubsub_owner']['configure']['node'] = node
-        return iq.send()
+        return iq.send(block=block, callback=callback, timeout=timeout)
 
-    def get_node_subscriptions(self, jid, node):
-        iq = IQ(sto=jid, sfrom=self.xmpp.jid, stype='get')
+    def get_node_subscriptions(self, jid, node, ifrom=None, block=True,
+                               callback=None, timeout=None):
+        """
+        Retrieve the subscriptions associated with a given node.
+
+        Arguments:
+            jid      -- The JID of the pubsub service.
+            node     -- The node to retrieve subscriptions from.
+            ifrom    -- Specify the sender's JID.
+            block    -- Specify if the send call 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 exiting the send call if blocking is used.
+                        Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+            callback -- Optional reference to a stream handler function. Will
+                        be executed when a reply stanza is received.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
         iq['pubsub_owner']['subscriptions']['node'] = node
-        return iq.send()
+        return iq.send(block=block, callback=callback, timeout=timeout)
 
-    def get_node_affiliations(self, jid, node):
-        iq = IQ(sto=jid, sfrom=self.xmpp.jid, stype='get')
+    def get_node_affiliations(self, jid, node, ifrom=None, block=True,
+                              callback=None, timeout=None):
+        """
+        Retrieve the affiliations associated with a given node.
+
+        Arguments:
+            jid      -- The JID of the pubsub service.
+            node     -- The node to retrieve affiliations from.
+            ifrom    -- Specify the sender's JID.
+            block    -- Specify if the send call 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 exiting the send call if blocking is used.
+                        Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+            callback -- Optional reference to a stream handler function. Will
+                        be executed when a reply stanza is received.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
         iq['pubsub_owner']['affiliations']['node'] = node
-        return iq.send()
+        return iq.send(block=block, callback=callback, timeout=timeout)
 
-    def delete_node(self, jid, node):
-        iq = IQ(sto=jid, sfrom=self.xmpp.jid, stype='get')
+    def delete_node(self, jid, node, ifrom=None, block=True,
+                    callback=None, timeout=None):
+        """
+        Delete a a pubsub node.
+
+        Arguments:
+            jid      -- The JID of the pubsub service.
+            node     -- The node to delete.
+            ifrom    -- Specify the sender's JID.
+            block    -- Specify if the send call 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 exiting the send call if blocking is used.
+                        Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+            callback -- Optional reference to a stream handler function. Will
+                        be executed when a reply stanza is received.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
         iq['pubsub_owner']['delete']['node'] = node
-        return iq.send()
+        return iq.send(block=block, callback=callback, timeout=timeout)
 
-    def set_node_config(self, jid, node, config):
-        iq = IQ(sto=jid, sfrom=self.xmpp.jid, stype='set')
+    def set_node_config(self, jid, node, config, ifrom=None, block=True,
+                        callback=None, timeout=None):
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
         iq['pubsub_owner']['configure']['node'] = node
-        iq['pubsub_owner']['configure']['config'] = config
-        return iq.send()
+        iq['pubsub_owner']['configure']['form'].values = config.values
+        return iq.send(block=block, callback=callback, timeout=timeout)
 
-    def publish(self, jid, node, items=[]):
-        iq = IQ(sto=jid, sfrom=self.xmpp.jid, stype='set')
+    def publish(self, jid, node, id=None, payload=None, options=None,
+                ifrom=None, block=True, callback=None, timeout=None):
+        """
+        Add a new item to a node, or edit an existing item.
+
+        For services that support it, you can use the publish command
+        as an event signal by not including an ID or payload.
+
+        When including a payload and you do not provide an ID then
+        the service will generally create an ID for you.
+
+        Publish options may be specified, and how those options
+        are processed is left to the service, such as treating
+        the options as preconditions that the node's settings
+        must match.
+
+        Arguments:
+            jid      -- The JID of the pubsub service.
+            node     -- The node to publish the item to.
+            id       -- Optionally specify the ID of the item.
+            payload  -- The item content to publish.
+            options  -- A form of publish options.
+            ifrom    -- Specify the sender's JID.
+            block    -- Specify if the send call 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 exiting the send call if blocking is used.
+                        Defaults to sleekxmpp.xmlstream.RESPONSE_TIMEOUT
+            callback -- Optional reference to a stream handler function. Will
+                        be executed when a reply stanza is received.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
         iq['pubsub']['publish']['node'] = node
-        for id, payload in items:
-            item = stanza.pubsub.Item()
-            if id is not None:
-                item['id'] = id
-            item['payload'] = payload
-            iq['pubsub']['publish'].append(item)
-        return iq.send()
+        if id is not None:
+            iq['pubsub']['publish']['item']['id'] = id
+        if payload is not None:
+            iq['pubsub']['publish']['item']['payload'] = payload
+        iq['pubsub']['publish_options'] = options
+        return iq.send(block=block, callback=callback, timeout=timeout)
+
+    def retract(self, jid, node, id, notify=None, ifrom=None, block=True,
+                callback=None, timeout=None):
+        """
+        Delete a single item from a node.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
 
-    def retract(self, jid, node, item):
-        iq = IQ(sto=jid, sfrom=self.xmpp.jid, stype='set')
         iq['pubsub']['retract']['node'] = node
-        item = stanza.pubsub.Item()
-        item['id'] = item
-        iq['pubsub']['retract'].append(item)
-        return iq.send()
+        iq['pubsub']['retract']['notify'] = notify
+        iq['pubsub']['retract']['item']['id'] = id
+        return iq.send(block=block, callback=callback, timeout=timeout)
 
-    def get_nodes(self, jid):
-        return self.xmpp.plugin['xep_0030'].get_items(jid)
+    def purge(self, jid, node, ifrom=None, block=True, callback=None,
+              timeout=None):
+        """
+        Remove all items from a node.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
+        iq['pubsub_owner']['purge']['node'] = node
+        return iq.send(block=block, callback=callback, timeout=timeout)
 
-    def getItems(self, jid, node):
-        return self.xmpp.plugin['xep_0030'].get_items(jid, node)
+    def get_nodes(self, *args, **kwargs):
+        """
+        Discover the nodes provided by a Pubsub service, using disco.
+        """
+        return self.xmpp.plugin['xep_0030'].get_items(*args, **kwargs)
 
-    def modify_affiliation(self, jid, node, affiliation, user_jid=None):
-        iq = IQ(sto=jid, sfrom=self.xmpp.jid, stype='set')
-        iq['pubsub_owner']['affiliations']
-        aff = stanza.pubsub.Affiliation()
-        aff['node'] = node
-        if user_jid is not None:
-            aff['jid'] = user_jid
-        aff['affiliation'] = affiliation
-        iq['pubsub_owner']['affiliations'].append(aff)
-        return iq.send()
+    def get_item(self, jid, node, item_id, ifrom=None, block=True,
+                 callback=None, timeout=None):
+        """
+        Retrieve the content of an individual item.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
+        item = self.stanza.Item()
+        item['id'] = item_id
+        iq['pubsub']['items']['node'] = node
+        iq['pubsub']['items'].append(item)
+        return iq.send(block=block, callback=callback, timeout=timeout)
+
+    def get_items(self, jid, node, item_ids=None, max_items=None,
+                  iterator=False, ifrom=None, block=False,
+                  callback=None, timeout=None):
+        """
+        Request the contents of a node's items.
+
+        The desired items can be specified, or a query for the last
+        few published items can be used.
+
+        Pubsub services may use result set management for nodes with
+        many items, so an iterator can be returned if needed.
+        """
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='get')
+        iq['pubsub']['items']['node'] = node
+        iq['pubsub']['items']['max_items'] = max_items
+
+        if item_ids is not None:
+            for item_id in item_ids:
+                item = self.stanza.Item()
+                item['id'] = item_id
+                iq['pubsub']['items'].append(item)
+
+        if iterator:
+            return self.xmpp['xep_0059'].iterate(iq, 'pubsub')
+        else:
+            return iq.send(block=block, callback=callback, timeout=timeout)
+
+    def get_item_ids(self, jid, node, ifrom=None, block=True,
+                     callback=None, timeout=None, iterator=False):
+        """
+        Retrieve the ItemIDs hosted by a given node, using disco.
+        """
+        return self.xmpp.plugin['xep_0030'].get_items(jid, node,
+                                                      ifrom=ifrom,
+                                                      block=block,
+                                                      callback=callback,
+                                                      timeout=timeout,
+                                                      iterator=iterator)
+
+    def modify_affiliations(self, jid, node, affiliations=None, ifrom=None,
+                            block=True, callback=None, timeout=None):
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
+        iq['pubsub_owner']['affiliations']['node'] = node
+
+        if affiliations is None:
+            affiliations = []
+
+        for jid, affiliation in affiliations:
+            aff = self.stanza.OwnerAffiliation()
+            aff['jid'] = jid
+            aff['affiliation'] = affiliation
+            iq['pubsub_owner']['affiliations'].append(aff)
+
+        return iq.send(block=block, callback=callback, timeout=timeout)
+
+    def modify_subscriptions(self, jid, node, subscriptions=None, ifrom=None,
+                             block=True, callback=None, timeout=None):
+        iq = self.xmpp.Iq(sto=jid, sfrom=ifrom, stype='set')
+        iq['pubsub_owner']['subscriptions']['node'] = node
+
+        if subscriptions is None:
+            subscriptions = []
+
+        for jid, subscription in subscriptions:
+            sub = self.stanza.OwnerSubscription()
+            sub['jid'] = jid
+            sub['subscription'] = subscription
+            iq['pubsub_owner']['subscriptions'].append(sub)
+
+        return iq.send(block=block, callback=callback, timeout=timeout)

sleekxmpp/plugins/xep_0060/stanza/__init__.py

@@ -1,3 +1,12 @@
-from sleekxmpp.plugins.xep_0060.stanza.pubsub import Pubsub, Affiliation, Affiliations, Subscription, Subscriptions, SubscribeOptions, Item, Items, Create, Publish, Retract, Unsubscribe, Subscribe, Configure, Options, PubsubState, PubsubStateEvent
-from sleekxmpp.plugins.xep_0060.stanza.pubsub_owner import PubsubOwner, DefaultConfig, OwnerAffiliations, OwnerAffiliation, OwnerConfigure, OwnerDefault, OwnerDelete, OwnerPurge, OwnerRedirect, OwnerSubscriptions, OwnerSubscription
-from sleekxmpp.plugins.xep_0060.stanza.pubsub_event import Event, EventItem, EventRetract, EventItems, EventCollection, EventAssociate, EventDisassociate, EventConfiguration, EventPurge, EventSubscription
+"""
+    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.plugins.xep_0060.stanza.pubsub import *
+from sleekxmpp.plugins.xep_0060.stanza.pubsub_owner import *
+from sleekxmpp.plugins.xep_0060.stanza.pubsub_event import *
+from sleekxmpp.plugins.xep_0060.stanza.pubsub_errors import *

sleekxmpp/plugins/xep_0060/stanza/base.py

@@ -1,24 +1,29 @@
-from xml.etree import cElementTree as ET
+"""
+    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 ET
+
 
 class OptionalSetting(object):
-	interfaces = set(('required',))
 
-	def setRequired(self, value):
-		value = bool(value)
-		if value and not self['required']:
-			self.xml.append(ET.Element("{%s}required" % self.namespace))
-		elif not value and self['required']:
-			self.delRequired()
-	
-	def getRequired(self):
-		required = self.xml.find("{%s}required" % self.namespace)
-		if required is not None:
-			return True
-		else:
-			return False
-	
-	def delRequired(self):
-		required = self.xml.find("{%s}required" % self.namespace)
-		if required is not None:
-			self.xml.remove(required)
+    interfaces = set(('required',))
 
+    def set_required(self, value):
+        if value in (True, 'true', 'True', '1'):
+            self.xml.append(ET.Element("{%s}required" % self.namespace))
+        elif self['required']:
+            self.del_required()
+
+    def get_required(self):
+        required = self.xml.find("{%s}required" % self.namespace)
+        return required is not None
+
+    def del_required(self):
+        required = self.xml.find("{%s}required" % self.namespace)
+        if required is not None:
+            self.xml.remove(required)

sleekxmpp/plugins/xep_0060/stanza/pubsub.py

@@ -1,9 +1,13 @@
-from sleekxmpp.xmlstream.stanzabase import registerStanzaPlugin, ElementBase, ET, JID
-from sleekxmpp.stanza.iq import Iq
-from sleekxmpp.stanza.message import Message
-from sleekxmpp.basexmpp import basexmpp
-from sleekxmpp.xmlstream.xmlstream import XMLStream
-import logging
+"""
+    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 import Iq, Message
+from sleekxmpp.xmlstream import register_stanza_plugin, ElementBase, ET, JID
 from sleekxmpp.plugins import xep_0004
 from sleekxmpp.plugins.xep_0060.stanza.base import OptionalSetting
 
@@ -11,12 +15,15 @@ from sleekxmpp.plugins.xep_0060.stanza.base import OptionalSetting
 class Pubsub(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'pubsub'
-    plugin_attrib = 'pubsub'
+    plugin_attrib = name
     interfaces = set(tuple())
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-registerStanzaPlugin(Iq, Pubsub)
+
+class Affiliations(ElementBase):
+    namespace = 'http://jabber.org/protocol/pubsub'
+    name = 'affiliations'
+    plugin_attrib = name
+    interfaces = set(('node',))
 
 
 class Affiliation(ElementBase):
@@ -24,25 +31,12 @@ class Affiliation(ElementBase):
     name = 'affiliation'
     plugin_attrib = name
     interfaces = set(('node', 'affiliation', 'jid'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
-    
-    def setJid(self, value):
-        self._setAttr('jid', str(value))
 
-    def getJid(self):
-        return JID(self._getAttr('jid'))
+    def set_jid(self, value):
+        self._set_attr('jid', str(value))
 
-class Affiliations(ElementBase):
-    namespace = 'http://jabber.org/protocol/pubsub'
-    name = 'affiliations'
-    plugin_attrib = 'affiliations'
-    interfaces = set(tuple())
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
-    subitem = (Affiliation,)
-
-registerStanzaPlugin(Pubsub, Affiliations)
+    def get_jid(self):
+        return JID(self._get_attr('jid'))
 
 
 class Subscription(ElementBase):
@@ -50,228 +44,257 @@ class Subscription(ElementBase):
     name = 'subscription'
     plugin_attrib = name
     interfaces = set(('jid', 'node', 'subscription', 'subid'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-    def setjid(self, value):
-        self._setattr('jid', str(value))
+    def set_jid(self, value):
+        self._set_attr('jid', str(value))
 
-    def getjid(self):
-        return jid(self._getattr('jid'))
+    def get_jid(self):
+        return JID(self._get_attr('jid'))
 
-registerStanzaPlugin(Pubsub, Subscription)
 
 class Subscriptions(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'subscriptions'
-    plugin_attrib = 'subscriptions'
-    interfaces = set(tuple())
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
-    subitem = (Subscription,)
-
-registerStanzaPlugin(Pubsub, Subscriptions)
+    plugin_attrib = name
+    interfaces = set(('node',))
 
 
 class SubscribeOptions(ElementBase, OptionalSetting):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'subscribe-options'
     plugin_attrib = 'suboptions'
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
     interfaces = set(('required',))
 
-registerStanzaPlugin(Subscription, SubscribeOptions)
 
 class Item(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'item'
     plugin_attrib = name
     interfaces = set(('id', 'payload'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-    def setPayload(self, value):
-        self.xml.append(value)
+    def set_payload(self, value):
+        del self['payload']
+        self.append(value)
 
-    def getPayload(self):
+    def get_payload(self):
         childs = self.xml.getchildren()
         if len(childs) > 0:
             return childs[0]
 
-    def delPayload(self):
+    def del_payload(self):
         for child in self.xml.getchildren():
             self.xml.remove(child)
 
+
 class Items(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'items'
-    plugin_attrib = 'items'
-    interfaces = set(('node',))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
-    subitem = (Item,)
+    plugin_attrib = name
+    interfaces = set(('node', 'max_items'))
+
+    def set_max_items(self, value):
+        self._set_attr('max_items', str(value))
 
-registerStanzaPlugin(Pubsub, Items)
 
 class Create(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'create'
     plugin_attrib = name
     interfaces = set(('node',))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-registerStanzaPlugin(Pubsub, Create)
 
-#class Default(ElementBase):
-#    namespace = 'http://jabber.org/protocol/pubsub'
-#    name = 'default'
-#    plugin_attrib = name
-#    interfaces = set(('node', 'type'))
-#    plugin_attrib_map = {}
-#    plugin_tag_map = {}
-#
-#    def getType(self):
-#        t = self._getAttr('type')
-#        if not t: t == 'leaf'
-#        return t
-#
-#registerStanzaPlugin(Pubsub, Default)
+class Default(ElementBase):
+    namespace = 'http://jabber.org/protocol/pubsub'
+    name = 'default'
+    plugin_attrib = name
+    interfaces = set(('node', 'type'))
 
-class Publish(Items):
+    def get_type(self):
+        t = self._get_attr('type')
+        if not t:
+            return 'leaf'
+        return t
+
+
+class Publish(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'publish'
     plugin_attrib = name
     interfaces = set(('node',))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
-    subitem = (Item,)
 
-registerStanzaPlugin(Pubsub, Publish)
 
-class Retract(Items):
+class Retract(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'retract'
     plugin_attrib = name
     interfaces = set(('node', 'notify'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-registerStanzaPlugin(Pubsub, Retract)
+    def get_notify(self):
+        notify = self._get_attr('notify')
+        if notify in ('0', 'false'):
+            return False
+        elif notify in ('1', 'true'):
+            return True
+        return None
+
+    def set_notify(self, value):
+        del self['notify']
+        if value is None:
+            return
+        elif value in (True, '1', 'true', 'True'):
+            self._set_attr('notify', 'true')
+        else:
+            self._set_attr('notify', 'false')
+
 
 class Unsubscribe(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'unsubscribe'
     plugin_attrib = name
     interfaces = set(('node', 'jid', 'subid'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-    def setJid(self, value):
-        self._setAttr('jid', str(value))
+    def set_jid(self, value):
+        self._set_attr('jid', str(value))
 
-    def getJid(self):
-        return JID(self._getAttr('jid'))
+    def get_jid(self):
+        return JID(self._get_attr('jid'))
 
-registerStanzaPlugin(Pubsub, Unsubscribe)
 
 class Subscribe(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'subscribe'
     plugin_attrib = name
     interfaces = set(('node', 'jid'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-    def setJid(self, value):
-        self._setAttr('jid', str(value))
+    def set_jid(self, value):
+        self._set_attr('jid', str(value))
 
-    def getJid(self):
-        return JID(self._getAttr('jid'))
+    def get_jid(self):
+        return JID(self._get_attr('jid'))
 
-registerStanzaPlugin(Pubsub, Subscribe)
 
 class Configure(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'configure'
     plugin_attrib = name
     interfaces = set(('node', 'type'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
     def getType(self):
-        t = self._getAttr('type')
-        if not t: t == 'leaf'
+        t = self._get_attr('type')
+        if not t:
+            t == 'leaf'
         return t
 
-registerStanzaPlugin(Pubsub, Configure)
-registerStanzaPlugin(Configure, xep_0004.Form)
 
 class Options(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub'
     name = 'options'
-    plugin_attrib = 'options'
+    plugin_attrib = name
     interfaces = set(('jid', 'node', 'options'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
     def __init__(self, *args, **kwargs):
         ElementBase.__init__(self, *args, **kwargs)
 
-    def getOptions(self):
+    def get_options(self):
         config = self.xml.find('{jabber:x:data}x')
-        form = xep_0004.Form()
-        if config is not None:
-            form.fromXML(config)
+        form = xep_0004.Form(xml=config)
         return form
 
-    def setOptions(self, value):
+    def set_options(self, value):
         self.xml.append(value.getXML())
         return self
 
-    def delOptions(self):
+    def del_options(self):
         config = self.xml.find('{jabber:x:data}x')
         self.xml.remove(config)
 
-    def setJid(self, value):
-        self._setAttr('jid', str(value))
+    def set_jid(self, value):
+        self._set_attr('jid', str(value))
 
-    def getJid(self):
-        return JID(self._getAttr('jid'))
+    def get_jid(self):
+        return JID(self._get_attr('jid'))
+
+
+class PublishOptions(ElementBase):
+    namespace = 'http://jabber.org/protocol/pubsub'
+    name = 'publish-options'
+    plugin_attrib = 'publish_options'
+    interfaces = set(('publish_options',))
+    is_extension = True
+
+    def get_publish_options(self):
+        config = self.xml.find('{jabber:x:data}x')
+        if config is None:
+            return None
+        form = xep_0004.Form(xml=config)
+        return form
+
+    def set_publish_options(self, value):
+        if value is None:
+            self.del_publish_options()
+        else:
+            self.xml.append(value.getXML())
+        return self
+
+    def del_publish_options(self):
+        config = self.xml.find('{jabber:x:data}x')
+        if config is not None:
+            self.xml.remove(config)
+        self.parent().xml.remove(self.xml)
 
-registerStanzaPlugin(Pubsub, Options)
-registerStanzaPlugin(Subscribe, Options)
 
 class PubsubState(ElementBase):
+    """This is an experimental pubsub extension."""
     namespace = 'http://jabber.org/protocol/psstate'
     name = 'state'
     plugin_attrib = 'psstate'
     interfaces = set(('node', 'item', 'payload'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-    def setPayload(self, value):
+    def set_payload(self, value):
         self.xml.append(value)
 
-    def getPayload(self):
+    def get_payload(self):
         childs = self.xml.getchildren()
         if len(childs) > 0:
             return childs[0]
 
-    def delPayload(self):
+    def del_payload(self):
         for child in self.xml.getchildren():
             self.xml.remove(child)
 
-registerStanzaPlugin(Iq, PubsubState)
 
 class PubsubStateEvent(ElementBase):
+    """This is an experimental pubsub extension."""
     namespace = 'http://jabber.org/protocol/psstate#event'
     name = 'event'
     plugin_attrib = 'psstate_event'
     intefaces = set(tuple())
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-registerStanzaPlugin(Message, PubsubStateEvent)
-registerStanzaPlugin(PubsubStateEvent, PubsubState)
+
+register_stanza_plugin(Iq, PubsubState)
+register_stanza_plugin(Message, PubsubStateEvent)
+register_stanza_plugin(PubsubStateEvent, PubsubState)
+
+
+register_stanza_plugin(Iq, Pubsub)
+register_stanza_plugin(Pubsub, Affiliations)
+register_stanza_plugin(Pubsub, Configure)
+register_stanza_plugin(Pubsub, Create)
+register_stanza_plugin(Pubsub, Default)
+register_stanza_plugin(Pubsub, Items)
+register_stanza_plugin(Pubsub, Options)
+register_stanza_plugin(Pubsub, Publish)
+register_stanza_plugin(Pubsub, PublishOptions)
+register_stanza_plugin(Pubsub, Retract)
+register_stanza_plugin(Pubsub, Subscribe)
+register_stanza_plugin(Pubsub, Subscription)
+register_stanza_plugin(Pubsub, Subscriptions)
+register_stanza_plugin(Pubsub, Unsubscribe)
+register_stanza_plugin(Affiliations, Affiliation, iterable=True)
+register_stanza_plugin(Configure, xep_0004.Form)
+register_stanza_plugin(Items, Item, iterable=True)
+register_stanza_plugin(Publish, Item, iterable=True)
+register_stanza_plugin(Retract, Item)
+register_stanza_plugin(Subscribe, Options)
+register_stanza_plugin(Subscription, SubscribeOptions)
+register_stanza_plugin(Subscriptions, Subscription, iterable=True)

sleekxmpp/plugins/xep_0060/stanza/pubsub_errors.py

@@ -0,0 +1,86 @@
+"""
+    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.stanza import Error
+from sleekxmpp.xmlstream import ElementBase, ET, register_stanza_plugin
+
+
+class PubsubErrorCondition(ElementBase):
+
+    plugin_attrib = 'pubsub'
+    interfaces = set(('condition', 'unsupported'))
+    plugin_attrib_map = {}
+    plugin_tag_map = {}
+    conditions = set(('closed-node', 'configuration-required', 'invalid-jid',
+                      'invalid-options', 'invalid-payload', 'invalid-subid',
+                      'item-forbidden', 'item-required', 'jid-required',
+                      'max-items-exceeded', 'max-nodes-exceeded',
+                      'nodeid-required', 'not-in-roster-group',
+                      'not-subscribed', 'payload-too-big',
+                      'payload-required', 'pending-subscription',
+                      'presence-subscription-required', 'subid-required',
+                      'too-many-subscriptions', 'unsupported'))
+    condition_ns = 'http://jabber.org/protocol/pubsub#errors'
+
+    def setup(self, xml):
+        """Don't create XML for the plugin."""
+        self.xml = ET.Element('')
+
+    def get_condition(self):
+        """Return the condition element's name."""
+        for child in self.parent().xml.getchildren():
+            if "{%s}" % self.condition_ns in child.tag:
+                cond = child.tag.split('}', 1)[-1]
+                if cond in self.conditions:
+                    return cond
+        return ''
+
+    def set_condition(self, value):
+        """
+        Set the tag name of the condition element.
+
+        Arguments:
+           value -- The tag name of the condition element.
+        """
+        if value in self.conditions:
+            del self['condition']
+            cond = ET.Element("{%s}%s" % (self.condition_ns, value))
+            self.parent().xml.append(cond)
+        return self
+
+    def del_condition(self):
+        """Remove the condition element."""
+        for child in self.parent().xml.getchildren():
+            if "{%s}" % self.condition_ns in child.tag:
+                tag = child.tag.split('}', 1)[-1]
+                if tag in self.conditions:
+                    self.parent().xml.remove(child)
+        return self
+
+    def get_unsupported(self):
+        """Return the name of an unsupported feature"""
+        xml = self.parent().xml.find('{%s}unsupported' % self.condition_ns)
+        if xml is not None:
+            return xml.attrib.get('feature', '')
+        return ''
+
+    def set_unsupported(self, value):
+        """Mark a feature as unsupported"""
+        self.del_unsupported()
+        xml = ET.Element('{%s}unsupported' % self.condition_ns)
+        xml.attrib['feature'] = value
+        self.parent().xml.append(xml)
+
+    def del_unsupported(self):
+        """Delete an unsupported feature condition."""
+        xml = self.parent().xml.find('{%s}unsupported' % self.condition_ns)
+        if xml is not None:
+            self.parent().xml.remove(xml)
+
+
+register_stanza_plugin(Error, PubsubErrorCondition)

sleekxmpp/plugins/xep_0060/stanza/pubsub_event.py

@@ -1,124 +1,112 @@
-from sleekxmpp.xmlstream.stanzabase import registerStanzaPlugin, ElementBase, ET, JID
-from sleekxmpp.stanza.iq import Iq
-from sleekxmpp.stanza.message import Message
-from sleekxmpp.basexmpp import basexmpp
-from sleekxmpp.xmlstream.xmlstream import XMLStream
-import logging
-from sleekxmpp.plugins import xep_0004
+"""
+    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 import Message
+from sleekxmpp.xmlstream import register_stanza_plugin, ElementBase, ET, JID
+from sleekxmpp.plugins.xep_0004 import Form
+
 
 class Event(ElementBase):
-	namespace = 'http://jabber.org/protocol/pubsub#event'
-	name = 'event'
-	plugin_attrib = 'pubsub_event'
-	interfaces = set(('node',))
-	plugin_attrib_map = {}
-	plugin_tag_map = {}
+    namespace = 'http://jabber.org/protocol/pubsub#event'
+    name = 'event'
+    plugin_attrib = 'pubsub_event'
+    interfaces = set(('node',))
 
-registerStanzaPlugin(Message, Event)
 
 class EventItem(ElementBase):
-	namespace = 'http://jabber.org/protocol/pubsub#event'
-	name = 'item'
-	plugin_attrib = 'item'
-	interfaces = set(('id', 'payload'))
-	plugin_attrib_map = {}
-	plugin_tag_map = {}
+    namespace = 'http://jabber.org/protocol/pubsub#event'
+    name = 'item'
+    plugin_attrib = name
+    interfaces = set(('id', 'payload'))
 
-	def setPayload(self, value):
-		self.xml.append(value)
-	
-	def getPayload(self):
-		childs = self.xml.getchildren()
-		if len(childs) > 0:
-			return childs[0]
-	
-	def delPayload(self):
-		for child in self.xml.getchildren():
-			self.xml.remove(child)
+    def set_payload(self, value):
+        self.xml.append(value)
+
+    def get_payload(self):
+        childs = self.xml.getchildren()
+        if len(childs) > 0:
+            return childs[0]
+
+    def del_payload(self):
+        for child in self.xml.getchildren():
+            self.xml.remove(child)
 
 
 class EventRetract(ElementBase):
-	namespace = 'http://jabber.org/protocol/pubsub#event'
-	name = 'retract'
-	plugin_attrib = 'retract'
-	interfaces = set(('id',))
-	plugin_attrib_map = {}
-	plugin_tag_map = {}
+    namespace = 'http://jabber.org/protocol/pubsub#event'
+    name = 'retract'
+    plugin_attrib = name
+    interfaces = set(('id',))
+
 
 class EventItems(ElementBase):
-	namespace = 'http://jabber.org/protocol/pubsub#event'
-	name = 'items'
-	plugin_attrib = 'items'
-	interfaces = set(('node',))
-	plugin_attrib_map = {}
-	plugin_tag_map = {}
-	subitem = (EventItem, EventRetract)
+    namespace = 'http://jabber.org/protocol/pubsub#event'
+    name = 'items'
+    plugin_attrib = name
+    interfaces = set(('node',))
 
-registerStanzaPlugin(Event, EventItems)
 
 class EventCollection(ElementBase):
-	namespace = 'http://jabber.org/protocol/pubsub#event'
-	name = 'collection'
-	plugin_attrib = name
-	interfaces = set(('node',))
-	plugin_attrib_map = {}
-	plugin_tag_map = {}
+    namespace = 'http://jabber.org/protocol/pubsub#event'
+    name = 'collection'
+    plugin_attrib = name
+    interfaces = set(('node',))
 
-registerStanzaPlugin(Event, EventCollection)
 
 class EventAssociate(ElementBase):
-	namespace = 'http://jabber.org/protocol/pubsub#event'
-	name = 'associate'
-	plugin_attrib = name
-	interfaces = set(('node',))
-	plugin_attrib_map = {}
-	plugin_tag_map = {}
+    namespace = 'http://jabber.org/protocol/pubsub#event'
+    name = 'associate'
+    plugin_attrib = name
+    interfaces = set(('node',))
 
-registerStanzaPlugin(EventCollection, EventAssociate)
 
 class EventDisassociate(ElementBase):
-	namespace = 'http://jabber.org/protocol/pubsub#event'
-	name = 'disassociate'
-	plugin_attrib = name
-	interfaces = set(('node',))
-	plugin_attrib_map = {}
-	plugin_tag_map = {}
+    namespace = 'http://jabber.org/protocol/pubsub#event'
+    name = 'disassociate'
+    plugin_attrib = name
+    interfaces = set(('node',))
 
-registerStanzaPlugin(EventCollection, EventDisassociate)
 
 class EventConfiguration(ElementBase):
-	namespace = 'http://jabber.org/protocol/pubsub#event'
-	name = 'configuration'
-	plugin_attrib = name
-	interfaces = set(('node', 'config'))
-	plugin_attrib_map = {}
-	plugin_tag_map = {}
-	
-registerStanzaPlugin(Event, EventConfiguration)
-registerStanzaPlugin(EventConfiguration, xep_0004.Form)
+    namespace = 'http://jabber.org/protocol/pubsub#event'
+    name = 'configuration'
+    plugin_attrib = name
+    interfaces = set(('node', 'config'))
+
 
 class EventPurge(ElementBase):
-	namespace = 'http://jabber.org/protocol/pubsub#event'
-	name = 'purge'
-	plugin_attrib = name
-	interfaces = set(('node',))
-	plugin_attrib_map = {}
-	plugin_tag_map = {}
+    namespace = 'http://jabber.org/protocol/pubsub#event'
+    name = 'purge'
+    plugin_attrib = name
+    interfaces = set(('node',))
 
-registerStanzaPlugin(Event, EventPurge)
 
 class EventSubscription(ElementBase):
-	namespace = 'http://jabber.org/protocol/pubsub#event'
-	name = 'subscription'
-	plugin_attrib = name
-	interfaces = set(('node','expiry', 'jid', 'subid', 'subscription'))
-	plugin_attrib_map = {}
-	plugin_tag_map = {}
-	
-	def setJid(self, value):
-		self._setAttr('jid', str(value))
-	
-	def getJid(self):
-		return JID(self._getAttr('jid'))
+    namespace = 'http://jabber.org/protocol/pubsub#event'
+    name = 'subscription'
+    plugin_attrib = name
+    interfaces = set(('node', 'expiry', 'jid', 'subid', 'subscription'))
 
-registerStanzaPlugin(Event, EventSubscription)
+    def set_jid(self, value):
+        self._set_attr('jid', str(value))
+
+    def get_jid(self):
+        return JID(self._get_attr('jid'))
+
+
+register_stanza_plugin(Message, Event)
+register_stanza_plugin(Event, EventCollection)
+register_stanza_plugin(Event, EventConfiguration)
+register_stanza_plugin(Event, EventItems)
+register_stanza_plugin(Event, EventPurge)
+register_stanza_plugin(Event, EventSubscription)
+register_stanza_plugin(EventCollection, EventAssociate)
+register_stanza_plugin(EventCollection, EventDisassociate)
+register_stanza_plugin(EventConfiguration, Form)
+register_stanza_plugin(EventItems, EventItem, iterable=True)
+register_stanza_plugin(EventItems, EventRetract, iterable=True)

sleekxmpp/plugins/xep_0060/stanza/pubsub_owner.py

@@ -1,155 +1,131 @@
-from sleekxmpp.xmlstream.stanzabase import registerStanzaPlugin, ElementBase, ET, JID
-from sleekxmpp.stanza.iq import Iq
-from sleekxmpp.stanza.message import Message
-from sleekxmpp.basexmpp import basexmpp
-from sleekxmpp.xmlstream.xmlstream import XMLStream
-import logging
-from sleekxmpp.plugins import xep_0004
+"""
+    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 import Iq
+from sleekxmpp.xmlstream import register_stanza_plugin, ElementBase, ET, JID
+from sleekxmpp.plugins.xep_0004 import Form
 from sleekxmpp.plugins.xep_0060.stanza.base import OptionalSetting
-from sleekxmpp.plugins.xep_0060.stanza.pubsub import Affiliations, Affiliation, Configure, Subscriptions
+from sleekxmpp.plugins.xep_0060.stanza.pubsub import Affiliations, Affiliation
+from sleekxmpp.plugins.xep_0060.stanza.pubsub import Configure, Subscriptions
+
 
 class PubsubOwner(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub#owner'
     name = 'pubsub'
     plugin_attrib = 'pubsub_owner'
     interfaces = set(tuple())
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-registerStanzaPlugin(Iq, PubsubOwner)
 
 class DefaultConfig(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub#owner'
     name = 'default'
-    plugin_attrib = 'default'
-    interfaces = set(('node', 'type', 'config'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
+    plugin_attrib = name
+    interfaces = set(('node', 'config'))
 
     def __init__(self, *args, **kwargs):
         ElementBase.__init__(self, *args, **kwargs)
 
-    def getType(self):
-        t = self._getAttr('type')
-        if not t: t = 'leaf'
-        return t
-
-    def getConfig(self):
+    def get_config(self):
         return self['form']
 
-    def setConfig(self, value):
-        self['form'].setStanzaValues(value.getStanzaValues())
+    def set_config(self, value):
+        self['form'].values = value.values
         return self
 
-registerStanzaPlugin(PubsubOwner, DefaultConfig)
-registerStanzaPlugin(DefaultConfig, xep_0004.Form)
 
 class OwnerAffiliations(Affiliations):
     namespace = 'http://jabber.org/protocol/pubsub#owner'
-    interfaces = set(('node'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
+    interfaces = set(('node',))
 
     def append(self, affiliation):
         if not isinstance(affiliation, OwnerAffiliation):
             raise TypeError
         self.xml.append(affiliation.xml)
-        return self.affiliations.append(affiliation)
 
-registerStanzaPlugin(PubsubOwner, OwnerAffiliations)
 
 class OwnerAffiliation(Affiliation):
     namespace = 'http://jabber.org/protocol/pubsub#owner'
     interfaces = set(('affiliation', 'jid'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
+
 
 class OwnerConfigure(Configure):
-    name = 'configure'
-    plugin_attrib = 'configure'
     namespace = 'http://jabber.org/protocol/pubsub#owner'
-    interfaces = set(('node', 'config'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
-    
-    def getConfig(self):
-        return self['form']
+    name = 'configure'
+    plugin_attrib = name
+    interfaces = set(('node',))
 
-    def setConfig(self, value):
-        self['form'].setStanzaValues(value.getStanzaValues())
-        return self
-
-registerStanzaPlugin(PubsubOwner, OwnerConfigure)
 
 class OwnerDefault(OwnerConfigure):
     namespace = 'http://jabber.org/protocol/pubsub#owner'
-    interfaces = set(('node', 'config'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
+    interfaces = set(('node',))
 
 
-registerStanzaPlugin(PubsubOwner, OwnerDefault)
-registerStanzaPlugin(OwnerDefault, xep_0004.Form)
-
 class OwnerDelete(ElementBase, OptionalSetting):
     namespace = 'http://jabber.org/protocol/pubsub#owner'
     name = 'delete'
-    plugin_attrib = 'delete'
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
+    plugin_attrib = name
     interfaces = set(('node',))
 
-registerStanzaPlugin(PubsubOwner, OwnerDelete)
 
 class OwnerPurge(ElementBase, OptionalSetting):
     namespace = 'http://jabber.org/protocol/pubsub#owner'
     name = 'purge'
     plugin_attrib = name
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
+    interfaces = set(('node',))
 
-registerStanzaPlugin(PubsubOwner, OwnerPurge)
 
 class OwnerRedirect(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub#owner'
     name = 'redirect'
     plugin_attrib = name
     interfaces = set(('node', 'jid'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-    def setJid(self, value):
-        self._setAttr('jid', str(value))
+    def set_jid(self, value):
+        self._set_attr('jid', str(value))
 
-    def getJid(self):
-        return JID(self._getAttr('jid'))
+    def get_jid(self):
+        return JID(self._get_attr('jid'))
 
-registerStanzaPlugin(OwnerDelete, OwnerRedirect)
 
 class OwnerSubscriptions(Subscriptions):
     namespace = 'http://jabber.org/protocol/pubsub#owner'
     interfaces = set(('node',))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
     def append(self, subscription):
         if not isinstance(subscription, OwnerSubscription):
             raise TypeError
         self.xml.append(subscription.xml)
-        return self.subscriptions.append(subscription)
 
-registerStanzaPlugin(PubsubOwner, OwnerSubscriptions)
 
 class OwnerSubscription(ElementBase):
     namespace = 'http://jabber.org/protocol/pubsub#owner'
     name = 'subscription'
     plugin_attrib = name
     interfaces = set(('jid', 'subscription'))
-    plugin_attrib_map = {}
-    plugin_tag_map = {}
 
-    def setJid(self, value):
-        self._setAttr('jid', str(value))
+    def set_jid(self, value):
+        self._set_attr('jid', str(value))
 
-    def getJid(self):
-        return JID(self._getAttr('from'))
+    def get_jid(self):
+        return JID(self._get_attr('jid'))
+
+
+register_stanza_plugin(Iq, PubsubOwner)
+register_stanza_plugin(PubsubOwner, DefaultConfig)
+register_stanza_plugin(PubsubOwner, OwnerAffiliations)
+register_stanza_plugin(PubsubOwner, OwnerConfigure)
+register_stanza_plugin(PubsubOwner, OwnerDefault)
+register_stanza_plugin(PubsubOwner, OwnerDelete)
+register_stanza_plugin(PubsubOwner, OwnerPurge)
+register_stanza_plugin(PubsubOwner, OwnerSubscriptions)
+register_stanza_plugin(DefaultConfig, Form)
+register_stanza_plugin(OwnerAffiliations, OwnerAffiliation, iterable=True)
+register_stanza_plugin(OwnerConfigure, Form)
+register_stanza_plugin(OwnerDefault, Form)
+register_stanza_plugin(OwnerDelete, OwnerRedirect)
+register_stanza_plugin(OwnerSubscriptions, OwnerSubscription, iterable=True)

sleekxmpp/plugins/xep_0066/oob.py

@@ -108,8 +108,7 @@ class xep_0066(base_plugin):
         iq = self.xmpp.Iq()
         iq['type'] = 'set'
         iq['to'] = to
-        if ifrom:
-            iq['from'] = ifrom
+        iq['from'] = ifrom
         iq['oob_transfer']['url'] = url
         iq['oob_transfer']['desc'] = desc
         return iq.send(**iqargs)

sleekxmpp/plugins/xep_0078/legacyauth.py

@@ -60,12 +60,12 @@ class xep_0078(base_plugin):
         try:
             resp = iq.send(now=True)
         except IqError:
-            log.info("Authentication failed: %s" % resp['error']['condition'])
+            log.info("Authentication failed: %s", resp['error']['condition'])
             self.xmpp.event('failed_auth', direct=True)
             self.xmpp.disconnect()
             return True
         except IqTimeout:
-            log.info("Authentication failed: %s" % 'timeout')
+            log.info("Authentication failed: %s", 'timeout')
             self.xmpp.event('failed_auth', direct=True)
             self.xmpp.disconnect()
             return True

sleekxmpp/plugins/xep_0082.py

@@ -76,7 +76,7 @@ def format_datetime(time_obj):
         return '%sZ' % timestamp
     return timestamp
 
-def date(year=None, month=None, day=None):
+def date(year=None, month=None, day=None, obj=False):
     """
     Create a date only timestamp for the given instant.
 
@@ -86,17 +86,22 @@ def date(year=None, month=None, day=None):
         year   -- Integer value of the year (4 digits)
         month  -- Integer value of the month
         day    -- Integer value of the day of the month.
+        obj    -- If True, return the date object instead
+                  of a formatted string. Defaults to False.
     """
-    today = dt.datetime.today()
+    today = dt.datetime.utcnow()
     if year is None:
         year = today.year
     if month is None:
         month = today.month
     if day is None:
         day = today.day
-    return format_date(dt.date(year, month, day))
+    value = dt.date(year, month, day)
+    if obj:
+        return value 
+    return format_date(value)
 
-def time(hour=None, min=None, sec=None, micro=None, offset=None):
+def time(hour=None, min=None, sec=None, micro=None, offset=None, obj=False):
     """
     Create a time only timestamp for the given instant.
 
@@ -110,6 +115,8 @@ def time(hour=None, min=None, sec=None, micro=None, offset=None):
         offset -- Either a positive or negative number of seconds
                   to offset from UTC to match a desired timezone,
                   or a tzinfo object.
+        obj    -- If True, return the time object instead
+                  of a formatted string. Defaults to False.
     """
     now = dt.datetime.utcnow()
     if hour is None:
@@ -124,12 +131,14 @@ def time(hour=None, min=None, sec=None, micro=None, offset=None):
         offset = tzutc()
     elif not isinstance(offset, dt.tzinfo):
         offset = tzoffset(None, offset)
-    time = dt.time(hour, min, sec, micro, offset)
-    return format_time(time)
+    value = dt.time(hour, min, sec, micro, offset)
+    if obj:
+        return value
+    return format_time(value)
 
 def datetime(year=None, month=None, day=None, hour=None,
              min=None, sec=None, micro=None, offset=None,
-             separators=True):
+             separators=True, obj=False):
     """
     Create a datetime timestamp for the given instant.
 
@@ -146,6 +155,8 @@ def datetime(year=None, month=None, day=None, hour=None,
         offset -- Either a positive or negative number of seconds
                   to offset from UTC to match a desired timezone,
                   or a tzinfo object.
+        obj    -- If True, return the datetime object instead
+                  of a formatted string. Defaults to False.
     """
     now = dt.datetime.utcnow()
     if year is None:
@@ -167,9 +178,11 @@ def datetime(year=None, month=None, day=None, hour=None,
     elif not isinstance(offset, dt.tzinfo):
         offset = tzoffset(None, offset)
 
-    date = dt.datetime(year, month, day, hour,
+    value = dt.datetime(year, month, day, hour,
                        min, sec, micro, offset)
-    return format_datetime(date)
+    if obj:
+        return value 
+    return format_datetime(value)
 
 class xep_0082(base_plugin):
 

sleekxmpp/plugins/xep_0085/chat_states.py

@@ -45,5 +45,5 @@ class xep_0085(base_plugin):
 
     def _handle_chat_state(self, msg):
         state = msg['chat_state']
-        log.debug("Chat State: %s, %s" % (state, msg['from'].jid))
+        log.debug("Chat State: %s, %s", state, msg['from'].jid)
         self.xmpp.event('chatstate_%s' % state, msg)

sleekxmpp/plugins/xep_0092/version.py

@@ -76,8 +76,7 @@ class xep_0092(base_plugin):
         """
         iq = self.xmpp.Iq()
         iq['to'] = jid
-        if ifrom:
-            iq['from'] = ifrom
+        iq['from'] = ifrom
         iq['type'] = 'get'
         iq['query'] = Version.namespace
 

sleekxmpp/plugins/xep_0199/ping.py

@@ -70,6 +70,8 @@ class xep_0199(base_plugin):
             self.xmpp.add_event_handler('session_start',
                                         self._handle_keepalive,
                                         threaded=True)
+            self.xmpp.add_event_handler('session_end',
+                                        self._handle_session_end)
 
     def post_init(self):
         """Handle cross-plugin dependencies."""
@@ -106,6 +108,9 @@ class xep_0199(base_plugin):
                            scheduled_ping,
                            repeat=True)
 
+    def _handle_session_end(self, event):
+        self.xmpp.scheduler.remove('Ping Keep Alive')
+
     def _handle_ping(self, iq):
         """
         Automatically reply to ping requests.
@@ -113,7 +118,7 @@ class xep_0199(base_plugin):
         Arguments:
             iq -- The ping request.
         """
-        log.debug("Pinged by %s" % iq['from'])
+        log.debug("Pinged by %s", iq['from'])
         iq.reply().send()
 
     def send_ping(self, jid, timeout=None, errorfalse=False,
@@ -136,15 +141,14 @@ class xep_0199(base_plugin):
                           is received. Useful in conjunction with
                           the option block=False.
         """
-        log.debug("Pinging %s" % jid)
+        log.debug("Pinging %s", jid)
         if timeout is None:
             timeout = self.timeout
 
         iq = self.xmpp.Iq()
         iq['type'] = 'get'
         iq['to'] = jid
-        if ifrom:
-            iq['from'] = ifrom
+        iq['from'] = ifrom
         iq.enable('ping')
 
         start_time = time.clock()
@@ -163,7 +167,7 @@ class xep_0199(base_plugin):
         if not block:
             return None
 
-        log.debug("Pong: %s %f" % (jid, delay))
+        log.debug("Pong: %s %f", jid, delay)
         return delay
 
 

sleekxmpp/plugins/xep_0202/time.py

@@ -85,8 +85,7 @@ class xep_0202(base_plugin):
         """
         iq = self.xmpp.Iq()
         iq['type'] = 'get'
-        iq['to'] = 'to'
-        if ifrom:
-            iq['from'] = 'ifrom'
+        iq['to'] = to
+        iq['from'] = ifrom
         iq.enable('entity_time')
         return iq.send(**iqargs)

sleekxmpp/plugins/xep_0224/attention.py

@@ -68,5 +68,5 @@ class xep_0224(base_plugin):
         Arguments:
             msg -- A message stanza with an attention element.
         """
-        log.debug("Received attention request from: %s" % msg['from'])
+        log.debug("Received attention request from: %s", msg['from'])
         self.xmpp.event('attention', msg)

sleekxmpp/roster/item.py

@@ -172,6 +172,7 @@ class RosterItem(object):
         Save the item's state information to an external datastore,
         if one has been provided.
         """
+        self['subscription'] = self._subscription()
         if self.db:
             self.db.save(self.owner, self.jid,
                          self._state, self._db_state)
@@ -224,7 +225,7 @@ class RosterItem(object):
         if self['to']:
             p = self.xmpp.Presence()
             p['to'] = self.jid
-            p['type'] = ['unsubscribe']
+            p['type'] = 'unsubscribe'
             if self.xmpp.is_component:
                 p['from'] = self.owner
             p.send()
@@ -345,7 +346,11 @@ class RosterItem(object):
             self.xmpp.event('got_online', presence)
         if resource not in self.resources:
             self.resources[resource] = {}
+        old_status = self.resources[resource].get('status', '')
+        old_show = self.resources[resource].get('show', None)
         self.resources[resource].update(data)
+        if old_show != presence['show'] or old_status != presence['status']:
+            self.xmpp.event('changed_status', presence)
 
     def handle_unavailable(self, presence):
         resource = presence['from'].resource
@@ -353,6 +358,7 @@ class RosterItem(object):
             return
         if resource in self.resources:
             del self.resources[resource]
+        self.xmpp.event('changed_status', presence)
         if not self.resources:
             self.xmpp.event('got_offline', presence)
 

sleekxmpp/roster/multi.py

@@ -48,8 +48,8 @@ class Roster(object):
         """
         self.xmpp = xmpp
         self.db = db
-        self.auto_authorize = True
-        self.auto_subscribe = True
+        self._auto_authorize = True
+        self._auto_subscribe = True
         self._rosters = {}
 
         if self.db:
@@ -138,3 +138,47 @@ class Roster(object):
                                   ppriority=ppriority,
                                   pnick=pnick,
                                   pto=pto)
+
+    @property
+    def auto_authorize(self):
+        """
+        Auto accept or deny subscription requests.
+
+        If True, auto accept subscription requests.
+        If False, auto deny subscription requests.
+        If None, don't automatically respond.
+        """
+        return self._auto_authorize
+
+    @auto_authorize.setter
+    def auto_authorize(self, value):
+        """
+        Auto accept or deny subscription requests.
+
+        If True, auto accept subscription requests.
+        If False, auto deny subscription requests.
+        If None, don't automatically respond.
+        """
+        self._auto_authorize = value
+        for node in self._rosters:
+            self._rosters[node].auto_authorize = value
+
+    @property
+    def auto_subscribe(self):
+        """
+        Auto send requests for mutual subscriptions.
+
+        If True, auto send mutual subscription requests.
+        """
+        return self._auto_subscribe
+
+    @auto_subscribe.setter
+    def auto_subscribe(self, value):
+        """
+        Auto send requests for mutual subscriptions.
+
+        If True, auto send mutual subscription requests.
+        """
+        self._auto_subscribe = value
+        for node in self._rosters:
+            self._rosters[node].auto_subscribe = value

sleekxmpp/roster/single.py

@@ -209,11 +209,11 @@ class RosterNode(object):
                             Implies block=False.
         """
         self[jid]['name'] = name
-        self[jid]['groups'] = group
+        self[jid]['groups'] = groups
         self[jid].save()
 
         if not self.xmpp.is_component:
-            iq = self.Iq()
+            iq = self.xmpp.Iq()
             iq['type'] = 'set'
             iq['roster']['items'] = {jid: {'name': name,
                                            'subscription': subscription,

sleekxmpp/stanza/error.py

@@ -53,6 +53,8 @@ class Error(ElementBase):
     plugin_attrib = 'error'
     interfaces = set(('code', 'condition', 'text', 'type'))
     sub_interfaces = set(('text',))
+    plugin_attrib_map = {}
+    plugin_tag_map = {}
     conditions = set(('bad-request', 'conflict', 'feature-not-implemented',
                       'forbidden', 'gone', 'internal-server-error',
                       'item-not-found', 'jid-malformed', 'not-acceptable',

sleekxmpp/stanza/message.py

@@ -79,7 +79,7 @@ class Message(RootStanza):
         return self
 
     def normal(self):
-        """Set the message type to 'chat'."""
+        """Set the message type to 'normal'."""
         self['type'] = 'normal'
         return self
 

sleekxmpp/stanza/rootstanza.py

@@ -80,8 +80,7 @@ class RootStanza(StanzaBase):
             self['error']['type'] = 'cancel'
             self.send()
             # log the error
-            log.exception('Error handling {%s}%s stanza' %
-                          (self.namespace, self.name))
+            log.exception('Error handling {%s}%s stanza' ,  self.namespace, self.name)
             # Finally raise the exception to a global exception handler
             self.stream.exception(e)
 

sleekxmpp/test/livesocket.py

@@ -138,7 +138,7 @@ class TestLiveSocket(object):
         """
         with self.send_queue_lock:
             self.send_queue.put(data)
-        self.socket.send(data)
+        return self.socket.send(data)
 
     # ------------------------------------------------------------------
     # File Socket

sleekxmpp/test/mocksocket.py

@@ -121,6 +121,7 @@ class TestSocket(object):
         if self.disconnected:
             raise socket.error
         self.send_queue.put(data)
+        return len(data)
 
     # ------------------------------------------------------------------
     # File Socket

sleekxmpp/test/sleektest.py

@@ -58,9 +58,6 @@ class SleekTest(unittest.TestCase):
         unittest.TestCase.__init__(self, *args, **kwargs)
         self.xmpp = None
 
-    def runTest(self):
-        pass
-
     def parse_xml(self, xml_string):
         try:
             xml = ET.fromstring(xml_string)
@@ -296,7 +293,8 @@ class SleekTest(unittest.TestCase):
     def stream_start(self, mode='client', skip=True, header=None,
                            socket='mock', jid='tester@localhost',
                            password='test', server='localhost',
-                           port=5222, plugins=None):
+                           port=5222, sasl_mech=None,
+                           plugins=None, plugin_config={}):
         """
         Initialize an XMPP client or component using a dummy XML stream.
 
@@ -320,10 +318,13 @@ class SleekTest(unittest.TestCase):
                         are loaded.
         """
         if mode == 'client':
-            self.xmpp = ClientXMPP(jid, password)
+            self.xmpp = ClientXMPP(jid, password,
+                                   sasl_mech=sasl_mech,
+                                   plugin_config=plugin_config)
         elif mode == 'component':
             self.xmpp = ComponentXMPP(jid, password,
-                                      server, port)
+                                      server, port,
+                                      plugin_config=plugin_config)
         else:
             raise ValueError("Unknown XMPP connection mode.")
 
@@ -336,7 +337,6 @@ class SleekTest(unittest.TestCase):
 
             # Simulate connecting for mock sockets.
             self.xmpp.auto_reconnect = False
-            self.xmpp.is_client = True
             self.xmpp.state._set_state('connected')
 
             # Must have the stream header ready for xmpp.process() to work.
@@ -351,7 +351,10 @@ class SleekTest(unittest.TestCase):
                 skip_queue.put('started')
 
             self.xmpp.add_event_handler('session_start', wait_for_session)
-            self.xmpp.connect()
+            if server is not None:
+                self.xmpp.connect((server, port))
+            else:
+                self.xmpp.connect()
         else:
             raise ValueError("Unknown socket type.")
 

sleekxmpp/thirdparty/suelta/mechanisms/scram_hmac.py

@@ -32,7 +32,7 @@ class SCRAM_HMAC(Mechanism):
             name = name[:-5]
             self._cb = True
 
-        self.hash = hash(self.name[6:])
+        self.hash = hash(name[6:])
         if self.hash is None:
             raise SASLCancelled(self.sasl, self)
         if not self.sasl.tls_active():

sleekxmpp/version.py

@@ -0,0 +1,13 @@
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2010  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+# We don't want to have to import the entire library
+# just to get the version info for setup.py
+
+__version__ = '1.0'
+__version_info__ = (1, 0, 0, '', 0)

sleekxmpp/xmlstream/filesocket.py

@@ -1,9 +1,15 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.filesocket
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    This module is a shim for correcting deficiencies in the file
+    socket implementation of Python2.6.
+
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 from socket import _fileobject
@@ -12,12 +18,11 @@ import socket
 
 class FileSocket(_fileobject):
 
-    """
-    Create a file object wrapper for a socket to work around
+    """Create a file object wrapper for a socket to work around
     issues present in Python 2.6 when using sockets as file objects.
 
-    The parser for xml.etree.cElementTree requires a file, but we will
-    be reading from the XMPP connection socket instead.
+    The parser for :class:`~xml.etree.cElementTree` requires a file, but
+    we will be reading from the XMPP connection socket instead.
     """
 
     def read(self, size=4096):
@@ -31,8 +36,7 @@ class FileSocket(_fileobject):
 
 class Socket26(socket._socketobject):
 
-    """
-    A custom socket implementation that uses our own FileSocket class
+    """A custom socket implementation that uses our own FileSocket class
     to work around issues in Python 2.6 when using sockets as files.
     """
 

sleekxmpp/xmlstream/handler/base.py

@@ -1,11 +1,16 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.handler.base
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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
 """
 
+import weakref
+
 
 class BaseHandler(object):
 
@@ -14,75 +19,62 @@ class BaseHandler(object):
     incoming stanzas so that the stanza may be processed in some way.
     Stanzas may be matched with multiple handlers.
 
-    Handler execution may take place in two phases. The first is during
-    the stream processing itself. The second is after stream processing
-    and during SleekXMPP's main event loop. The prerun method is used
-    for execution during stream processing, and the run method is used
-    during the main event loop.
+    Handler execution may take place in two phases: during the incoming
+    stream processing, and in the main event loop. The :meth:`prerun()`
+    method is executed in the first case, and :meth:`run()` is called
+    during the second.
 
-    Attributes:
-        name   -- The name of the handler.
-        stream -- The stream this handler is assigned to.
-
-    Methods:
-        match        -- Compare a stanza with the handler's matcher.
-        prerun       -- Handler execution during stream processing.
-        run          -- Handler execution during the main event loop.
-        check_delete -- Indicate if the handler may be removed from use.
+    :param string name: The name of the handler.
+    :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+                    derived object that will be used to determine if a
+                    stanza should be accepted by this handler.
+    :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+                    instance that the handle will respond to.
     """
 
     def __init__(self, name, matcher, stream=None):
-        """
-        Create a new stream handler.
-
-        Arguments:
-            name    -- The name of the handler.
-            matcher -- A matcher object from xmlstream.matcher that will be
-                       used to determine if a stanza should be accepted by
-                       this handler.
-            stream  -- The XMLStream instance the handler should monitor.
-        """
+        #: The name of the handler
         self.name = name
-        self.stream = stream
+
+        #: The XML stream this handler is assigned to
+        self.stream = None
+        if stream is not None:
+            self.stream = weakref.ref(stream)
+            stream.register_handler(self)
+
         self._destroy = False
         self._payload = None
         self._matcher = matcher
-        if stream is not None:
-            stream.registerHandler(self)
 
     def match(self, xml):
-        """
-        Compare a stanza or XML object with the handler's matcher.
+        """Compare a stanza or XML object with the handler's matcher.
 
-        Arguments
-            xml -- An XML or stanza object.
+        :param xml: An XML or 
+            :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object
         """
         return self._matcher.match(xml)
 
     def prerun(self, payload):
-        """
-        Prepare the handler for execution while the XML stream is being
-        processed.
+        """Prepare the handler for execution while the XML
+        stream is being processed.
 
-        Arguments:
-            payload -- A stanza object.
+        :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                        object.
         """
         self._payload = payload
 
     def run(self, payload):
-        """
-        Execute the handler after XML stream processing and during the
+        """Execute the handler after XML stream processing and during the
         main event loop.
 
-        Arguments:
-            payload -- A stanza object.
+        :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                        object.
         """
         self._payload = payload
 
     def check_delete(self):
-        """
-        Check if the handler should be removed from the list of stream
-        handlers.
+        """Check if the handler should be removed from the list 
+        of stream handlers.
         """
         return self._destroy
 

sleekxmpp/xmlstream/handler/callback.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.xmlstream.handler.callback
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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
 """
 
 from sleekxmpp.xmlstream.handler.base import BaseHandler
@@ -18,48 +21,42 @@ class Callback(BaseHandler):
     The handler may execute the callback either during stream
     processing or during the main event loop.
 
-    Callback functions are all executed in the same thread, so be
-    aware if you are executing functions that will block for extended
-    periods of time. Typically, you should signal your own events using the
-    SleekXMPP object's event() method to pass the stanza off to a threaded
-    event handler for further processing.
+    Callback functions are all executed in the same thread, so be aware if
+    you are executing functions that will block for extended periods of
+    time. Typically, you should signal your own events using the SleekXMPP
+    object's :meth:`~sleekxmpp.xmlstream.xmlstream.XMLStream.event()`
+    method to pass the stanza off to a threaded event handler for further
+    processing.
 
-    Methods:
-        prerun -- Overrides BaseHandler.prerun
-        run    -- Overrides BaseHandler.run
+
+    :param string name: The name of the handler.
+    :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+                    derived object for matching stanza objects.
+    :param pointer: The function to execute during callback.
+    :param bool thread: **DEPRECATED.** Remains only for 
+                        backwards compatibility.
+    :param bool once: Indicates if the handler should be used only
+                      once. Defaults to False.
+    :param bool instream: Indicates if the callback should be executed
+                          during stream processing instead of in the
+                          main event loop.
+    :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+                   instance this handler should monitor.
     """
 
     def __init__(self, name, matcher, pointer, thread=False,
                  once=False, instream=False, stream=None):
-        """
-        Create a new callback handler.
-
-        Arguments:
-            name     -- The name of the handler.
-            matcher  -- A matcher object for matching stanza objects.
-            pointer  -- The function to execute during callback.
-            thread   -- DEPRECATED. Remains only for backwards compatibility.
-            once     -- Indicates if the handler should be used only
-                        once. Defaults to False.
-            instream -- Indicates if the callback should be executed
-                        during stream processing instead of in the
-                        main event loop.
-            stream   -- The XMLStream instance this handler should monitor.
-        """
         BaseHandler.__init__(self, name, matcher, stream)
         self._pointer = pointer
         self._once = once
         self._instream = instream
 
     def prerun(self, payload):
-        """
-        Execute the callback during stream processing, if
-        the callback was created with instream=True.
+        """Execute the callback during stream processing, if
+        the callback was created with ``instream=True``.
 
-        Overrides BaseHandler.prerun
-
-        Arguments:
-            payload -- The matched stanza object.
+        :param payload: The matched
+            :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
         """
         if self._once:
             self._destroy = True
@@ -67,16 +64,13 @@ class Callback(BaseHandler):
             self.run(payload, True)
 
     def run(self, payload, instream=False):
-        """
-        Execute the callback function with the matched stanza payload.
+        """Execute the callback function with the matched stanza payload.
 
-        Overrides BaseHandler.run
-
-        Arguments:
-            payload  -- The matched stanza object.
-            instream -- Force the handler to execute during
-                        stream processing. Used only by prerun.
-                        Defaults to False.
+        :param payload: The matched
+            :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
+        :param bool instream: Force the handler to execute during stream
+                              processing. This should only be used by
+                              :meth:`prerun()`. Defaults to ``False``.
         """
         if not self._instream or instream:
             self._pointer(payload)

sleekxmpp/xmlstream/handler/waiter.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.xmlstream.handler.waiter
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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
 """
 
 import logging
@@ -22,83 +25,63 @@ log = logging.getLogger(__name__)
 class Waiter(BaseHandler):
 
     """
-    The Waiter handler allows an event handler to block
-    until a particular stanza has been received. The handler
-    will either be given the matched stanza, or False if the
-    waiter has timed out.
+    The Waiter handler allows an event handler to block until a
+    particular stanza has been received. The handler will either be
+    given the matched stanza, or ``False`` if the waiter has timed out.
 
-    Methods:
-        check_delete -- Overrides BaseHandler.check_delete
-        prerun       -- Overrides BaseHandler.prerun
-        run          -- Overrides BaseHandler.run
-        wait         -- Wait for a stanza to arrive and return it to
-                        an event handler.
+    :param string name: The name of the handler.
+    :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+                    derived object for matching stanza objects.
+    :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+                   instance this handler should monitor.
     """
 
     def __init__(self, name, matcher, stream=None):
-        """
-        Create a new Waiter.
-
-        Arguments:
-            name    -- The name of the waiter.
-            matcher -- A matcher object to detect the desired stanza.
-            stream  -- Optional XMLStream instance to monitor.
-        """
         BaseHandler.__init__(self, name, matcher, stream=stream)
         self._payload = queue.Queue()
 
     def prerun(self, payload):
-        """
-        Store the matched stanza.
+        """Store the matched stanza when received during processing.
 
-        Overrides BaseHandler.prerun
-
-        Arguments:
-            payload -- The matched stanza object.
+        :param payload: The matched
+            :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
         """
         self._payload.put(payload)
 
     def run(self, payload):
-        """
-        Do not process this handler during the main event loop.
-
-        Overrides BaseHandler.run
-
-        Arguments:
-            payload -- The matched stanza object.
-        """
+        """Do not process this handler during the main event loop."""
         pass
 
     def wait(self, timeout=None):
-        """
-        Block an event handler while waiting for a stanza to arrive.
+        """Block an event handler while waiting for a stanza to arrive.
 
         Be aware that this will impact performance if called from a
         non-threaded event handler.
 
-        Will return either the received stanza, or False if the waiter
-        timed out.
+        Will return either the received stanza, or ``False`` if the
+        waiter timed out.
 
-        Arguments:
-            timeout -- The number of seconds to wait for the stanza to
-                       arrive. Defaults to the global default timeout
-                       value sleekxmpp.xmlstream.RESPONSE_TIMEOUT.
+        :param int timeout: The number of seconds to wait for the stanza
+            to arrive. Defaults to the the stream's
+            :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream.response_timeout`
+            value.
         """
         if timeout is None:
-            timeout = self.stream.response_timeout
+            timeout = self.stream().response_timeout
 
-        try:
-            stanza = self._payload.get(True, timeout)
-        except queue.Empty:
-            stanza = False
-            log.warning("Timed out waiting for %s" % self.name)
-        self.stream.removeHandler(self.name)
+        elapsed_time = 0
+        stanza = False
+        while elapsed_time < timeout and not self.stream().stop.is_set():
+            try:
+                stanza = self._payload.get(True, 1)
+                break
+            except queue.Empty:
+                elapsed_time += 1
+                if elapsed_time >= timeout:
+                    log.warning("Timed out waiting for %s", self.name)
+        self.stream().remove_handler(self.name)
         return stanza
 
     def check_delete(self):
-        """
-        Always remove waiters after use.
-
-        Overrides BaseHandler.check_delete
-        """
+        """Always remove waiters after use."""
         return True

sleekxmpp/xmlstream/jid.py

@@ -1,15 +1,22 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.jid
+    ~~~~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    This module allows for working with Jabber IDs (JIDs) by
+    providing accessors for the various components of a JID.
+
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 from __future__ import unicode_literals
 
 
 class JID(object):
+
     """
     A representation of a Jabber ID, or JID.
 
@@ -19,18 +26,16 @@ class JID(object):
     When a resource is not used, the JID is called a bare JID.
     The JID is a full JID otherwise.
 
-    Attributes:
-        jid      -- Alias for 'full'.
-        full     -- The value of the full JID.
-        bare     -- The value of the bare JID.
-        user     -- The username portion of the JID.
-        domain   -- The domain name portion of the JID.
-        server   -- Alias for 'domain'.
-        resource -- The resource portion of the JID.
+    **JID Properties:**
+        :jid: Alias for ``full``.
+        :full: The value of the full JID.
+        :bare: The value of the bare JID.
+        :user: The username portion of the JID.
+        :domain: The domain name portion of the JID.
+        :server: Alias for ``domain``.
+        :resource: The resource portion of the JID.
 
-    Methods:
-        reset      -- Use a new JID value.
-        regenerate -- Recreate the JID from its components.
+    :param string jid: A string of the form ``'[user@]domain[/resource]'``.
     """
 
     def __init__(self, jid):
@@ -38,11 +43,9 @@ class JID(object):
         self.reset(jid)
 
     def reset(self, jid):
-        """
-        Start fresh from a new JID string.
+        """Start fresh from a new JID string.
 
-        Arguments:
-            jid - The new JID value.
+        :param string jid: A string of the form ``'[user@]domain[/resource]'``.
         """
         if isinstance(jid, JID):
             jid = jid.full
@@ -53,12 +56,10 @@ class JID(object):
         self._bare = None
 
     def __getattr__(self, name):
-        """
-        Handle getting the JID values, using cache if available.
+        """Handle getting the JID values, using cache if available.
 
-        Arguments:
-            name -- One of: user, server, domain, resource,
-                    full, or bare.
+        :param name: One of: user, server, domain, resource,
+                     full, or bare.
         """
         if name == 'resource':
             if self._resource is None and '/' in self._jid:
@@ -83,8 +84,7 @@ class JID(object):
             return self._bare or ""
 
     def __setattr__(self, name, value):
-        """
-        Edit a JID by updating it's individual values, resetting the
+        """Edit a JID by updating it's individual values, resetting the
         generated JID in the end.
 
         Arguments:
@@ -135,3 +135,7 @@ class JID(object):
         """
         other = JID(other)
         return self.full == other.full
+
+    def __ne__(self, other):
+        """Two JIDs are considered unequal if they are not equal."""
+        return not self == other

sleekxmpp/xmlstream/matcher/base.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.xmlstream.matcher.base
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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,21 +16,15 @@ class MatcherBase(object):
     Base class for stanza matchers. Stanza matchers are used to pick
     stanzas out of the XML stream and pass them to the appropriate
     stream handlers.
+
+    :param criteria: Object to compare some aspect of a stanza against.
     """
 
     def __init__(self, criteria):
-        """
-        Create a new stanza matcher.
-
-        Arguments:
-            criteria -- Object to compare some aspect of a stanza
-                        against.
-        """
         self._criteria = criteria
 
     def match(self, xml):
-        """
-        Check if a stanza matches the stored criteria.
+        """Check if a stanza matches the stored criteria.
 
         Meant to be overridden.
         """

sleekxmpp/xmlstream/matcher/id.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.xmlstream.matcher.id
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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
 """
 
 from sleekxmpp.xmlstream.matcher.base import MatcherBase
@@ -14,19 +17,13 @@ class MatcherId(MatcherBase):
     """
     The ID matcher selects stanzas that have the same stanza 'id'
     interface value as the desired ID.
-
-    Methods:
-        match -- Overrides MatcherBase.match.
     """
 
     def match(self, xml):
-        """
-        Compare the given stanza's 'id' attribute to the stored
-        id value.
+        """Compare the given stanza's ``'id'`` attribute to the stored
+        ``id`` value.
 
-        Overrides MatcherBase.match.
-
-        Arguments:
-            xml -- The stanza to compare against.
+        :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                    stanza to compare against.
         """
         return xml['id'] == self._criteria

sleekxmpp/xmlstream/matcher/stanzapath.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.xmlstream.matcher.stanzapath
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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
 """
 
 from sleekxmpp.xmlstream.matcher.base import MatcherBase
@@ -15,24 +18,17 @@ class StanzaPath(MatcherBase):
     The StanzaPath matcher selects stanzas that match a given "stanza path",
     which is similar to a normal XPath except that it uses the interfaces and
     plugins of the stanza instead of the actual, underlying XML.
-
-    In most cases, the stanza path and XPath should be identical, but be
-    aware that differences may occur.
-
-    Methods:
-        match -- Overrides MatcherBase.match.
     """
 
     def match(self, stanza):
         """
         Compare a stanza against a "stanza path". A stanza path is similar to
         an XPath expression, but uses the stanza's interfaces and plugins
-        instead of the underlying XML. For most cases, the stanza path and
-        XPath should be identical, but be aware that differences may occur.
+        instead of the underlying XML. See the documentation for the stanza
+        :meth:`~sleekxmpp.xmlstream.stanzabase.ElementBase.match()` method
+        for more information.
 
-        Overrides MatcherBase.match.
-
-        Arguments:
-            stanza -- The stanza object to compare against.
+        :param stanza: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                       stanza to compare against.
         """
         return stanza.match(self._criteria)

sleekxmpp/xmlstream/matcher/xmlmask.py

@@ -30,66 +30,59 @@ class MatchXMLMask(MatcherBase):
     XML pattern, or mask. For example, message stanzas with body elements
     could be matched using the mask:
 
+    .. code-block:: xml
+
         <message xmlns="jabber:client"><body /></message>
 
-    Use of XMLMask is discouraged, and XPath or StanzaPath should be used
-    instead.
+    Use of XMLMask is discouraged, and 
+    :class:`~sleekxmpp.xmlstream.matcher.xpath.MatchXPath` or 
+    :class:`~sleekxmpp.xmlstream.matcher.stanzapath.StanzaPath` 
+    should be used instead.
 
     The use of namespaces in the mask comparison is controlled by
-    IGNORE_NS. Setting IGNORE_NS to True will disable namespace based matching
-    for ALL XMLMask matchers.
+    ``IGNORE_NS``. Setting ``IGNORE_NS`` to ``True`` will disable namespace
+    based matching for ALL XMLMask matchers.
 
-    Methods:
-        match        -- Overrides MatcherBase.match.
-        setDefaultNS -- Set the default namespace for the mask.
+    :param criteria: Either an :class:`~xml.etree.ElementTree.Element` XML
+                     object or XML string to use as a mask.
     """
 
     def __init__(self, criteria):
-        """
-        Create a new XMLMask matcher.
-
-        Arguments:
-            criteria -- Either an XML object or XML string to use as a mask.
-        """
         MatcherBase.__init__(self, criteria)
         if isinstance(criteria, str):
             self._criteria = ET.fromstring(self._criteria)
         self.default_ns = 'jabber:client'
 
     def setDefaultNS(self, ns):
-        """
-        Set the default namespace to use during comparisons.
+        """Set the default namespace to use during comparisons.
 
-        Arguments:
-            ns -- The new namespace to use as the default.
+        :param ns: The new namespace to use as the default.
         """
         self.default_ns = ns
 
     def match(self, xml):
-        """
-        Compare a stanza object or XML object against the stored XML mask.
+        """Compare a stanza object or XML object against the stored XML mask.
 
         Overrides MatcherBase.match.
 
-        Arguments:
-            xml -- The stanza object or XML object to compare against.
+        :param xml: The stanza object or XML object to compare against.
         """
         if hasattr(xml, 'xml'):
             xml = xml.xml
         return self._mask_cmp(xml, self._criteria, True)
 
     def _mask_cmp(self, source, mask, use_ns=False, default_ns='__no_ns__'):
-        """
-        Compare an XML object against an XML mask.
+        """Compare an XML object against an XML mask.
 
-        Arguments:
-            source     -- The XML object to compare against the mask.
-            mask       -- The XML object serving as the mask.
-            use_ns     -- Indicates if namespaces should be respected during
-                          the comparison.
-            default_ns -- The default namespace to apply to elements that
-                          do not have a specified namespace.
-                          Defaults to "__no_ns__".
+        :param source: The :class:`~xml.etree.ElementTree.Element` XML object
+                       to compare against the mask.
+        :param mask: The :class:`~xml.etree.ElementTree.Element` XML object
+                     serving as the mask.
+        :param use_ns: Indicates if namespaces should be respected during
+                       the comparison.
+        :default_ns: The default namespace to apply to elements that
+                     do not have a specified namespace.
+                     Defaults to ``"__no_ns__"``.
         """
         use_ns = not IGNORE_NS
 
@@ -102,8 +95,7 @@ class MatchXMLMask(MatcherBase):
             try:
                 mask = ET.fromstring(mask)
             except ExpatError:
-                log.warning("Expat error: %s\nIn parsing: %s" % ('', mask))
-
+                log.warning("Expat error: %s\nIn parsing: %s", '', mask)
         if not use_ns:
             # Compare the element without using namespaces.
             source_tag = source.tag.split('}', 1)[-1]
@@ -149,14 +141,13 @@ class MatchXMLMask(MatcherBase):
         return True
 
     def _get_child(self, xml, tag):
-        """
-        Return a child element given its tag, ignoring namespace values.
+        """Return a child element given its tag, ignoring namespace values.
 
-        Returns None if the child was not found.
+        Returns ``None`` if the child was not found.
 
-        Arguments:
-            xml -- The XML object to search for the given child tag.
-            tag -- The name of the subelement to find.
+        :param xml: The :class:`~xml.etree.ElementTree.Element` XML object
+                    to search for the given child tag.
+        :param tag: The name of the subelement to find.
         """
         tag = tag.split('}')[-1]
         try: