summaryrefslogtreecommitdiff
path: root/sleekxmpp
diff options
context:
space:
mode:
Diffstat (limited to 'sleekxmpp')
-rw-r--r--sleekxmpp/roster/__init__.py12
-rw-r--r--sleekxmpp/roster/item.py (renamed from sleekxmpp/roster.py)322
-rw-r--r--sleekxmpp/roster/multi.py115
-rw-r--r--sleekxmpp/roster/single.py222
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()