Documentation for the activity and buddy presence objects

2 files changed, 119 insertions, 2 deletions

diff --git a/sugar/presence/activity.py b/sugar/presence/activity.py
index 1616378..f290368 100644
--- a/sugar/presence/activity.py
+++ b/sugar/presence/activity.py
@@ -1,3 +1,4 @@
+"""UI interface to an activity in the presence service"""
 # Copyright (C) 2007, Red Hat, Inc.
 #
 # This library is free software; you can redistribute it and/or
@@ -19,7 +20,19 @@ import gobject
 import dbus
 
 class Activity(gobject.GObject):
-
+    """UI interface for an Activity in the presence service
+    
+    Activities in the presence service represent other user's
+    shared activities and your own activities (XXX shared or 
+    otherwise?)
+    
+    Properties:
+        id 
+        color 
+        name 
+        type 
+        joined 
+    """
     __gsignals__ = {
         'buddy-joined': (gobject.SIGNAL_RUN_FIRST, gobject.TYPE_NONE,
                          ([gobject.TYPE_PYOBJECT])),
@@ -33,6 +46,7 @@ class Activity(gobject.GObject):
     _ACTIVITY_DBUS_INTERFACE = "org.laptop.Sugar.Presence.Activity"
 
     def __init__(self, bus, new_obj_cb, del_obj_cb, object_path):
+        """Initialse the activity interface, connecting to service"""
         gobject.GObject.__init__(self)
         self._object_path = object_path
         self._ps_new_object = new_obj_cb
@@ -50,9 +64,11 @@ class Activity(gobject.GObject):
         self._joined = False
 
     def object_path(self):
+        """Get our dbus object path"""
         return self._object_path
 
     def _emit_buddy_joined_signal(self, object_path):
+        """Generate buddy-joined GObject signal with presence Buddy object"""
         self.emit('buddy-joined', self._ps_new_object(object_path))
         return False
 
@@ -60,6 +76,10 @@ class Activity(gobject.GObject):
         gobject.idle_add(self._emit_buddy_joined_signal, object_path)
 
     def _emit_buddy_left_signal(self, object_path):
+        """Generate buddy-left GObject signal with presence Buddy object
+        
+        XXX note use of _ps_new_object instead of _ps_del_object here
+        """
         self.emit('buddy-left', self._ps_new_object(object_path))
         return False
 
@@ -67,6 +87,10 @@ class Activity(gobject.GObject):
         gobject.idle_add(self._emit_buddy_left_signal, object_path)
 
     def _emit_new_channel_signal(self, object_path):
+        """Generate new-channel GObject signal with channel object path 
+        
+        New telepathy-python communications channel has been opened
+        """
         self.emit('new-channel', object_path)
         return False
 
@@ -74,27 +98,35 @@ class Activity(gobject.GObject):
         gobject.idle_add(self._emit_new_channel_signal, object_path)
 
     def get_id(self):
+        """Retrieve the unique identifier for this activity instance"""
         # Cache activity ID, which should never change anyway
         if not self._id:
             self._id = self._activity.GetId()
         return self._id
 
     def get_color(self):
+        """Retrieve the activity icon colour for this activity instance"""
         if not self._color:
             self._color = self._activity.GetColor()
         return self._color
 
     def get_name(self):
+        """Retrieve the activity name for this activity instance"""
         if not self._name:
             self._name = self._activity.GetName()
         return self._name
 
     def get_type(self):
+        """Retrieve the activity/bundle type for this activity instance"""
         if not self._type:
             self._type = self._activity.GetType()
         return self._type
 
     def get_joined_buddies(self):
+        """Retrieve the set of Buddy objects attached to this activity
+        
+        returns list of presence Buddy objects
+        """
         resp = self._activity.GetJoinedBuddies()
         buddies = []
         for item in resp:
@@ -102,15 +134,26 @@ class Activity(gobject.GObject):
         return buddies
 
     def join(self):
+        """Join this activity 
+        
+        XXX if these are all activities, can I join my own activity?
+        """
         if self._joined:
             return
         self._activity.Join()
         self._joined = True
 
     def get_channels(self):
+        """Retrieve communications channel descriptions for the activity 
+        
+        Returns (bus name, connection, channels) for the activity
+        
+        XXX what are those values?
+        """
         (bus_name, connection, channels) = self._activity.GetChannels()
         return bus_name, connection, channels
 
     def owner_has_joined(self):
+        """Retrieve whether the owner of the activity is active within it"""
         # FIXME
         return False
diff --git a/sugar/presence/buddy.py b/sugar/presence/buddy.py
index c6f51d5..048f3ea 100644
--- a/sugar/presence/buddy.py
+++ b/sugar/presence/buddy.py
@@ -1,3 +1,4 @@
+"""UI interface to a buddy in the presence service"""
 # Copyright (C) 2007, Red Hat, Inc.
 #
 # This library is free software; you can redistribute it and/or
@@ -20,13 +21,33 @@ import gtk
 import dbus
 
 def _bytes_to_string(bytes):
+    """Convertes an short-int (char) array to a string
+    
+    returns string or None for a null sequence
+    """
     if len(bytes):
+        # if there's an internal buffer, we could use 
+        # ctypes to pull it out without this...
         return ''.join([chr(item) for item in bytes])
     return None
 
 
 class Buddy(gobject.GObject):
-
+    """UI interface for a Buddy in the presence service
+    
+    Each buddy interface tracks a set of activities and properties
+    that can be queried to provide UI controls for manipulating 
+    the presence interface.
+    
+    Properties Dictionary:
+        'key': public key, 
+        'nick': nickname , 
+        'color': color (XXX what format), 
+        'current-activity': (XXX dbus path?), 
+        'owner': (XXX dbus path?), 
+        'icon': (XXX pixel data for an icon?)
+    See __gproperties__
+    """
     __gsignals__ = {
         'icon-changed': (gobject.SIGNAL_RUN_FIRST, gobject.TYPE_NONE,
                          ([])),
@@ -51,6 +72,13 @@ class Buddy(gobject.GObject):
     _BUDDY_DBUS_INTERFACE = "org.laptop.Sugar.Presence.Buddy"
 
     def __init__(self, bus, new_obj_cb, del_obj_cb, object_path):
+        """Initialise the reference to the buddy
+        
+        bus -- dbus bus object 
+        new_obj_cb -- callback to call when this buddy joins an activity 
+        del_obj_cb -- callback to call when this buddy leaves an activity 
+        object_path -- path to the buddy object 
+        """
         gobject.GObject.__init__(self)
         self._object_path = object_path
         self._ps_new_object = new_obj_cb
@@ -68,12 +96,19 @@ class Buddy(gobject.GObject):
         self._icon = None
 
     def _get_properties_helper(self):
+        """Retrieve the Buddy's property dictionary from the service object
+        """
         props = self._buddy.GetProperties()
         if not props:
             return {}
         return props
 
     def do_get_property(self, pspec):
+        """Retrieve a particular property from our property dictionary 
+        
+        pspec -- XXX some sort of GTK specifier object with attributes
+            including 'name', 'active' and 'icon-name'
+        """
         if pspec.name == "key":
             return self._properties["key"]
         elif pspec.name == "nick":
@@ -97,48 +132,79 @@ class Buddy(gobject.GObject):
             return self._icon
 
     def object_path(self):
+        """Retrieve our dbus object path"""
         return self._object_path
 
     def _emit_icon_changed_signal(self, bytes):
+        """Emit GObject signal when icon has changed"""
         self._icon = _bytes_to_string(bytes)
         self.emit('icon-changed')
         return False
 
     def _icon_changed_cb(self, icon_data):
+        """Handle dbus signal by emitting a GObject signal"""
         gobject.idle_add(self._emit_icon_changed_signal, icon_data)
 
     def _emit_joined_activity_signal(self, object_path):
+        """Emit activity joined signal with Activity object"""
         self.emit('joined-activity', self._ps_new_object(object_path))
         return False
 
     def _joined_activity_cb(self, object_path):
+        """Handle dbus signal by emitting a GObject signal
+        
+        Stores the activity in activities dictionary as well
+        """
         if not self._activities.has_key(object_path):
             self._activities[object_path] = self._ps_new_object(object_path)
         gobject.idle_add(self._emit_joined_activity_signal, object_path)
 
     def _emit_left_activity_signal(self, object_path):
+        """Emit activity left signal with Activity object
+        
+        XXX this calls self._ps_new_object instead of self._ps_del_object,
+            which would seem to be the incorrect callback?
+        """
         self.emit('left-activity', self._ps_new_object(object_path))
         return False
 
     def _left_activity_cb(self, object_path):
+        """Handle dbus signal by emitting a GObject signal
+        
+        Also removes from the activities dictionary
+        """
         if self._activities.has_key(object_path):
             del self._activities[object_path]
         gobject.idle_add(self._emit_left_activity_signal, object_path)
 
     def _handle_property_changed_signal(self, prop_list):
+        """Emit property-changed signal with property dictionary 
+        
+        Generates a property-changed signal with the results of 
+        _get_properties_helper()
+        """
         self._properties = self._get_properties_helper()
         # FIXME: don't leak unexposed property names
         self.emit('property-changed', prop_list)
         return False
 
     def _property_changed_cb(self, prop_list):
+        """Handle dbus signal by emitting a GObject signal"""
         gobject.idle_add(self._handle_property_changed_signal, prop_list)
 
     def get_icon_pixbuf(self):
+        """Retrieve Buddy's icon as a GTK pixel buffer
+        
+        XXX Why aren't the icons coming in as SVG?
+        """
         if self.props.icon and len(self.props.icon):
             pbl = gtk.gdk.PixbufLoader()
             icon_data = ""
             for item in self.props.icon:
+                # XXX this is a slow way to convert the data 
+                # under Python 2.5 and below, collect in a 
+                # list and then join with "", see 
+                # _bytes_to_string in this module
                 icon_data = icon_data + chr(item)
             pbl.write(icon_data)
             pbl.close()
@@ -147,6 +213,14 @@ class Buddy(gobject.GObject):
             return None
 
     def get_joined_activities(self):
+        """Retrieve the set of all activities which this buddy has joined 
+        
+        Uses the GetJoinedActivities method on the service 
+        object to produce object paths, wraps each in an 
+        Activity object.  
+        
+        returns list of presence Activity objects
+        """
         try:
             resp = self._buddy.GetJoinedActivities()
         except dbus.exceptions.DBusException: