From 3453e9755aca10e51bb7ce6b7a665ee461aad1de Mon Sep 17 00:00:00 2001 From: Ragner Magalhaes Date: Tue, 16 Dec 2008 13:14:00 +0000 Subject: [PATCH] Adding comments to buddy class Adding comments to buddy class Signed-off-by: Ragner Magalhaes git-svn-id: https://garage.maemo.org/svn/carman/branches/carman-0.7-beta2/python-purple@1720 596f6dd7-e928-0410-a184-9e12fd12cf7e --- buddy.pyx | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 98 insertions(+), 15 deletions(-) diff --git a/buddy.pyx b/buddy.pyx index be9f2bd..a464b37 100644 --- a/buddy.pyx +++ b/buddy.pyx @@ -20,11 +20,11 @@ cimport purple cdef class Buddy: - """ - Buddy class - @param name - @param account - """ + '''Buddy class + + @param name Buddy's name. + @param account Buddy's account. + ''' cdef object __account cdef object __name @@ -40,29 +40,42 @@ cdef class Buddy: self.__exists = False cdef blist.PurpleBuddy *_get_structure(self): + '''Returns the buddy's C struct from purple. + + @return A pointer to buddy's C struct from purple. + ''' + return blist.purple_find_buddy(account.purple_accounts_find( \ self.__account.username, self.__account.protocol.id), \ self.__name) def __get_exists(self): + '''Answer if exists corresponding buddy in the purple. + + @return True if buddy is a valid buddy of False otherwise. + ''' + return self.__exists exists = property(__get_exists) def __get_name(self): + '''Returns the buddy's name. + + @return Buddy's name. + ''' + if self.__exists: return blist.purple_buddy_get_name(self._get_structure()) else: return self.__name name = property(__get_name) - def __get_account(self): - if self.__exists: - return self.__account - else: - return None - account = property(__get_account) - def __get_alias(self): + '''Returns the buddy's alias + + @return Buddy alias(if set) or None + ''' + cdef char *c_alias = NULL c_alias = blist.purple_buddy_get_alias_only( \ self._get_structure()) @@ -72,7 +85,24 @@ cdef class Buddy: return None alias = property(__get_alias) + def __get_account(self): + '''Returns the buddy's account. + + @return The account(if buddy exists) or None. + ''' + + if self.__exists: + return self.__account + else: + return None + account = property(__get_account) + def __get_group(self): + '''Returns the buddy's group. + + @return The group or None if buddy is not in a group. + ''' + cdef blist.PurpleGroup *c_group = NULL if self.__exists: c_group = blist.purple_buddy_get_group(self._get_structure()) @@ -82,6 +112,11 @@ cdef class Buddy: group = property(__get_group) def __get_server_alias(self): + '''Gets the server alias of the buddy. + + @return The server alias, or None if it is not set. + ''' + cdef char *c_server_alias = NULL c_server_alias = blist.purple_buddy_get_server_alias( \ self._get_structure()) @@ -92,6 +127,14 @@ cdef class Buddy: server_alias = property(__get_server_alias) def __get_contact_alias(self): + '''Returns the correct name to display for a buddy, taking the contact + alias into account. In order of precedence: the buddy's alias; + the buddy's contact alias; the buddy's server alias; the buddy's + user name. + + @return The appropriate name or alias, or None. + ''' + cdef char *c_contact_alias = NULL c_contact_alias = blist.purple_buddy_get_contact_alias( \ self._get_structure()) @@ -102,6 +145,13 @@ cdef class Buddy: contact_alias = property(__get_contact_alias) def __get_local_alias(self): + '''Returns the correct alias for this user, ignoring server aliases. + Used when a user-recognizable name is required. In order: buddy's + alias; buddy's contact alias; buddy's user name. + + @return The appropriate name or alias, or None. + ''' + cdef char *c_local_alias = NULL c_local_alias = blist.purple_buddy_get_local_alias( \ self._get_structure()) @@ -112,30 +162,51 @@ cdef class Buddy: local_alias = property(__get_local_alias) def __get_available(self): + '''Returns whether or not buddy's presence is available. + Available presences are online and possibly invisible, but not away or idle. + + @return True if the buddy's presence is available, or False otherwise. + ''' + if self.__exists: return status.purple_presence_is_available( \ blist.purple_buddy_get_presence(self._get_structure())) else: - return None + return False available = property(__get_available) def __get_online(self): + '''Returns whether or not the buddy's presence is online. + + @return True if the buddy's presence is online, of False otherwise. + ''' + if self.__exists: return status.purple_presence_is_online( \ blist.purple_buddy_get_presence(self._get_structure())) else: - return None + return False online = property(__get_online) def __get_idle(self): + '''Returns whether or not the buddy presence is idle. + + @return True if the presence is idle, or False otherwise. + ''' + if self.__exists: return status.purple_presence_is_idle( \ blist.purple_buddy_get_presence(self._get_structure())) else: - return None + return False idle = property(__get_idle) def __get_active_status(self): + '''Returns the buddy's active status. + + @return The active status. + ''' + cdef status.PurpleStatus* c_status = NULL cdef char *type = NULL cdef char *name = NULL @@ -160,6 +231,12 @@ cdef class Buddy: active_status = property(__get_active_status) def set_alias(self, alias): + '''Sets the buddy's alias. + + @param alias Buddy alias + @return True if success or False if failure to set. + ''' + if self.__exists: blist.purple_blist_alias_buddy(self._get_structure(), alias) return True @@ -167,6 +244,12 @@ cdef class Buddy: return False def set_group(self, group): + '''Sets the buddy's group. + + @param group Buddy group + @return True if success or False if failure to set. + ''' + cdef blist.PurpleContact *c_contact = NULL cdef blist.PurpleGroup *c_group = NULL if self.__exists and group: -- 1.7.9.5