Add support for roster versioning.

This was XEP-0237, but is now part of RFC 6121.

Roster backends should now expose two additional methods:

version(jid):
    Return the version of the given JID's roster.
set_version(jid, version):
    Update the version of the given JID's roster.

A new state field will be passed to the backend if an item
has been marked for removal. This is 'removed' which will
be set to True.

2 files changed, 39 insertions, 1 deletions

diff --git a/sleekxmpp/roster/item.py b/sleekxmpp/roster/item.py
index eb2f64b3..9cb278a4 100644
--- a/sleekxmpp/roster/item.py
+++ b/sleekxmpp/roster/item.py
@@ -134,6 +134,7 @@ class RosterItem(object):
                 'subscription': 'none',
                 'name': '',
                 'groups': []}
+
         self._db_state = {}
         self.load()
 
@@ -171,16 +172,25 @@ class RosterItem(object):
             return self._state
         return None
 
-    def save(self):
+    def save(self, remove=False):
         """
         Save the item's state information to an external datastore,
         if one has been provided.
+
+        Arguments:
+            remove -- If True, expunge the item from the datastore.
         """
         self['subscription'] = self._subscription()
+        if remove:
+            self._state['removed'] = True
         if self.db:
             self.db.save(self.owner, self.jid,
                          self._state, self._db_state)
 
+        # Finally, remove the in-memory copy if needed.
+        if remove:
+            del self.xmpp.roster[self.owner][self.jid]
+
     def __getitem__(self, key):
         """Return a state field's value."""
         if key in self._state:
diff --git a/sleekxmpp/roster/single.py b/sleekxmpp/roster/single.py
index 159eb07d..518afebe 100644
--- a/sleekxmpp/roster/single.py
+++ b/sleekxmpp/roster/single.py
@@ -57,11 +57,28 @@ class RosterNode(object):
         self.auto_authorize = True
         self.auto_subscribe = True
         self.last_status = None
+        self._version = ''
         self._jids = {}
 
         if self.db:
+            if hasattr(self.db, 'version'):
+                self._version = self.db.version(self.jid)
             for jid in self.db.entries(self.jid):
                 self.add(jid)
+    
+    @property
+    def version(self):
+        """Retrieve the roster's version ID."""
+        if self.db and hasattr(self.db, 'version'):
+            self._version = self.db.version(self.jid)
+        return self._version
+
+    @version.setter
+    def version(self, version):
+        """Set the roster's version ID."""
+        self._version = version
+        if self.db and hasattr(self.db, 'set_version'):
+            self.db.set_version(self.jid, version)
 
     def __getitem__(self, key):
         """
@@ -75,6 +92,17 @@ class RosterNode(object):
             self.add(key, save=True)
         return self._jids[key]
 
+    def __delitem__(self, key):
+        """
+        Remove a roster item from the local storage.
+
+        To remove an item from the server, use the remove() method.
+        """
+        if isinstance(key, JID):
+            key = key.bare
+        if key in self._jids:
+            del self._jids[key]
+
     def __len__(self):
         """Return the number of JIDs referenced by the roster."""
         return len(self._jids)