summaryrefslogtreecommitdiff
path: root/sleekxmpp/roster.py
diff options
context:
space:
mode:
Diffstat (limited to 'sleekxmpp/roster.py')
-rw-r--r--sleekxmpp/roster.py44
1 files changed, 40 insertions, 4 deletions
diff --git a/sleekxmpp/roster.py b/sleekxmpp/roster.py
index 77d2131d..da485336 100644
--- a/sleekxmpp/roster.py
+++ b/sleekxmpp/roster.py
@@ -364,9 +364,20 @@ class RosterItem(object):
def __init__(self, xmpp, jid, owner=None,
state=None, db=None):
+ """
+ Create a new roster item.
+
+ Arguments:
+ xmpp -- The main SleekXMPP instance.
+ jid -- The item's JID.
+ owner -- The roster owner's JID. Defaults
+ so self.xmpp.boundjid.bare.
+ state -- A dictionary of initial state values.
+ db -- An optional interface to an external datastore.
+ """
self.xmpp = xmpp
self.jid = jid
- self.owner = owner or self.xmpp.jid
+ self.owner = owner or self.xmpp.boundjid.bare
self.last_status = None
self.resources = {}
self.db = db
@@ -383,6 +394,10 @@ class RosterItem(object):
self.load()
def load(self):
+ """
+ Load the item's state information from an external datastore,
+ if one has been provided.
+ """
if self.db:
item = self.db.load(self.owner, self.jid,
self._db_state)
@@ -399,11 +414,16 @@ class RosterItem(object):
return None
def save(self):
+ """
+ Save the item's state information to an external datastore,
+ if one has been provided.
+ """
if self.db:
self.db.save(self.owner, self.jid,
self._state, self._db_state)
def __getitem__(self, key):
+ """Return a state field's value."""
if key in self._state:
if key == 'subscription':
return self._subscription()
@@ -412,7 +432,16 @@ class RosterItem(object):
raise KeyError
def __setitem__(self, key, value):
- print "%s: %s" % (key, value)
+ """
+ Set the value of a state field.
+
+ For boolean states, the values True, 'true', '1', 'on',
+ and 'yes' are accepted as True; all others are False.
+
+ Arguments:
+ key -- The state field to modify.
+ value -- The new value of the state field.
+ """
if key in self._state:
if key in ['name', 'subscription', 'groups']:
self._state[key] = value
@@ -423,6 +452,7 @@ class RosterItem(object):
raise KeyError
def _subscription(self):
+ """Return the proper subscription type based on current state."""
if self['to'] and self['from']:
return 'both'
elif self['from']:
@@ -434,8 +464,8 @@ class RosterItem(object):
def remove(self):
"""
- Remove the jids subscription, inform it if it is
- subscribed, and unwhitelist it.
+ Remove a JID's whitelisted status and unsubscribe if a
+ subscription exists.
"""
if self['to']:
p = self.xmpp.Presence()
@@ -449,6 +479,7 @@ class RosterItem(object):
self.save()
def subscribe(self):
+ """Send a subscription request to the JID."""
p = self.xmpp.Presence()
p['to'] = self.jid
p['type'] = 'subscribe'
@@ -459,6 +490,7 @@ class RosterItem(object):
p.send()
def authorize(self):
+ """Authorize a received subscription request from the JID."""
self['from'] = True
self['pending_in'] = False
self.save()
@@ -466,6 +498,7 @@ class RosterItem(object):
self.send_last_presence()
def unauthorize(self):
+ """Deny a received subscription request from the JID."""
self['from'] = False
self['pending_in'] = False
self.save()
@@ -478,6 +511,7 @@ class RosterItem(object):
p.send()
def _subscribed(self):
+ """Handle acknowledging a subscription."""
p = self.xmpp.Presence()
p['to'] = self.jid
p['type'] = 'subscribed'
@@ -486,6 +520,7 @@ class RosterItem(object):
p.send()
def unsubscribe(self):
+ """Unsubscribe from the JID."""
p = self.xmpp.Presence()
p['to'] = self.jid
p['type'] = 'unsubscribe'
@@ -495,6 +530,7 @@ class RosterItem(object):
p.send()
def _unsubscribed(self):
+ """Handle acknowledging an unsubscribe request."""
p = self.xmpp.Presence()
p['to'] = self.jid
p['type'] = 'unsubscribed'