From 4f69a03bb1a8caab7899bd04f97b7975a78f2f34 Mon Sep 17 00:00:00 2001
From: Lance Stout <lancestout@gmail.com>
Date: Wed, 27 Oct 2010 15:02:21 -0400
Subject: [PATCH] More cleanup.

---
 sleekxmpp/basexmpp.py |  1 -
 sleekxmpp/roster.py   | 43 ++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/sleekxmpp/basexmpp.py b/sleekxmpp/basexmpp.py
index 446871d..15a9156 100644
--- a/sleekxmpp/basexmpp.py
+++ b/sleekxmpp/basexmpp.py
@@ -548,7 +548,6 @@ class BaseXMPP(XMLStream):
         self.roster[presence['to'].bare][presence['from'].bare].handle_unavailable(presence)
 
     def _handle_new_subscription(self, stanza):
-        logging.debug(">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>")
         roster = self.roster[stanza['to'].bare]
         item = self.roster[stanza['to'].bare][stanza['from'].bare]
         if item['whitelisted']:
diff --git a/sleekxmpp/roster.py b/sleekxmpp/roster.py
index 77d2131..48f52de 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,6 +432,16 @@ class RosterItem(object):
             raise KeyError
 
     def __setitem__(self, 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.
+        """
         print "%s: %s" % (key, value)
         if key in self._state:
             if key in ['name', 'subscription', 'groups']:
@@ -423,6 +453,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 +465,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 +480,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 +491,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 +499,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 +512,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 +521,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 +531,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'