diff options
Diffstat (limited to 'sleekxmpp')
| -rw-r--r-- | sleekxmpp/roster/__init__.py | 12 | ||||
| -rw-r--r-- | sleekxmpp/roster/item.py (renamed from sleekxmpp/roster.py) | 322 | ||||
| -rw-r--r-- | sleekxmpp/roster/multi.py | 115 | ||||
| -rw-r--r-- | sleekxmpp/roster/single.py | 222 |
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() |