diff options
| -rw-r--r-- | sleekxmpp/roster.py | 61 |
1 files changed, 59 insertions, 2 deletions
diff --git a/sleekxmpp/roster.py b/sleekxmpp/roster.py index de96296b..8b6af7d7 100644 --- a/sleekxmpp/roster.py +++ b/sleekxmpp/roster.py @@ -1,28 +1,82 @@ +""" + SleekXMPP: The Sleek XMPP Library + Copyright (C) 2010 Nathanael C. Fritz + This file is part of SleekXMPP. + + See the file LICENSE for copying permission. +""" + import logging 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. + + 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 -- An interface object to a datastore. + """ self.xmpp = xmpp self.db = db self._rosters = {} 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 key not in self._rosters: - self.add(key) + self.add(key, self.db) 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 node not in self._rosters: self._rosters[node] = RosterNode(self.xmpp, node, self.db) + class RosterNode(object): def __init__(self, xmpp, jid, db=None): @@ -169,7 +223,10 @@ class RosterItem(object): return 'none' def remove(self): - "Remove the jids subscription, inform it if it is subscribed, and unwhitelist it" + """ + Remove the jids subscription, inform it if it is + subscribed, and unwhitelist it. + """ if self['to']: p = self.xmpp.Presence() p['to'] = self.jid |