From 12ead36f9642aebf100d9ed749108e449aa29158 Mon Sep 17 00:00:00 2001
From: Lance Stout <lancestout@gmail.com>
Date: Wed, 27 Oct 2010 10:51:58 -0400
Subject: Added more docs.
---
sleekxmpp/roster.py | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 107 insertions(+), 1 deletion(-)
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
--
cgit v1.2.3