X-Git-Url: http://git.maemo.org/git/?p=python-purple;a=blobdiff_plain;f=purple.pyx;h=17411e78233f6ae7c2035846ba327b5f242f1219;hp=0005f73e3e5fd46104497ea5d039c58cb435ce4e;hb=39c1c26cdc38fe7dc79122c45bba7731b08ed1cd;hpb=99b9434bf3dee660cff5a0603eade5800f108803

diff --git a/purple.pyx b/purple.pyx
index 0005f73..17411e7 100644
--- a/purple.pyx
+++ b/purple.pyx
@@ -23,6 +23,7 @@ cdef extern from "c_purple.h":
     glib.guint glib_input_add(glib.gint fd, eventloop.PurpleInputCondition condition, eventloop.PurpleInputFunction function, glib.gpointer data)
 
 import ecore
+import signal
 
 cdef glib.GHashTable *c_ui_info
 
@@ -59,11 +60,17 @@ include "signal_cbs.pxd"
 include "util.pxd"
 
 cdef class Purple:
-    """ Purple class.
+    '''Purple class.
+
+    @param ui_name ID of the UI using the purple.
+        This should be a unique ID, registered with the purple team.
+    @param ui_version UI version.
+    @param ui_website UI website.
+    @param ui_dev_website UI development website.
+    @param debug_enabled True to enable debug messages.
+    @param default_path Custom settings directory
+    '''
 
-    @param debug_enabled: Toggle debug messages.
-    @param default_path: Full path for libpurple user files.
-    """
 
     def __init__(self, ui_name, ui_version, ui_website, ui_dev_website, \
             debug_enabled=None, default_path=None):
@@ -87,10 +94,21 @@ cdef class Purple:
         # adds glib iteration inside ecore main loop
         ecore.timer_add(0.001, self.__glib_iteration_when_idle)
 
+        # libpurple's built-in DNS resolution forks processes to perform
+        # blocking lookups without blocking the main process.  It does not
+        # handle SIGCHLD itself, so if the UI does not you quickly get an army
+        # of zombie subprocesses marching around.
+        signal.signal(signal.SIGCHLD, signal.SIG_IGN)
+
     def destroy(self):
         core.purple_core_quit()
 
     def __get_ui_name(self):
+        '''Returns the UI name.
+
+        @return UI name.
+        '''
+
         global c_ui_name
         return str(c_ui_name)
     ui_name = property(__get_ui_name)
@@ -156,7 +174,11 @@ cdef class Purple:
         return True
 
     def purple_init(self):
-        """ Initializes libpurple """
+        '''Initializes the purple.
+
+        This will setup preferences for all the core subsystems.
+        '''
+
         global c_ui_name
 
         c_account_ui_ops.notify_added = notify_added
@@ -259,13 +281,13 @@ cdef class Purple:
         return ret
 
     def add_callback(self, type, name, callback):
-        """
-        Adds a callback with given name inside callback's type.
+        '''Adds a callback with given name inside callback's type.
 
         @param type     Callback type (e.g. "account")
         @param name     Callback name (e.g. "notify-added")
         @param callback Callback to be called
-        """
+        '''
+
         global account_cbs
         global blist_cbs
         global connection_cbs
@@ -281,6 +303,14 @@ cdef class Purple:
           "request": request_cbs }[type][name] = callback
 
     def signal_connect(self, name=None, cb=None):
+        '''Connects a signal handler to a signal for a particular object.
+        Take care not to register a handler function twice. Purple will
+        not correct any mistakes for you in this area.
+
+        @param name Name of the signal to connect.
+        @param cb Callback function.
+        '''
+
         cdef int handle
         cdef plugin.PurplePlugin *jabber
 
@@ -330,6 +360,11 @@ cdef class Purple:
                     <signals.PurpleCallback> jabber_receiving_xmlnode_cb, NULL)
 
     def accounts_get_all(self):
+        '''Returns a list of all accounts.
+
+        @return A list of all accounts.
+        '''
+
         cdef glib.GList *iter
         cdef account.PurpleAccount *acc
         cdef char *username
@@ -353,11 +388,19 @@ cdef class Purple:
         return account_list
 
     def accounts_get_all_active(self):
+        '''Returns a list of all enabled accounts.
+
+        @return A list of all enabled accounts.
+        '''
+
         cdef glib.GList *iter
         cdef account.PurpleAccount *acc
         cdef char *username
         cdef char *protocol_id
 
+        #FIXME: The list is owned by the caller, and must be g_list_free()d
+        #       to avoid leaking the nodes.
+
         iter = account.purple_accounts_get_all_active()
         account_list = []
 
@@ -376,6 +419,11 @@ cdef class Purple:
         return account_list
 
     def protocols_get_all(self):
+        '''Returns a list of all protocols.
+
+        @return A list of all protocols.
+        '''
+
         cdef glib.GList *iter
         cdef plugin.PurplePlugin *pp
 
@@ -388,6 +436,9 @@ cdef class Purple:
             iter = iter.next
         return protocol_list
 
+    def call_action(self, i):
+        __call_action(i)
+
 include "protocol.pyx"
 #include "plugin.pyx"
 include "proxy.pyx"