Split roster.py into a directory.

4 files changed, 349 insertions, 322 deletions

diff --git a/sleekxmpp/roster/__init__.py b/sleekxmpp/roster/__init__.py
new file mode 100644
index 00000000..4335d367
--- /dev/null
+++ b/sleekxmpp/roster/__init__.py
@@ -0,0 +1,12 @@
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2010  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+from sleekxmpp.xmlstream import JID
+from sleekxmpp.roster.item import RosterItem
+from sleekxmpp.roster.single import RosterNode
+from sleekxmpp.roster.multi import Roster
diff --git a/sleekxmpp/roster.py b/sleekxmpp/roster/item.py
index 55af1e46..eb115a4a 100644
--- a/sleekxmpp/roster.py
+++ b/sleekxmpp/roster/item.py
@@ -6,328 +6,6 @@
     See the file LICENSE for copying permission.
 """
 
-import logging
-
-from sleekxmpp.xmlstream import JID
-
-
-class Roster(object):
-
-    """
-    SleekXMPP's roster manager.
-
-    The roster is divided into "nodes", where each node is responsible
-    for a single JID. While the distinction is not strictly necessary
-    for client connections, it is a necessity for components that use
-    multiple JIDs.
-
-    Rosters may be stored and persisted in an external datastore. An
-    interface object to the datastore that loads and saves roster items may
-    be provided. See the documentation for the RosterItem class for the
-    methods that the datastore interface object must provide.
-
-    Attributes:
-        xmpp           -- The main SleekXMPP instance.
-        db             -- Optional interface object to an external datastore.
-        auto_authorize -- Default auto_authorize value for new roster nodes.
-                          Defaults to True.
-        auto_subscribe -- Default auto_subscribe value for new roster nodes.
-                          Defaults to True.
-
-    Methods:
-        add -- Create a new roster node for a JID.
-    """
-
-    def __init__(self, xmpp, db=None):
-        """
-        Create a new roster.
-
-        Arguments:
-            xmpp -- The main SleekXMPP instance.
-            db   -- Optional interface object to a datastore.
-        """
-        self.xmpp = xmpp
-        self.db = db
-        self.auto_authorize = True
-        self.auto_subscribe = True
-        self._rosters = {}
-
-        if self.db:
-            for node in self.db.entries(None, {}):
-                self.add(node)
-
-    def __getitem__(self, key):
-        """
-        Return the roster node for a JID.
-
-        A new roster node will be created if one
-        does not already exist.
-
-        Arguments:
-            key -- Return the roster for this JID.
-        """
-        if isinstance(key, JID):
-            key = key.bare
-        if key not in self._rosters:
-            self.add(key)
-            self._rosters[key].auto_authorize = self.auto_authorize
-            self._rosters[key].auto_subscribe = self.auto_subscribe
-        return self._rosters[key]
-
-    def keys(self):
-        """Return the JIDs managed by the roster."""
-        return self._rosters.keys()
-
-    def __iter__(self):
-        """Iterate over the roster nodes."""
-        return self._rosters.__iter__()
-
-    def add(self, node):
-        """
-        Add a new roster node for the given JID.
-
-        Arguments:
-            node -- The JID for the new roster node.
-        """
-        if isinstance(node, JID):
-            node = node.bare
-        if node not in self._rosters:
-            self._rosters[node] = RosterNode(self.xmpp, node, self.db)
-
-    def set_backend(self, db=None):
-        """
-        Set the datastore interface object for the roster.
-
-        Arguments:
-            db -- The new datastore interface.
-        """
-        self.db = db
-        for node in self.db.entries(None, {}):
-            self.add(node)
-        for node in self._rosters:
-            self._rosters[node].set_backend(db)
-
-    def reset(self):
-        """
-        Reset the state of the roster to forget any current
-        presence information. Useful after a disconnection occurs.
-        """
-        for node in self:
-            self[node].reset()
-
-
-class RosterNode(object):
-
-    """
-    A roster node is a roster for a single JID.
-
-    Attributes:
-        xmpp           -- The main SleekXMPP instance.
-        jid            -- The JID that owns the roster node.
-        db             -- Optional interface to an external datastore.
-        auto_authorize -- Determines how authorizations are handled:
-                            True  -- Accept all subscriptions.
-                            False -- Reject all subscriptions.
-                            None  -- Subscriptions must be
-                                     manually authorized.
-                          Defaults to True.
-        auto_subscribe -- Determines if bi-directional subscriptions
-                          are created after automatically authrorizing
-                          a subscription request.
-                          Defaults to True
-
-    Methods:
-        add         -- Add a JID to the roster.
-        update      -- Update a JID's subscription information.
-        subscribe   -- Subscribe to a JID.
-        unsubscribe -- Unsubscribe from a JID.
-        remove      -- Remove a JID from the roster.
-        presence    -- Return presence information for a JID's resources.
-    """
-
-    def __init__(self, xmpp, jid, db=None):
-        """
-        Create a roster node for a JID.
-
-        Arguments:
-            xmpp -- The main SleekXMPP instance.
-            jid  -- The JID that owns the roster.
-            db   -- Optional interface to an external datastore.
-        """
-        self.xmpp = xmpp
-        self.jid = jid
-        self.db = db
-        self.auto_authorize = True
-        self.auto_subscribe = True
-        self._jids = {}
-
-        if self.db:
-            for jid in self.db.entries(self.jid):
-                self.add(jid)
-
-    def __getitem__(self, key):
-        """
-        Return the roster item for a subscribed JID.
-
-        A new item entry will be created if one does not already exist.
-        """
-        if isinstance(key, JID):
-            key = key.bare
-        if key not in self._jids:
-            self.add(key, save=True)
-        return self._jids[key]
-
-    def keys(self):
-        """Return a list of all subscribed JIDs."""
-        return self._jids.keys()
-
-    def has_jid(self, jid):
-        """Returns whether the roster has a JID."""
-        return jid in self._jids
-
-    def __iter__(self):
-        """Iterate over the roster items."""
-        return self._jids.__iter__()
-
-    def set_backend(self, db=None):
-        """
-        Set the datastore interface object for the roster node.
-
-        Arguments:
-            db -- The new datastore interface.
-        """
-        self.db = db
-        for jid in self.db.entries(self.jid):
-            self.add(jid)
-        for jid in self._jids:
-            self._jids[jid].set_backend(db)
-
-    def add(self, jid, name='', groups=None, afrom=False, ato=False,
-            pending_in=False, pending_out=False, whitelisted=False,
-            save=False):
-        """
-        Add a new roster item entry.
-
-        Arguments:
-            jid         -- The JID for the roster item.
-            name        -- An alias for the JID.
-            groups      -- A list of group names.
-            afrom       -- Indicates if the JID has a subscription state
-                           of 'from'. Defaults to False.
-            ato         -- Indicates if the JID has a subscription state
-                           of 'to'. Defaults to False.
-            pending_in  -- Indicates if the JID has sent a subscription
-                           request to this connection's JID.
-                           Defaults to False.
-            pending_out -- Indicates if a subscription request has been sent
-                           to this JID.
-                           Defaults to False.
-            whitelisted -- Indicates if a subscription request from this JID
-                           should be automatically authorized.
-                           Defaults to False.
-            save        -- Indicates if the item should be persisted
-                           immediately to an external datastore,
-                           if one is used.
-                           Defaults to False.
-        """
-        if isinstance(jid, JID):
-            key = jid.bare
-        state = {'name': name,
-                 'groups': groups or [],
-                 'from': afrom,
-                 'to': ato,
-                 'pending_in': pending_in,
-                 'pending_out': pending_out,
-                 'whitelisted': whitelisted,
-                 'subscription': 'none'}
-        self._jids[jid] = RosterItem(self.xmpp, jid, self.jid,
-                                     state=state, db=self.db)
-        if save:
-            self._jids[jid].save()
-
-    def subscribe(self, jid):
-        """
-        Subscribe to the given JID.
-
-        Arguments:
-            jid -- The JID to subscribe to.
-        """
-        self[jid].subscribe()
-
-    def unsubscribe(self, jid):
-        """
-        Unsubscribe from the given JID.
-
-        Arguments:
-            jid -- The JID to unsubscribe from.
-        """
-        self[jid].unsubscribe()
-
-    def remove(self, jid):
-        """
-        Remove a JID from the roster.
-
-        Arguments:
-            jid -- The JID to remove.
-        """
-        self[jid].remove()
-        if not self.xmpp.is_component:
-            self.update(jid, subscription='remove')
-
-    def update(self, jid, name=None, subscription=None, groups=[]):
-        """
-        Update a JID's subscription information.
-
-        Arguments:
-            jid          -- The JID to update.
-            name         -- Optional alias for the JID.
-            subscription -- The subscription state. May be one of: 'to',
-                            'from', 'both', 'none', or 'remove'.
-            groups       -- A list of group names.
-        """
-        self[jid]['name'] = name
-        self[jid]['groups'] = group
-        self[jid].save()
-
-        if not self.xmpp.is_component:
-            iq = self.Iq()
-            iq['type'] = 'set'
-            iq['roster']['items'] = {jid: {'name': name,
-                                           'subscription': subscription,
-                                           'groups': groups}}
-            response = iq.send()
-            return response and response['type'] == 'result'
-
-    def presence(self, jid, resource=None):
-        """
-        Retrieve the presence information of a JID.
-
-        May return either all online resources' status, or
-        a single resource's status.
-
-        Arguments:
-            jid      -- The JID to lookup.
-            resource -- Optional resource for returning
-                        only the status of a single connection.
-        """
-        if resource is None:
-            return self[jid].resources
-
-        default_presence = {'status': '',
-                            'priority': 0,
-                            'show': ''}
-        return self[jid].resources.get(resource,
-                                       default_presence)
-
-    def reset(self):
-        """
-        Reset the state of the roster to forget any current
-        presence information. Useful after a disconnection occurs.
-        """
-        for jid in self:
-            self[jid].reset()
-
-
 
 class RosterItem(object):
 
diff --git a/sleekxmpp/roster/multi.py b/sleekxmpp/roster/multi.py
new file mode 100644
index 00000000..cd4a5195
--- /dev/null
+++ b/sleekxmpp/roster/multi.py
@@ -0,0 +1,115 @@
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2010  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+from sleekxmpp.xmlstream import JID
+from sleekxmpp.roster import RosterNode
+
+
+class Roster(object):
+
+    """
+    SleekXMPP's roster manager.
+
+    The roster is divided into "nodes", where each node is responsible
+    for a single JID. While the distinction is not strictly necessary
+    for client connections, it is a necessity for components that use
+    multiple JIDs.
+
+    Rosters may be stored and persisted in an external datastore. An
+    interface object to the datastore that loads and saves roster items may
+    be provided. See the documentation for the RosterItem class for the
+    methods that the datastore interface object must provide.
+
+    Attributes:
+        xmpp           -- The main SleekXMPP instance.
+        db             -- Optional interface object to an external datastore.
+        auto_authorize -- Default auto_authorize value for new roster nodes.
+                          Defaults to True.
+        auto_subscribe -- Default auto_subscribe value for new roster nodes.
+                          Defaults to True.
+
+    Methods:
+        add -- Create a new roster node for a JID.
+    """
+
+    def __init__(self, xmpp, db=None):
+        """
+        Create a new roster.
+
+        Arguments:
+            xmpp -- The main SleekXMPP instance.
+            db   -- Optional interface object to a datastore.
+        """
+        self.xmpp = xmpp
+        self.db = db
+        self.auto_authorize = True
+        self.auto_subscribe = True
+        self._rosters = {}
+
+        if self.db:
+            for node in self.db.entries(None, {}):
+                self.add(node)
+
+    def __getitem__(self, key):
+        """
+        Return the roster node for a JID.
+
+        A new roster node will be created if one
+        does not already exist.
+
+        Arguments:
+            key -- Return the roster for this JID.
+        """
+        if isinstance(key, JID):
+            key = key.bare
+        if key not in self._rosters:
+            self.add(key)
+            self._rosters[key].auto_authorize = self.auto_authorize
+            self._rosters[key].auto_subscribe = self.auto_subscribe
+        return self._rosters[key]
+
+    def keys(self):
+        """Return the JIDs managed by the roster."""
+        return self._rosters.keys()
+
+    def __iter__(self):
+        """Iterate over the roster nodes."""
+        return self._rosters.__iter__()
+
+    def add(self, node):
+        """
+        Add a new roster node for the given JID.
+
+        Arguments:
+            node -- The JID for the new roster node.
+        """
+        if isinstance(node, JID):
+            node = node.bare
+        if node not in self._rosters:
+            self._rosters[node] = RosterNode(self.xmpp, node, self.db)
+
+    def set_backend(self, db=None):
+        """
+        Set the datastore interface object for the roster.
+
+        Arguments:
+            db -- The new datastore interface.
+        """
+        self.db = db
+        for node in self.db.entries(None, {}):
+            self.add(node)
+        for node in self._rosters:
+            self._rosters[node].set_backend(db)
+
+    def reset(self):
+        """
+        Reset the state of the roster to forget any current
+        presence information. Useful after a disconnection occurs.
+        """
+        for node in self:
+            self[node].reset()
diff --git a/sleekxmpp/roster/single.py b/sleekxmpp/roster/single.py
new file mode 100644
index 00000000..6ce44e8f
--- /dev/null
+++ b/sleekxmpp/roster/single.py
@@ -0,0 +1,222 @@
+"""
+    SleekXMPP: The Sleek XMPP Library
+    Copyright (C) 2010  Nathanael C. Fritz
+    This file is part of SleekXMPP.
+
+    See the file LICENSE for copying permission.
+"""
+
+from sleekxmpp.xmlstream import JID
+from sleekxmpp.roster import RosterItem
+
+
+class RosterNode(object):
+
+    """
+    A roster node is a roster for a single JID.
+
+    Attributes:
+        xmpp           -- The main SleekXMPP instance.
+        jid            -- The JID that owns the roster node.
+        db             -- Optional interface to an external datastore.
+        auto_authorize -- Determines how authorizations are handled:
+                            True  -- Accept all subscriptions.
+                            False -- Reject all subscriptions.
+                            None  -- Subscriptions must be
+                                     manually authorized.
+                          Defaults to True.
+        auto_subscribe -- Determines if bi-directional subscriptions
+                          are created after automatically authrorizing
+                          a subscription request.
+                          Defaults to True
+
+    Methods:
+        add         -- Add a JID to the roster.
+        update      -- Update a JID's subscription information.
+        subscribe   -- Subscribe to a JID.
+        unsubscribe -- Unsubscribe from a JID.
+        remove      -- Remove a JID from the roster.
+        presence    -- Return presence information for a JID's resources.
+    """
+
+    def __init__(self, xmpp, jid, db=None):
+        """
+        Create a roster node for a JID.
+
+        Arguments:
+            xmpp -- The main SleekXMPP instance.
+            jid  -- The JID that owns the roster.
+            db   -- Optional interface to an external datastore.
+        """
+        self.xmpp = xmpp
+        self.jid = jid
+        self.db = db
+        self.auto_authorize = True
+        self.auto_subscribe = True
+        self._jids = {}
+
+        if self.db:
+            for jid in self.db.entries(self.jid):
+                self.add(jid)
+
+    def __getitem__(self, key):
+        """
+        Return the roster item for a subscribed JID.
+
+        A new item entry will be created if one does not already exist.
+        """
+        if isinstance(key, JID):
+            key = key.bare
+        if key not in self._jids:
+            self.add(key, save=True)
+        return self._jids[key]
+
+    def keys(self):
+        """Return a list of all subscribed JIDs."""
+        return self._jids.keys()
+
+    def has_jid(self, jid):
+        """Returns whether the roster has a JID."""
+        return jid in self._jids
+
+    def __iter__(self):
+        """Iterate over the roster items."""
+        return self._jids.__iter__()
+
+    def set_backend(self, db=None):
+        """
+        Set the datastore interface object for the roster node.
+
+        Arguments:
+            db -- The new datastore interface.
+        """
+        self.db = db
+        for jid in self.db.entries(self.jid):
+            self.add(jid)
+        for jid in self._jids:
+            self._jids[jid].set_backend(db)
+
+    def add(self, jid, name='', groups=None, afrom=False, ato=False,
+            pending_in=False, pending_out=False, whitelisted=False,
+            save=False):
+        """
+        Add a new roster item entry.
+
+        Arguments:
+            jid         -- The JID for the roster item.
+            name        -- An alias for the JID.
+            groups      -- A list of group names.
+            afrom       -- Indicates if the JID has a subscription state
+                           of 'from'. Defaults to False.
+            ato         -- Indicates if the JID has a subscription state
+                           of 'to'. Defaults to False.
+            pending_in  -- Indicates if the JID has sent a subscription
+                           request to this connection's JID.
+                           Defaults to False.
+            pending_out -- Indicates if a subscription request has been sent
+                           to this JID.
+                           Defaults to False.
+            whitelisted -- Indicates if a subscription request from this JID
+                           should be automatically authorized.
+                           Defaults to False.
+            save        -- Indicates if the item should be persisted
+                           immediately to an external datastore,
+                           if one is used.
+                           Defaults to False.
+        """
+        if isinstance(jid, JID):
+            key = jid.bare
+        state = {'name': name,
+                 'groups': groups or [],
+                 'from': afrom,
+                 'to': ato,
+                 'pending_in': pending_in,
+                 'pending_out': pending_out,
+                 'whitelisted': whitelisted,
+                 'subscription': 'none'}
+        self._jids[jid] = RosterItem(self.xmpp, jid, self.jid,
+                                     state=state, db=self.db)
+        if save:
+            self._jids[jid].save()
+
+    def subscribe(self, jid):
+        """
+        Subscribe to the given JID.
+
+        Arguments:
+            jid -- The JID to subscribe to.
+        """
+        self[jid].subscribe()
+
+    def unsubscribe(self, jid):
+        """
+        Unsubscribe from the given JID.
+
+        Arguments:
+            jid -- The JID to unsubscribe from.
+        """
+        self[jid].unsubscribe()
+
+    def remove(self, jid):
+        """
+        Remove a JID from the roster.
+
+        Arguments:
+            jid -- The JID to remove.
+        """
+        self[jid].remove()
+        if not self.xmpp.is_component:
+            self.update(jid, subscription='remove')
+
+    def update(self, jid, name=None, subscription=None, groups=[]):
+        """
+        Update a JID's subscription information.
+
+        Arguments:
+            jid          -- The JID to update.
+            name         -- Optional alias for the JID.
+            subscription -- The subscription state. May be one of: 'to',
+                            'from', 'both', 'none', or 'remove'.
+            groups       -- A list of group names.
+        """
+        self[jid]['name'] = name
+        self[jid]['groups'] = group
+        self[jid].save()
+
+        if not self.xmpp.is_component:
+            iq = self.Iq()
+            iq['type'] = 'set'
+            iq['roster']['items'] = {jid: {'name': name,
+                                           'subscription': subscription,
+                                           'groups': groups}}
+            response = iq.send()
+            return response and response['type'] == 'result'
+
+    def presence(self, jid, resource=None):
+        """
+        Retrieve the presence information of a JID.
+
+        May return either all online resources' status, or
+        a single resource's status.
+
+        Arguments:
+            jid      -- The JID to lookup.
+            resource -- Optional resource for returning
+                        only the status of a single connection.
+        """
+        if resource is None:
+            return self[jid].resources
+
+        default_presence = {'status': '',
+                            'priority': 0,
+                            'show': ''}
+        return self[jid].resources.get(resource,
+                                       default_presence)
+
+    def reset(self):
+        """
+        Reset the state of the roster to forget any current
+        presence information. Useful after a disconnection occurs.
+        """
+        for jid in self:
+            self[jid].reset()