Documentation for the activity and buddy presence objects

1 files changed, 75 insertions, 1 deletions

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: