Merge branch 'develop' into roster

1 files changed, 126 insertions, 0 deletions

diff --git a/sleekxmpp/plugins/xep_0030/static.py b/sleekxmpp/plugins/xep_0030/static.py
index b0e931b4..eff67f02 100644
--- a/sleekxmpp/plugins/xep_0030/static.py
+++ b/sleekxmpp/plugins/xep_0030/static.py
@@ -31,6 +31,11 @@ class StaticDisco(object):
 
     StaticDisco provides a set of node handlers that will store
     static sets of disco info and items in memory.
+
+    Attributes:
+        nodes -- A dictionary mapping (JID, node) tuples to a dict
+                 containing a disco#info and a disco#items stanza.
+        xmpp  -- The main SleekXMPP object.
     """
 
     def __init__(self, xmpp):
@@ -47,6 +52,14 @@ class StaticDisco(object):
         self.xmpp = xmpp
 
     def add_node(self, jid=None, node=None):
+        """
+        Create a new set of stanzas for the provided
+        JID and node combination.
+
+        Arguments:
+            jid  -- The JID that will own the new stanzas.
+            node -- The node that will own the new stanzas.
+        """
         if jid is None:
             jid = self.xmpp.boundjid.full
         if node is None:
@@ -57,7 +70,21 @@ class StaticDisco(object):
             self.nodes[(jid, node)]['info']['node'] = node
             self.nodes[(jid, node)]['items']['node'] = node
 
+    # =================================================================
+    # Node Handlers
+    #
+    # Each handler accepts three arguments: jid, node, and data.
+    # The jid and node parameters together determine the set of
+    # info and items stanzas that will be retrieved or added.
+    # The data parameter is a dictionary with additional paramters
+    # that will be passed to other calls.
+
     def get_info(self, jid, node, data):
+        """
+        Return the stored info data for the requested JID/node combination.
+
+        The data parameter is not used.
+        """
         if (jid, node) not in self.nodes:
             if not node:
                 return DiscoInfo()
@@ -67,10 +94,20 @@ class StaticDisco(object):
             return self.nodes[(jid, node)]['info']
 
     def del_info(self, jid, node, data):
+        """
+        Reset the info stanza for a given JID/node combination.
+
+        The data parameter is not used.
+        """
         if (jid, node) in self.nodes:
             self.nodes[(jid, node)]['info'] = DiscoInfo()
 
     def get_items(self, jid, node, data):
+        """
+        Return the stored items data for the requested JID/node combination.
+
+        The data parameter is not used.
+        """
         if (jid, node) not in self.nodes:
             if not node:
                 return DiscoInfo()
@@ -80,15 +117,34 @@ class StaticDisco(object):
             return self.nodes[(jid, node)]['items']
 
     def set_items(self, jid, node, data):
+        """
+        Replace the stored items data for a JID/node combination.
+
+        The data parameter is not used.
+        """
         items = data.get('items', set())
         self.add_node(jid, node)
         self.nodes[(jid, node)]['items']['items'] = items
 
     def del_items(self, jid, node, data):
+        """
+        Reset the items stanza for a given JID/node combination.
+
+        The data parameter is not used.
+        """
         if (jid, node) in self.nodes:
             self.nodes[(jid, node)]['items'] = DiscoItems()
 
     def add_identity(self, jid, node, data):
+        """
+        Add a new identity to te JID/node combination.
+
+        The data parameter may provide:
+            category -- The general category to which the agent belongs.
+            itype    -- A more specific designation with the category.
+            name     -- Optional human readable name for this identity.
+            lang     -- Optional standard xml:lang value.
+        """
         self.add_node(jid, node)
         self.nodes[(jid, node)]['info'].add_identity(
                 data.get('category', ''),
@@ -97,11 +153,27 @@ class StaticDisco(object):
                 data.get('lang', None))
 
     def set_identities(self, jid, node, data):
+        """
+        Add or replace all identities for a JID/node combination.
+
+        The data parameter should include:
+            identities -- A list of identities in tuple form:
+                            (category, type, name, lang)
+        """
         identities = data.get('identities', set())
         self.add_node(jid, node)
         self.nodes[(jid, node)]['info']['identities'] = identities
 
     def del_identity(self, jid, node, data):
+        """
+        Remove an identity from a JID/node combination.
+
+        The data parameter may provide:
+            category -- The general category to which the agent belonged.
+            itype    -- A more specific designation with the category.
+            name     -- Optional human readable name for this identity.
+            lang     -- Optional, standard xml:lang value.
+        """
         if (jid, node) not in self.nodes:
             return
         self.nodes[(jid, node)]['info'].del_identity(
@@ -110,21 +182,68 @@ class StaticDisco(object):
                 data.get('name', None),
                 data.get('lang', None))
 
+    def del_identities(self, jid, node, data):
+        """
+        Remove all identities from a JID/node combination.
+
+        The data parameter is not used.
+        """
+        if (jid, node) not in self.nodes:
+            return
+        del self.nodes[(jid, node)]['info']['identities']
+
     def add_feature(self, jid, node, data):
+        """
+        Add a feature to a JID/node combination.
+
+        The data parameter should include:
+            feature -- The namespace of the supported feature.
+        """
         self.add_node(jid, node)
         self.nodes[(jid, node)]['info'].add_feature(data.get('feature', ''))
 
     def set_features(self, jid, node, data):
+        """
+        Add or replace all features for a JID/node combination.
+
+        The data parameter should include:
+            features -- The new set of supported features.
+        """
         features = data.get('features', set())
         self.add_node(jid, node)
         self.nodes[(jid, node)]['info']['features'] = features
 
     def del_feature(self, jid, node, data):
+        """
+        Remove a feature from a JID/node combination.
+
+        The data parameter should include:
+            feature -- The namespace of the removed feature.
+        """
         if (jid, node) not in self.nodes:
             return
         self.nodes[(jid, node)]['info'].del_feature(data.get('feature', ''))
 
+    def del_features(self, jid, node, data):
+        """
+        Remove all features from a JID/node combination.
+
+        The data parameter is not used.
+        """
+        if (jid, node) not in self.nodes:
+            return
+        del self.nodes[(jid, node)]['info']['features']
+
     def add_item(self, jid, node, data):
+        """
+        Add an item to a JID/node combination.
+
+        The data parameter may include:
+            ijid  -- The JID for the item.
+            inode -- Optional additional information to reference
+                     non-addressable items.
+            name  -- Optional human readable name for the item.
+        """
         self.add_node(jid, node)
         self.nodes[(jid, node)]['items'].add_item(
                 data.get('ijid', ''),
@@ -132,6 +251,13 @@ class StaticDisco(object):
                 name=data.get('name', None))
 
     def del_item(self, jid, node, data):
+        """
+        Remove an item from a JID/node combination.
+
+        The data parameter may include:
+            ijid  -- JID of the item to remove.
+            inode -- Optional extra identifying information.
+        """
         if (jid, node) in self.nodes:
             self.nodes[(jid, node)]['items'].del_item(
                     data.get('ijid', ''),