diff options
| -rw-r--r-- | sleekxmpp/roster.py | 108 |
1 files changed, 107 insertions, 1 deletions
diff --git a/sleekxmpp/roster.py b/sleekxmpp/roster.py index 8b6af7d7..cced86bf 100644 --- a/sleekxmpp/roster.py +++ b/sleekxmpp/roster.py @@ -38,7 +38,7 @@ class Roster(object): Arguments: xmpp -- The main SleekXMPP instance. - db -- An interface object to a datastore. + db -- Optional interface object to a datastore. """ self.xmpp = xmpp self.db = db @@ -79,7 +79,41 @@ class Roster(object): class RosterNode(object): + """ + + 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 @@ -88,19 +122,52 @@ class RosterNode(object): self._jids = {} 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 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 __iter__(self): + """Iterate over the roster items.""" return self._jids.__iter__() 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. + """ + state = {'name': name, 'groups': groups or [], 'from': afrom, @@ -115,17 +182,45 @@ class RosterNode(object): self._jids[jid].save() def subscribe(self, jid): + """ + Subscribe to the given JID. + + Arguments: + jid -- The JID to subscribe to. + """ self._jids[jid].subscribe() def unsubscribe(self, jid): + """ + Unsubscribe from the given JID. + + Arguments: + jid -- The JID to unsubscribe from. + """ self._jids[jid].unsubscribe() def remove(self, jid): + """ + Remove a JID from the roster. + + Arguments: + jid -- The JID to remove. + """ self._jids[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._jids[jid]['name'] = name self._jids[jid]['groups'] = group self._jids[jid].save() @@ -140,6 +235,17 @@ class RosterNode(object): 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._jids[jid].resources |