summaryrefslogtreecommitdiff
path: root/sleekxmpp/stanza
diff options
context:
space:
mode:
authorLance Stout <lancestout@gmail.com>2010-08-11 23:32:14 -0400
committerLance Stout <lancestout@gmail.com>2010-08-11 23:32:14 -0400
commitb40a48979636ccb4055294427292b2decf095fea (patch)
tree98a04060a350fd4a2b97c12d740ad1609a234ee0 /sleekxmpp/stanza
parent7a5ef2849218e122b04e244aeedd67844a0690b2 (diff)
downloadslixmpp-b40a48979636ccb4055294427292b2decf095fea.tar.gz
slixmpp-b40a48979636ccb4055294427292b2decf095fea.tar.bz2
slixmpp-b40a48979636ccb4055294427292b2decf095fea.tar.xz
slixmpp-b40a48979636ccb4055294427292b2decf095fea.zip
Updated roster stanza with docs and PEP8 style.
Diffstat (limited to 'sleekxmpp/stanza')
-rw-r--r--sleekxmpp/stanza/roster.py146
1 files changed, 100 insertions, 46 deletions
diff --git a/sleekxmpp/stanza/roster.py b/sleekxmpp/stanza/roster.py
index eda65ec7..292c8956 100644
--- a/sleekxmpp/stanza/roster.py
+++ b/sleekxmpp/stanza/roster.py
@@ -5,51 +5,105 @@
See the file LICENSE for copying permission.
"""
-from .. xmlstream.stanzabase import registerStanzaPlugin, ElementBase, ET, JID
-import logging
+
+from sleekxmpp.stanza import Iq
+from sleekxmpp.xmlstream import JID
+from sleekxmpp.xmlstream.stanzabase import registerStanzaPlugin
+from sleekxmpp.xmlstream.stanzabase import ET, ElementBase
+
class Roster(ElementBase):
- namespace = 'jabber:iq:roster'
- name = 'query'
- plugin_attrib = 'roster'
- interfaces = set(('items',))
- sub_interfaces = set()
-
- def setItems(self, items):
- self.delItems()
- for jid in items:
- ijid = str(jid)
- item = ET.Element('{jabber:iq:roster}item', {'jid': ijid})
- if 'subscription' in items[jid]:
- item.attrib['subscription'] = items[jid]['subscription']
- if 'name' in items[jid]:
- name = items[jid]['name']
- if name is not None:
- item.attrib['name'] = name
- if 'groups' in items[jid]:
- for group in items[jid]['groups']:
- groupxml = ET.Element('{jabber:iq:roster}group')
- groupxml.text = group
- item.append(groupxml)
- self.xml.append(item)
- return self
-
- def getItems(self):
- items = {}
- itemsxml = self.xml.findall('{jabber:iq:roster}item')
- if itemsxml is not None:
- for itemxml in itemsxml:
- item = {}
- item['name'] = itemxml.get('name', '')
- item['subscription'] = itemxml.get('subscription', '')
- item['groups'] = []
- groupsxml = itemxml.findall('{jabber:iq:roster}group')
- if groupsxml is not None:
- for groupxml in groupsxml:
- item['groups'].append(groupxml.text)
- items[itemxml.get('jid')] = item
- return items
-
- def delItems(self):
- for child in self.xml.getchildren():
- self.xml.remove(child)
+
+ """
+ Example roster stanzas:
+ <iq type="set">
+ <query xmlns="jabber:iq:roster">
+ <item jid="user@example.com" subscription="both" name="User">
+ <group>Friends</group>
+ </item>
+ </query>
+ </iq>
+
+ Stanza Inteface:
+ items -- A dictionary of roster entries contained
+ in the stanza.
+
+ Methods:
+ getItems -- Return a dictionary of roster entries.
+ setItems -- Add <item> elements.
+ delItems -- Remove all <item> elements.
+ """
+
+ namespace = 'jabber:iq:roster'
+ name = 'query'
+ plugin_attrib = 'roster'
+ interfaces = set(('items',))
+
+ def setItems(self, items):
+ """
+ Set the roster entries in the <roster> stanza.
+
+ Uses a dictionary using JIDs as keys, where each entry is itself
+ a dictionary that contains:
+ name -- An alias or nickname for the JID.
+ subscription -- The subscription type. Can be one of 'to',
+ 'from', 'both', 'none', or 'remove'.
+ groups -- A list of group names to which the JID
+ has been assigned.
+
+ Arguments:
+ items -- A dictionary of roster entries.
+ """
+ self.delItems()
+ for jid in items:
+ ijid = str(jid)
+ item = ET.Element('{jabber:iq:roster}item', {'jid': ijid})
+ if 'subscription' in items[jid]:
+ item.attrib['subscription'] = items[jid]['subscription']
+ if 'name' in items[jid]:
+ name = items[jid]['name']
+ if name is not None:
+ item.attrib['name'] = name
+ if 'groups' in items[jid]:
+ for group in items[jid]['groups']:
+ groupxml = ET.Element('{jabber:iq:roster}group')
+ groupxml.text = group
+ item.append(groupxml)
+ self.xml.append(item)
+ return self
+
+ def getItems(self):
+ """
+ Return a dictionary of roster entries.
+
+ Each item is keyed using its JID, and contains:
+ name -- An assigned alias or nickname for the JID.
+ subscription -- The subscription type. Can be one of 'to',
+ 'from', 'both', 'none', or 'remove'.
+ groups -- A list of group names to which the JID has
+ been assigned.
+ """
+ items = {}
+ itemsxml = self.xml.findall('{jabber:iq:roster}item')
+ if itemsxml is not None:
+ for itemxml in itemsxml:
+ item = {}
+ item['name'] = itemxml.get('name', '')
+ item['subscription'] = itemxml.get('subscription', '')
+ item['groups'] = []
+ groupsxml = itemxml.findall('{jabber:iq:roster}group')
+ if groupsxml is not None:
+ for groupxml in groupsxml:
+ item['groups'].append(groupxml.text)
+ items[itemxml.get('jid')] = item
+ return items
+
+ def delItems(self):
+ """
+ Remove all <item> elements from the roster stanza.
+ """
+ for child in self.xml.getchildren():
+ self.xml.remove(child)
+
+
+registerStanzaPlugin(Iq, Roster)