X-Git-Url: http://git.maemo.org/git/?p=python-purple;a=blobdiff_plain;f=buddy.pyx;h=ce45965b6322d93c8855077874d3b794409c2638;hp=be9f2bd72ac2d6b97de0cbe1ff0b23cd41fb652b;hb=refs%2Fheads%2Fmaster;hpb=05c92b9fd39b619dd3da3902cb94a3fec94fe563
diff --git a/buddy.pyx b/buddy.pyx
index be9f2bd..ce45965 100644
--- a/buddy.pyx
+++ b/buddy.pyx
@@ -17,14 +17,16 @@
# along with this program. If not, see .
#
-cimport purple
+cimport account
+cimport blist
+cimport status
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 +42,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 +87,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 +114,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 +129,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 +147,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 +164,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 +233,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 +246,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: