Gwibber

Merge lp:~markjtully/gwibber/documentation into lp:gwibber

  1. documentation
  2. Merge into trunk
Proposed by Mark Tully
Status: Merged
Merged at revision: 1362
Proposed branch: lp:~markjtully/gwibber/documentation
Merge into: lp:gwibber
Diff against target: 1827 lines (+967/-7)
16 files modified
gwibber/microblog/plugins/digg/__init__.py (+25/-0)
gwibber/microblog/plugins/facebook/__init__.py (+71/-0)
gwibber/microblog/plugins/facebook/gtk/facebook/__init__.py (+15/-0)
gwibber/microblog/plugins/flickr/__init__.py (+36/-0)
gwibber/microblog/plugins/foursquare/__init__.py (+42/-1)
gwibber/microblog/plugins/foursquare/gtk/foursquare/__init__.py (+15/-0)
gwibber/microblog/plugins/friendfeed/__init__.py (+101/-0)
gwibber/microblog/plugins/identica/__init__.py (+174/-0)
gwibber/microblog/plugins/identica/gtk/identica/__init__.py (+10/-0)
gwibber/microblog/plugins/pingfm/__init__.py (+15/-0)
gwibber/microblog/plugins/qaiku/__init__.py (+59/-0)
gwibber/microblog/plugins/statusnet/__init__.py (+166/-0)
gwibber/microblog/plugins/statusnet/gtk/statusnet/__init__.py (+10/-0)
gwibber/microblog/plugins/twitter/__init__.py (+205/-4)
gwibber/microblog/plugins/twitter/gtk/twitter/__init__.py (+10/-0)
gwibber/microblog/util/__init__.py (+13/-2)
To merge this branch: bzr merge lp:~markjtully/gwibber/documentation
Reviewer Review Type Date Requested Status
Ken VanDine Approve
Review via email: mp+105572@code.launchpad.net

Description of the change

Added documentation for functions in plugins

To post a comment you must log in.
lp:~markjtully/gwibber/documentation updated
1345. By Mark Tully

Merging from trunk

1346. By Mark Tully

Fixed couple of minor typos in StatusNet after a find/replace was a little overzealous.

Revision history for this message
Ken VanDine (ken-vandine) wrote :

Thanks!

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'gwibber/microblog/plugins/digg/__init__.py'
2--- gwibber/microblog/plugins/digg/__init__.py 2012-02-10 10:06:59 +0000
3+++ gwibber/microblog/plugins/digg/__init__.py 2012-05-13 20:44:18 +0000
4@@ -29,10 +29,19 @@
5 URL_PREFIX = "http://services.digg.com"
6
7 class Client:
8+ """ Client: The Client class is responsible for querying Digg and turning the data obtained
9+ into data that Gwibber can understand.
10+ """
11 def __init__(self, acct):
12 self.account = acct
13
14 def _story(self, data):
15+ """ Parses stories into gwibber compatible forms.
16+ Args:
17+ data: A data object obtained from Digg containing a complete story
18+ Returns:
19+ m: A data object compatible with inserting into the Gwibber database for that tweet
20+ """
21 m = {};
22 m["mid"] = str(data["id"])
23 m["service"] = "digg"
24@@ -66,6 +75,16 @@
25 return m
26
27 def _get(self, path, parse="story", post=False, single=False, **args):
28+ """ Establishes a connection with Digg and gets the data requested.
29+ Args:
30+ path: The end of the url to look up on Twitter
31+ parse: The function to use to parse the data returned (story by default)
32+ post: True is this is a send, False if a recieve (False by default)
33+ single: True if a single checkin is requested, False if multiple (False by default)
34+ **args: Args to be added to the url when accessed.
35+ Returns:
36+ A list of gwibber compatible objects which have been parsed by the parse function
37+ """
38 url = "/".join((URL_PREFIX, path)) + "?appkey=http://gwibber.com&type=json"
39
40 data = network.Download(url, util.compact(args) or None, post).get_json()
41@@ -85,4 +104,10 @@
42 return getattr(self, opname)(**args)
43
44 def receive(self):
45+ """ Gets the latest stories friends have dugg and adds them to the database.
46+ Args:
47+ None
48+ Returns:
49+ A list of gwibber compatible objects which have been parsed by _message()
50+ """
51 return self._get("user/%s/friends/dugg" % self.account["username"])
52
53=== modified file 'gwibber/microblog/plugins/facebook/__init__.py'
54--- gwibber/microblog/plugins/facebook/__init__.py 2012-03-09 19:34:33 +0000
55+++ gwibber/microblog/plugins/facebook/__init__.py 2012-05-13 20:44:18 +0000
56@@ -57,11 +57,24 @@
57 POST_URL = "http://www.facebook.com/profile.php?id=%s&v=feed&story_fbid=%s&ref=mf"
58
59 class Client:
60+ """ Client: The Client class is responsible for querying Facebook and turning the data obtained
61+ into data that Gwibber can understand. Facebook uses a version of oauth for security.
62+ Tokens have already been obtained when the account was set up in Gwibber and are used to
63+ authenticate when getting data.
64+ """
65 def __init__(self, acct):
66 self.account = acct
67 self.user_id = acct.get("uid", None)
68
69 def _check_error(self, data):
70+ """Checks to ensure the data obtained by Facebook is on the correct form
71+ If not, an error is logged in gwibber.log
72+ Args:
73+ data: A data structure obtained from Foursquare
74+ Returns:
75+ True if data is contains 'error' or is not a dict.
76+ Otherwise, False
77+ """
78 if isinstance(data, dict):
79 if data.has_key("error"):
80 logger.info("Facebook error %s - %s", data["error"]["type"], data["error"]["message"])
81@@ -71,6 +84,15 @@
82 return True
83
84 def _get(self, operation, post=False, single=False, **args):
85+ """ Establishes a connection with Facebook and gets the data requested
86+ Args:
87+ operation: The end of the url to look up on Facebook
88+ post: True is this is a send, False if a recieve (False by default)
89+ single: True if a single checkin is requested, False if multiple (False by default)
90+ **args: Args to be added to the url when accessed.
91+ Returns:
92+ A list of facebook objects
93+ """
94 if not self.user_id or "access_token" not in self.account:
95 logstr = """%s: %s - %s""" % (PROTOCOL_INFO["name"], _("Authentication failed"), "Auth needs updating")
96 logger.error("%s", logstr)
97@@ -103,6 +125,12 @@
98 return data
99
100 def _sender(self, data):
101+ """ Parses the sender of the facebook object
102+ Args:
103+ data: A facebook object
104+ Returns:
105+ A sender object in a format compatible with gwibber's database
106+ """
107 sender = {
108 "name": data["name"],
109 "id": str(data.get("id", '')),
110@@ -113,6 +141,12 @@
111 return sender
112
113 def _message(self, data):
114+ """ Parses a facebook object
115+ Args:
116+ data: A facebook object
117+ Returns:
118+ A facebook object in a format compatible with gwibber's database
119+ """
120 if type(data) != dict:
121 logger.error("Cannot parse message data: %s", str(data))
122 return {}
123@@ -250,6 +284,12 @@
124 return getattr(self, opname)(**args)
125
126 def receive(self, since=None):
127+ """ Gets a list of facebook objects and add them to the database.
128+ Args:
129+ since: the time to get facebook objects from
130+ Returns:
131+ A list of gwibber compatible objects which have been parsed by the parse function
132+ """
133 if not since:
134 since = int(mx.DateTime.DateTimeFromTicks(mx.DateTime.localtime()) - mx.DateTime.TimeDelta(hours=240.0))
135 else:
136@@ -269,6 +309,12 @@
137 else: return
138
139 def delete(self, message):
140+ """ Deletes a specified message from facebook
141+ Args:
142+ message: a gwibber compatible message object (from gwibber's database)
143+ Returns:
144+ Nothing
145+ """
146 result = self._get("stream.remove", post_id=message["mid"])
147 if not result:
148 logger.error("<facebook:delete> failed")
149@@ -276,6 +322,12 @@
150 return []
151
152 def like(self, message):
153+ """ Likes a specified message on facebook
154+ Args:
155+ message: a gwibber compatible message object (from gwibber's database)
156+ Returns:
157+ The liked message
158+ """
159 result = self._get(message["mid"] + "/likes", post=True)
160 if not result:
161 logger.error("<facebook:like> failed")
162@@ -284,6 +336,12 @@
163 return data
164
165 def unlike(self, message):
166+ """ Unlikes a specified message on facebook
167+ Args:
168+ message: a gwibber compatible message object (from gwibber's database)
169+ Returns:
170+ The unliked message
171+ """
172 result = self._get(message["mid"] + "/likes", post=True, method="delete")
173 if not result:
174 logger.error("<facebook:like> failed")
175@@ -292,6 +350,12 @@
176 return data
177
178 def send(self, message):
179+ """ Sends a message to facebook
180+ Args:
181+ message: The text of the message
182+ Returns:
183+ Nothing
184+ """
185 result = self._get("me/feed", message=message, status_includes_verb=True, post=True)
186 if not result:
187 logger.error("<facebook:send> failed")
188@@ -299,6 +363,13 @@
189 return []
190
191 def send_thread(self, message, target):
192+ """ Sends a message to facebook as a reply to another message
193+ Args:
194+ message: The text of the message
195+ target: The person the message is directed at (as a gwibber compatible object)
196+ Returns:
197+ Nothing
198+ """
199 result = self._get(target["mid"] + "/comments", message=message, post=True)
200 if not result:
201 logger.error("<facebook:send_thread> failed")
202
203=== modified file 'gwibber/microblog/plugins/facebook/gtk/facebook/__init__.py'
204--- gwibber/microblog/plugins/facebook/gtk/facebook/__init__.py 2012-04-27 15:03:16 +0000
205+++ gwibber/microblog/plugins/facebook/gtk/facebook/__init__.py 2012-05-13 20:44:18 +0000
206@@ -89,6 +89,12 @@
207 return True
208
209 def on_facebook_auth_clicked(self, widget, data=None):
210+ """ When the Authorize button is clicked, the Facebook authorisation window
211+ is loaded for the user to enter their credentials for authorisation
212+ Args:
213+ widget:
214+ data:
215+ """
216 self.winsize = self.window.get_size()
217
218 web = WebKit.WebView()
219@@ -119,6 +125,15 @@
220 self.ui.get_object("vbox_advanced").hide()
221
222 def on_facebook_auth_title_change(self, web=None, title=None, data=None):
223+ """ When the title of the authorisation window is changed, the user has entered their credentials
224+ and pressed login. If login is successful, grab the accesstoken from the callback url.
225+ This is used for authentication for all subsequnt calls to Facebook
226+ The first thing to do is get the user's own information from Facebook.
227+ Args:
228+ web:
229+ title:
230+ data:
231+ """
232 saved = False
233 if hasattr(self.dialog, "infobar_content_area"):
234 for child in self.dialog.infobar_content_area.get_children(): child.destroy()
235
236=== modified file 'gwibber/microblog/plugins/flickr/__init__.py'
237--- gwibber/microblog/plugins/flickr/__init__.py 2012-02-10 10:06:59 +0000
238+++ gwibber/microblog/plugins/flickr/__init__.py 2012-05-13 20:44:18 +0000
239@@ -38,13 +38,28 @@
240 IMAGE_PAGE_URL = "http://www.flickr.com/photos/%s/%s"
241
242 def parse_time(t):
243+ """Converts time from the format used by Flickr to that used by gwibber
244+ Args:
245+ t: Time as provided by Flickr
246+ Return:
247+ Time in a gwibber compatible format
248+ """
249 return mx.DateTime.DateTimeFromTicks(int(t)).gmtime().ticks()
250
251 class Client:
252+ """ Client: The Client class is responsible for querying Flickr and turning the data obtained
253+ into data that Gwibber can understand.
254+ """
255 def __init__(self, acct):
256 self.account = acct
257
258 def _message(self, data):
259+ """ Parses messages into gwibber compatible forms.
260+ Args:
261+ data: A data object obtained from Twitter containing a complete tweet
262+ Returns:
263+ m: A data object compatible with inserting into the Gwibber database for that tweet
264+ """
265 m = {}
266 m["mid"] = str(data["id"])
267 m["service"] = "flickr"
268@@ -75,6 +90,15 @@
269 return m
270
271 def _get(self, method, parse="message", post=False, **args):
272+ """ Establishes a connection with Flickr and gets the data requested.
273+ Args:
274+ method: The method to look up on Flickr
275+ parse: The function to use to parse the data returned (message by default)
276+ post: True is this is a send, False if a recieve (False by default)
277+ **args: Args to be added to the url when accessed.
278+ Returns:
279+ A list of gwibber compatible objects which have been parsed by the parse function
280+ """
281 args.update({"api_key": API_KEY, "method": method})
282 data = network.Download(REST_SERVER, args, post).get_json()
283
284@@ -83,6 +107,12 @@
285 else: return data
286
287 def _getNSID(self):
288+ """ Gets users own Flickr id
289+ Args:
290+ None
291+ Returns:
292+ A flickr user id
293+ """
294 data = self._get("flickr.people.findByUsername",
295 parse=None, nojsoncallback="1", format="json",
296 username=self.account["username"])
297@@ -96,6 +126,12 @@
298 return getattr(self, opname)(**args)
299
300 def images(self):
301+ """ Gets a stream of images from Flickr
302+ Args:
303+ None
304+ Returns:
305+ A list of gwibber compatible objects which have been parsed by the parse function
306+ """
307 user_id=self._getNSID()
308 if user_id:
309 return self._get("flickr.photos.getContactsPublicPhotos",
310
311=== modified file 'gwibber/microblog/plugins/foursquare/__init__.py'
312--- gwibber/microblog/plugins/foursquare/__init__.py 2012-02-19 02:02:27 +0000
313+++ gwibber/microblog/plugins/foursquare/__init__.py 2012-05-13 20:44:18 +0000
314@@ -34,6 +34,11 @@
315 URL_PREFIX = "https://api.foursquare.com/v2"
316
317 class Client:
318+ """ Client: The Client class is responsible for querying Foursquare and turning the data obtained
319+ into data that Gwibber can understand. Foursquare uses a version of oauth for security.
320+ Tokens have already been obtained when the account was set up in Gwibber and are used to
321+ authenticate when getting data.
322+ """
323 def __init__(self, acct):
324 self.service = util.getbus("Service")
325 if acct.has_key("secret_token") and acct.has_key("password"): acct.pop("password")
326@@ -45,7 +50,12 @@
327 self.token = acct["access_token"]
328
329 def _message(self, data):
330-
331+ """ Parses messages into gwibber compatible forms
332+ Args:
333+ data: A data object obtained from Foursquare containing a complete checkin
334+ Returns:
335+ m: A data object compatible with inserting into the Gwibber database for that checkin
336+ """
337 m = {};
338 m["mid"] = str(data["id"])
339 m["service"] = "foursquare"
340@@ -160,6 +170,14 @@
341 return m
342
343 def _check_error(self, data):
344+ """Checks to ensure the data obtained by Foursquare is on the correct form
345+ If not, an error is logged in gwibber.log
346+ Args:
347+ data: A data structure obtained from Foursquare
348+ Returns:
349+ True if data is valid (is a dict and contains a 'recent' parameter.
350+ Otherwise, False
351+ """
352 if isinstance(data, dict) and "recent" in data:
353 return True
354 else:
355@@ -167,12 +185,28 @@
356 return False
357
358 def _get_comments(self, checkin_id):
359+ """ Gets comments on a particular checkin id.
360+ Args:
361+ checkin_id: The checkin id of the checkin
362+ Returns:
363+ A comment object
364+ """
365 url = "/".join((URL_PREFIX, "checkins", checkin_id))
366 url = url + "?oauth_token=" + self.token
367 data = network.Download(url, None, False).get_json()["response"]
368 return data["checkin"]["comments"]["items"]
369
370 def _get(self, path, parse="message", post=False, single=False, **args):
371+ """ Establishes a connection with Foursquare and gets the data requested
372+ Args:
373+ path: The end of the url to look up on Foursquare
374+ parse: The function to use to parse the data returned (message by default)
375+ post: True is this is a send, False if a recieve (False by default)
376+ single: True if a single checkin is requested, False if multiple (False by default)
377+ **args: Args to be added to the url when accessed.
378+ Returns:
379+ A list of gwibber compatible objects which have been parsed by the parse function
380+ """
381 url = "/".join((URL_PREFIX, path))
382
383 url = url + "?oauth_token=" + self.token
384@@ -211,4 +245,11 @@
385 return getattr(self, opname)(**args)
386
387 def receive(self):
388+ """ Gets a list of each friend's most recent checkins and add them to
389+ the database.
390+ Args:
391+ None
392+ Returns:
393+ A list of gwibber compatible objects which have been parsed by the parse function
394+ """
395 return self._get("checkins/recent")
396
397=== modified file 'gwibber/microblog/plugins/foursquare/gtk/foursquare/__init__.py'
398--- gwibber/microblog/plugins/foursquare/gtk/foursquare/__init__.py 2012-04-12 18:28:38 +0000
399+++ gwibber/microblog/plugins/foursquare/gtk/foursquare/__init__.py 2012-05-13 20:44:18 +0000
400@@ -59,6 +59,12 @@
401 return True
402
403 def on_foursquare_auth_clicked(self, widget, data=None):
404+ """ When the Authorize button is clicked, the Foursquare authorisation window
405+ is loaded for the user to enter their credentials for authorisation
406+ Args:
407+ widget:
408+ data:
409+ """
410 self.winsize = self.window.get_size()
411
412 web = WebKit.WebView()
413@@ -84,6 +90,15 @@
414 self.dialog.infobar.set_message_type(Gtk.MessageType.INFO)
415
416 def on_foursquare_auth_title_change(self, web=None, title=None, data=None):
417+ """ When the title of the authorisation window is changed, the user has entered their credentials
418+ and pressed login. If login is successful, exchange the code obtained from Foursquare via the callback url for
419+ an access token. This is used for authentication for all subsequnt calls to Foursquare
420+ The first thing to do is get the user's own information from Foursquare.
421+ Args:
422+ web:
423+ title:
424+ data:
425+ """
426 saved = False
427 if hasattr(self.dialog, "infobar_content_area"):
428 for child in self.dialog.infobar_content_area.get_children(): child.destroy()
429
430=== modified file 'gwibber/microblog/plugins/friendfeed/__init__.py'
431--- gwibber/microblog/plugins/friendfeed/__init__.py 2012-02-10 10:06:59 +0000
432+++ gwibber/microblog/plugins/friendfeed/__init__.py 2012-05-13 20:44:18 +0000
433@@ -43,10 +43,21 @@
434 URL_PREFIX = "https://friendfeed.com/api"
435
436 class Client:
437+ """ Client: The Client class is responsible for querying Friendfeed and turning the data obtained
438+ into data that Gwibber can understand. Friendfeed uses a username and password for security
439+ which are provided when the account was set up in Gwibber and are used to
440+ authenticate when getting data.
441+ """
442 def __init__(self, acct):
443 self.account = acct
444
445 def _sender(self, user):
446+ """Parses the user portion of an update
447+ Args:
448+ user: A user object from an update
449+ Returns:
450+ A user object in a format compatible with gwibber's database
451+ """
452 return {
453 "name": user["name"],
454 "nick": user["nickname"],
455@@ -57,6 +68,14 @@
456 }
457
458 def _message(self, data):
459+ """ Parses messages into gwibber compatible forms. This is the initial function for
460+ tweet parsing and parses likes, comments and attached media. It sends the rest to _sender()
461+ for further parsing
462+ Args:
463+ data: A data object obtained from Twitter containing a complete update
464+ Returns:
465+ m: A data object compatible with inserting into the Gwibber database for that update
466+ """
467 m = {
468 "mid": data["id"],
469 "service": "friendfeed",
470@@ -102,6 +121,17 @@
471 return m
472
473 def _get(self, path, post=False, parse="message", kind="entries", single=False, **args):
474+ """ Establishes a connection with Twitter and gets the data requested. Requires authentication.
475+ Args:
476+ path: The end of the url to look up on Twitter
477+ parse: The function to use to parse the data returned (message by default)
478+ post: True is this is a send, False if a recieve (False by default)
479+ kind : The type of updates to get
480+ single: True if a single checkin is requested, False if multiple (False by default)
481+ **args: Args to be added to the url when accessed.
482+ Returns:
483+ A list of gwibber compatible objects which have been parsed by the parse function
484+ """
485 url = "/".join((URL_PREFIX, path))
486 data = network.Download(url, util.compact(args), post,
487 self.account["username"], self.account["secret_key"]).get_json()
488@@ -124,36 +154,107 @@
489 return getattr(self, opname)(**args)
490
491 def receive(self, count=util.COUNT, since=None):
492+ """ Gets the latest updates and adds them to the database.
493+ Args:
494+ count = number of updates to get
495+ since = time to get updates since
496+ Returns:
497+ A list of gwibber compatible objects which have been parsed by _message()
498+ """
499 return self._get("feed/home", num=count, start=since)
500
501 def public(self, count=util.COUNT, since=None):
502+ """ Gets the latest updates from the public timeline and adds them to the database.
503+ Args:
504+ count = number of updates to get
505+ since = time to get updates since
506+ Returns:
507+ A list of gwibber compatible objects which have been parsed by _message()
508+ """
509 return self._get("feed/public", num=count, start=since)
510
511 def thread(self, id, count=util.COUNT, since=None):
512+ """ Gets the latest updates from a specific conversation thread and adds them to the database.
513+ Args:
514+ id = The thread id
515+ count = number of updates to get
516+ since = time to get updates since
517+ Returns:
518+ A list of gwibber compatible objects which have been parsed by _message()
519+ """
520 self._get("feed/entry/%s" % id, num=count, start=since)
521
522 def search(self, query, count=util.COUNT, since=None):
523+ """ Gets the results of a search.
524+ Args:
525+ query: The search terms
526+ count = number of updates to get
527+ since = time to get updates since
528+ Returns:
529+ A list of gwibber compatible objects which have been parsed by _message()
530+ """
531 return self._get("feed/search", q=query, num=count, start=since)
532
533 def search_url(self, query, count=util.COUNT, since=None):
534+ """ Gets the results of a search by a specific url.
535+ Args:
536+ query: The search url
537+ count = number of updates to get
538+ since = time to get updates since
539+ Returns:
540+ A list of gwibber compatible objects which have been parsed by _message()
541+ """
542 return self._get("feed/url", url=query, num=util.COUNT, start=None)
543
544 def user_messages(self, id, count=util.COUNT, since=None):
545+ """ Gets a user's message stream
546+ Args:
547+ id: The user's screen name
548+ count: Number of tweets to get
549+ since: Time to get tweets since
550+ Returns:
551+ A list of gwibber compatible objects which have been parsed by _message()
552+ """
553 return self._get("feed/user/%s" % id, num=count, start=since)
554
555 def delete(self, message):
556+ """ Deletes a specified update from Friendfeed
557+ Args:
558+ message: a gwibber compatible message object (from gwibber's database)
559+ Returns:
560+ Nothing
561+ """
562 self._get("entry/delete", True, None, entry=message["mid"])
563 return []
564
565 def like(self, message):
566+ """ Likes a specified update on Friendfeed
567+ Args:
568+ message: a gwibber compatible message object (from gwibber's database)
569+ Returns:
570+ Nothing
571+ """
572 self._get("entry/like", True, None, entry=message["mid"])
573 return []
574
575 def send(self, message):
576+ """ Sends an update to Friendfeed
577+ Args:
578+ message: The message text
579+ Returns:
580+ Nothing
581+ """
582 self._get("share", True, single=True, title=message)
583 return []
584
585 def send_thread(self, message, target):
586+ """ Sends an update to a specific user to Friendfeed
587+ Args:
588+ message: The message text
589+ target: A gwibber compatible object for the target user
590+ Returns:
591+ Nothing
592+ """
593 self._get("comment", True, None, body=message, entry=target["mid"])
594 return []
595
596
597=== modified file 'gwibber/microblog/plugins/identica/__init__.py'
598--- gwibber/microblog/plugins/identica/__init__.py 2012-02-13 20:39:02 +0000
599+++ gwibber/microblog/plugins/identica/__init__.py 2012-05-13 20:44:18 +0000
600@@ -58,6 +58,11 @@
601 URL_PREFIX = "https://identi.ca"
602
603 class Client:
604+ """ Client: The Client class is responsible for querying Identica and turning the data obtained
605+ into data that Gwibber can understand. Identica uses a version of oauth for security.
606+ Tokens have already been obtained when the account was set up in Gwibber and are used to
607+ authenticate when getting data.
608+ """
609 def __init__(self, acct):
610 self.url_prefix = "https://identi.ca"
611
612@@ -65,6 +70,13 @@
613 self.account = acct
614
615 def _common(self, data):
616+ """ Parses messages into gwibber compatible forms. This function is common to all tweet types
617+ and includes parsing of user mentions, hashtags, urls, images and videos
618+ Args:
619+ data: A data object obtained from Identica containing a complete update
620+ Returns:
621+ m: A data object compatible with inserting into the Gwibber database for that update
622+ """
623 m = {}
624 try:
625 m["mid"] = str(data["id"])
626@@ -104,6 +116,12 @@
627 return m
628
629 def _user(self, user):
630+ """ Parses the user portion of an update
631+ Args:
632+ user: A user object from an update
633+ Returns:
634+ A user object in a format compatible with gwibber's database
635+ """
636 return {
637 "name": user.get("name", None),
638 "nick": user.get("screen_name", None),
639@@ -122,6 +140,14 @@
640 }
641
642 def _message(self, data):
643+ """ Parses messages into gwibber compatible forms. This is the initial function for
644+ update parsing and parses retweeted status (the shared-by portion)
645+ and reply details (the in-reply-to portion). It sends the rest to _common() for further parsing
646+ Args:
647+ data: A data object obtained from Identica containing a complete update
648+ Returns:
649+ m: A data object compatible with inserting into the Gwibber database for that update
650+ """
651 if type(data) != dict:
652 logger.error("Cannot parse message data: %s", str(data))
653 return {}
654@@ -158,6 +184,14 @@
655 return m
656
657 def _private(self, data):
658+ """ Sets the message type and privacy if the message should be in the private stream.
659+ Also parses the recipient as both sent & recieved messages can be in the private stream.
660+ It sends the rest to _message() for further parsing
661+ Args:
662+ data: A data object obtained from Identica containing a complete update
663+ Returns:
664+ m: A data object compatible with inserting into the Gwibber database for that update
665+ """
666 m = self._message(data)
667 m["private"] = True
668 m["recipient"] = {}
669@@ -172,6 +206,13 @@
670 return m
671
672 def _result(self, data):
673+ """ Called when a search is done in gwibber. Parses the sender and sends the rest to _common()
674+ for further parsing
675+ Args:
676+ data: A data object obtained from Identica containing a complete update
677+ Returns:
678+ m: A data object compatible with inserting into the Gwibber database for that update
679+ """
680 m = self._common(data)
681
682 if data["to_user_id"]:
683@@ -188,6 +229,12 @@
684 return m
685
686 def _profile(self, data):
687+ """ Called when a user is clicked on.
688+ Args:
689+ data: A data object obtained from Identica containing a complete user
690+ Returns:
691+ A data object compatible with inserting into the Gwibber database for that user
692+ """
693 return {
694 "name": data.get("name", data["screen_name"]),
695 "service": "identica",
696@@ -213,6 +260,16 @@
697 }
698
699 def _get(self, path, parse="message", post=False, single=False, **args):
700+ """ Establishes a connection with Identica and gets the data requested. Requires authentication.
701+ Args:
702+ path: The end of the url to look up on Identica
703+ parse: The function to use to parse the data returned (message by default)
704+ post: True is this is a send, False if a recieve (False by default)
705+ single: True if a single checkin is requested, False if multiple (False by default)
706+ **args: Args to be added to the url when accessed.
707+ Returns:
708+ A list of gwibber compatible objects which have been parsed by the parse function
709+ """
710 if not self.account.has_key("access_token") and not self.account.has_key("secret_token"):
711 logger.error("%s unexpected result - %s", PROTOCOL_INFO["name"], _("Account needs to be re-authorized"))
712 return [{"error": {"type": "auth", "account": self.account, "message": _("Account needs to be re-authorized")}}]
713@@ -262,6 +319,13 @@
714 return [self._result(m) for m in data]
715
716 def _search(self, **args):
717+ """ Establishes a connection with Identica and gets the results of a search.
718+ Does not require authentication
719+ Args:
720+ **args: The search terms
721+ Returns:
722+ A list of gwibber compatible objects which have been parsed by _result()
723+ """
724 data = network.Download("%s/api/search.json" % self.url_prefix, util.compact(args))
725 data = data.get_json()
726
727@@ -275,58 +339,168 @@
728 return getattr(self, opname)(**args)
729
730 def receive(self, count=util.COUNT, since=None):
731+ """ Gets the latest updates and adds them to the database.
732+ Args:
733+ count = number of updates to get
734+ since = time to get updates since
735+ Returns:
736+ A list of gwibber compatible objects which have been parsed by _message()
737+ """
738 return self._get("statuses/friends_timeline.json", count=count, since_id=since)
739
740 def responses(self, count=util.COUNT, since=None):
741+ """ Gets the latest replies and adds them to the database.
742+ Args:
743+ count = number of updates to get
744+ since = time to get updates since
745+ Returns:
746+ A list of gwibber compatible objects which have been parsed by _responses()
747+ """
748 return self._get("statuses/mentions.json", count=count, since_id=since)
749
750 def private(self, count=util.COUNT, since=None):
751+ """ Gets the latest direct messages sent and recieved and adds them to the database.
752+ Args:
753+ count = number of updates to get
754+ since = time to get updates since
755+ Returns:
756+ A list of gwibber compatible objects which have been parsed by _private()
757+ """
758 private = self._get("direct_messages.json", "private", count=count, since_id=since) or []
759 private_sent = self._get("direct_messages/sent.json", "private", count=count, since_id=since) or []
760 return private + private_sent
761
762 def public(self, count=util.COUNT, since=None):
763+ """ Gets the latest updates from the public timeline and adds them to the database.
764+ Args:
765+ count = number of updates to get
766+ since = time to get updates since
767+ Returns:
768+ A list of gwibber compatible objects which have been parsed by _message()
769+ """
770 return self._get("statuses/public_timeline.json")
771
772 def search(self, query, count=util.COUNT, since=None):
773+ """ Gets the latest results from a search and adds them to the database.
774+ Args:
775+ query = the search query
776+ count = number of updates to get
777+ since = time to get updates since
778+ Returns:
779+ A list of gwibber compatible objects which have been parsed by _search()
780+ """
781 return self._search(q=query, rpp=count, since_id=since)
782
783 def tag(self, query, count=util.COUNT, since=None):
784+ """ Gets the latest results from a hashtag search and adds them to the database.
785+ Args:
786+ query = the search query (hashtag without the #)
787+ count = number of updates to get
788+ since = time to get updates since
789+ Returns:
790+ A list of gwibber compatible objects which have been parsed by _search()
791+ """
792 return self._search(q="#%s" % query, count=count, since_id=since)
793
794 def delete(self, message):
795+ """ Deletes a specified tweet from Identica
796+ Args:
797+ message: a gwibber compatible message object (from gwibber's database)
798+ Returns:
799+ Nothing
800+ """
801 self._get("statuses/destroy/%s.json" % message["mid"], None, post=True, do=1)
802 return []
803
804 def like(self, message):
805+ """ Favourites a specified tweet on Identica
806+ Args:
807+ message: a gwibber compatible message object (from gwibber's database)
808+ Returns:
809+ Nothing
810+ """
811 self._get("favorites/create/%s.json" % message["mid"], None, post=True, do=1)
812 return []
813
814 def send(self, message):
815+ """ Sends an update to Identica
816+ Args:
817+ message: The update's text
818+ Returns:
819+ Nothing
820+ """
821 return self._get("statuses/update.json", post=True, single=True,
822 status=message, source="Gwibber")
823
824 def send_private(self, message, private):
825+ """ Sends a direct message to Identica
826+ Args:
827+ message: The update's text
828+ private: A gwibber compatible user object (from gwibber's database)
829+ Returns:
830+ Nothing
831+ """
832 return self._get("direct_messages/new.json", "private", post=True, single=True,
833 text=message, screen_name=private["sender"]["nick"])
834
835 def send_thread(self, message, target):
836+ """ Sends a reply to a user on Identica
837+ Args:
838+ message: The update's text
839+ target: A gwibber compatible user object (from gwibber's database)
840+ Returns:
841+ Nothing
842+ """
843 return self._get("statuses/update.json", post=True, single=True,
844 status=message, source="Gwibber", in_reply_to_status_id=target["mid"])
845
846 def retweet(self, message):
847+ """ Shares an update
848+ Args:
849+ message: A gwibber compatible message object (from gwibber's database)
850+ Returns:
851+ Nothing
852+ """
853 return self._get("statuses/retweet/%s.json" % message["mid"], None, post=True, do=1, source="Gwibber")
854
855 def follow(self, screen_name):
856+ """ Follows a user
857+ Args:
858+ screen_name: The screen name of the user to be followed
859+ Returns:
860+ Nothing
861+ """
862 return self._get("friendships/create.json", screen_name=screen_name, post=True, parse="follow", source="Gwibber")
863
864 def unfollow(self, screen_name):
865+ """ Unfollows a user
866+ Args:
867+ screen_name: The screen name of the user to be unfollowed
868+ Returns:
869+ Nothing
870+ """
871 return self._get("friendships/destroy.json", screen_name=screen_name, post=True, parse="unfollow", source="Gwibber")
872
873 def profile(self, id=None, count=None, since=None):
874+ """ Gets a user's profile
875+ Args:
876+ id: The user's screen name
877+ count: Number of updates to get
878+ since: Time to get updates since
879+ Returns:
880+ A list of gwibber compatible objects which have been parsed by _profile()
881+ """
882 return self._get("users/show.json", screen_name=id, count=count, since_id=since, parse="profile", source="Gwibber")
883
884 def user_messages(self, id=None, count=util.COUNT, since=None):
885+ """ Gets a user's profile & timeline
886+ Args:
887+ id: The user's screen name
888+ count: Number of updates to get
889+ since: Time to get updates since
890+ Returns:
891+ A list of gwibber compatible objects which have been parsed by _profile()
892+ """
893 profiles = [self.profile(id)] or []
894 messages = self._get("statuses/user_timeline.json", id=id, count=count, since_id=since, source="Gwibber") or []
895 return messages + profiles
896
897=== modified file 'gwibber/microblog/plugins/identica/gtk/identica/__init__.py'
898--- gwibber/microblog/plugins/identica/gtk/identica/__init__.py 2012-03-07 21:17:19 +0000
899+++ gwibber/microblog/plugins/identica/gtk/identica/__init__.py 2012-05-13 20:44:18 +0000
900@@ -59,6 +59,12 @@
901 return True
902
903 def on_statusnet_auth_clicked(self, widget, data=None):
904+ """ When the Authorize button is clicked, the Identica authorisation window
905+ is loaded for the user to enter their credentials for authorisation
906+ Args:
907+ widget:
908+ data:
909+ """
910 self.winsize = self.window.get_size()
911
912 web = WebKit.WebView()
913@@ -96,6 +102,10 @@
914 self.ui.get_object("vbox_advanced").hide()
915
916 def on_statusnet_auth_title_change(self, web=None, title=None, data=None):
917+ """ When the title of the authorisation window is changed, the user has entered their credentials
918+ and pressed login. If login is successful, get the token & verifier from the callback uri. Exchange
919+ these for the access token & secret. This is used for authentication for all subsequnt calls to Identica.
920+ """
921 saved = False
922 if title.get_title() == "Success":
923 try:
924
925=== modified file 'gwibber/microblog/plugins/pingfm/__init__.py'
926--- gwibber/microblog/plugins/pingfm/__init__.py 2012-02-10 10:06:59 +0000
927+++ gwibber/microblog/plugins/pingfm/__init__.py 2012-05-13 20:44:18 +0000
928@@ -36,6 +36,11 @@
929 API_KEY = "7c3d2c111be8979ac236eecddf6679e7"
930
931 class Client:
932+ """ Client: The Client class is responsible for sending messages to Ping.fm.
933+ Ping uses a version of oauth for security. Tokens have already been
934+ obtained when the account was set up in Gwibber and are used to
935+ authenticate when sending data.
936+ """
937 def __init__(self, acct):
938 self.account = acct
939
940@@ -43,9 +48,19 @@
941 return getattr(self, opname)(**args)
942
943 def send_enabled(self):
944+ """ Checks that sending is enabled on the account
945+ Returns:
946+ True/False if sending is enabled or not and also the application key
947+ """
948 return self.account["send_enabled"] and self.account["app_key"]
949
950 def send(self, message):
951+ """ Sends an update to ping.fm
952+ Args:
953+ message: The update's text
954+ Returns:
955+ Nothing
956+ """
957 args = {
958 "post_method": "microblog",
959 "user_app_key": self.account["secret_key"],
960
961=== modified file 'gwibber/microblog/plugins/qaiku/__init__.py'
962--- gwibber/microblog/plugins/qaiku/__init__.py 2012-02-10 10:06:59 +0000
963+++ gwibber/microblog/plugins/qaiku/__init__.py 2012-05-13 20:44:18 +0000
964@@ -38,10 +38,21 @@
965 URL_PREFIX = "http://www.qaiku.com"
966
967 class Client:
968+ """ Client: The Client class is responsible for querying Qaiku and turning the data obtained
969+ into data that Gwibber can understand. Qaiku uses a username and password for security.
970+ which are used to authenticate when getting data.
971+ """
972 def __init__(self, acct):
973 self.account = acct
974
975 def _common(self, data):
976+ """ Parses messages into gwibber compatible forms. This function is common to all update types
977+ and includes parsing of user mentions, hashtags, urls, images and videos
978+ Args:
979+ data: A data object obtained from Qaiku containing a complete update
980+ Returns:
981+ m: A data object compatible with inserting into the Gwibber database for that tweet
982+ """
983 m = {};
984 m["mid"] = str(data["id"])
985 m["service"] = "qaiku"
986@@ -74,6 +85,13 @@
987 return m
988
989 def _message(self, data):
990+ """ Parses messages into gwibber compatible forms. This is the initial function for
991+ update parsing and parses the sender. It sends the rest to _common() for further parsing
992+ Args:
993+ data: A data object obtained from Qaiku containing a complete update
994+ Returns:
995+ m: A data object compatible with inserting into the Gwibber database for that update
996+ """
997 m = self._common(data)
998 user = data["user"]
999 img = user["profile_image_url"]
1000@@ -92,6 +110,16 @@
1001 return m
1002
1003 def _get(self, path, parse="message", post=False, single=False, **args):
1004+ """ Establishes a connection with Qaiku and gets the data requested. Requires authentication.
1005+ Args:
1006+ path: The end of the url to look up on Qaiku
1007+ parse: The function to use to parse the data returned (message by default)
1008+ post: True is this is a send, False if a recieve (False by default)
1009+ single: True if a single checkin is requested, False if multiple (False by default)
1010+ **args: Args to be added to the url when accessed.
1011+ Returns:
1012+ A list of gwibber compatible objects which have been parsed by the parse function
1013+ """
1014 url = "/".join((URL_PREFIX, "api", path))
1015 url += ("&" if "?" in url else "?") + "apikey=%s" % self.account["password"]
1016 data = network.Download(url, util.compact(args) or None, post).get_json()
1017@@ -106,18 +134,49 @@
1018 return getattr(self, opname)(**args)
1019
1020 def receive(self):
1021+ """ Gets the latest updates and adds them to the database.
1022+ Args:
1023+ None
1024+ Returns:
1025+ A list of gwibber compatible objects which have been parsed by _message()
1026+ """
1027 return self._get("statuses/friends_timeline.json")
1028
1029 def user_messages(self, id=None):
1030+ """ Gets a specific user's timeline
1031+ Args:
1032+ id: The user's screen name
1033+ Returns:
1034+ A list of gwibber compatible objects which have been parsed by _message()
1035+ """
1036 return self._get("statuses/user_timeline.json", screen_name=id)
1037
1038 def responses(self):
1039+ """ Gets the latest replies and adds them to the database.
1040+ Args:
1041+ None
1042+ Returns:
1043+ A list of gwibber compatible objects which have been parsed by _message()
1044+ """
1045 return self._get("statuses/mentions.json")
1046
1047 def send(self, message):
1048+ """ Sends an update to Qaiku
1049+ Args:
1050+ message: The update's text
1051+ Returns:
1052+ Nothing
1053+ """
1054 return self._get("statuses/update.json", post=True, single=True, status=message, source='gwibbernet')
1055
1056 def send_thread(self, message, target):
1057+ """ Sends a reply to a user on Qaiku
1058+ Args:
1059+ message: The update's text
1060+ target: A gwibber compatible user object (from gwibber's database)
1061+ Returns:
1062+ Nothing
1063+ """
1064 recipient = target.get("reply", {}).get("id", 0) or target.get("mid", 0)
1065 return self._get("statuses/update.json", post=True, single=True,
1066 status=message, in_reply_to_status_id=recipient, source='gwibbernet')
1067
1068=== modified file 'gwibber/microblog/plugins/statusnet/__init__.py'
1069--- gwibber/microblog/plugins/statusnet/__init__.py 2012-02-13 20:39:02 +0000
1070+++ gwibber/microblog/plugins/statusnet/__init__.py 2012-05-13 20:44:18 +0000
1071@@ -55,6 +55,11 @@
1072 }
1073
1074 class Client:
1075+ """ Client: The Client class is responsible for querying the StatusNet server and turning the data obtained
1076+ into data that Gwibber can understand. The StatusNet server uses a version of oauth for security.
1077+ Tokens have already been obtained when the account was set up in Gwibber and are used to
1078+ authenticate when getting data.
1079+ """
1080 def __init__(self, acct):
1081 if acct.has_key("url_prefix"):
1082 pref = "" if acct["url_prefix"].startswith("http") else "https://"
1083@@ -65,6 +70,13 @@
1084 self.account = acct
1085
1086 def _common(self, data):
1087+ """ Parses messages into gwibber compatible forms. This function is common to all update types
1088+ and includes parsing of user mentions, hashtags, urls, images and videos
1089+ Args:
1090+ data: A data object obtained from the StatusNet server containing a complete update
1091+ Returns:
1092+ m: A data object compatible with inserting into the Gwibber database for that update
1093+ """
1094 m = {}
1095 try:
1096 m["mid"] = str(data["id"])
1097@@ -104,6 +116,12 @@
1098 return m
1099
1100 def _user(self, user):
1101+ """ Parses the user portion of an update
1102+ Args:
1103+ user: A user object from an update
1104+ Returns:
1105+ A user object in a format compatible with gwibber's database
1106+ """
1107 return {
1108 "name": user.get("name", None),
1109 "nick": user.get("screen_name", None),
1110@@ -122,6 +140,14 @@
1111 }
1112
1113 def _message(self, data):
1114+ """ Parses messages into gwibber compatible forms. This is the initial function for
1115+ tweet parsing and parses shared status, source (the program the update was sent from)
1116+ and reply details (the in-reply-to portion). It sends the rest to _common() for further parsing
1117+ Args:
1118+ data: A data object obtained from the StatusNet server containing a complete update
1119+ Returns:
1120+ m: A data object compatible with inserting into the Gwibber database for that tweet
1121+ """
1122 if type(data) != dict:
1123 logger.error("Cannot parse message data: %s", str(data))
1124 return {}
1125@@ -157,6 +183,14 @@
1126 return m
1127
1128 def _private(self, data):
1129+ """ Sets the message type and privacy if the message should be in the private stream.
1130+ Also parses the recipient as both sent & recieved messages can be in the private stream.
1131+ It sends the rest to _message() for further parsing
1132+ Args:
1133+ data: A data object obtained from the StatusNet server containing a complete update
1134+ Returns:
1135+ m: A data object compatible with inserting into the Gwibber database for that update
1136+ """
1137 m = self._message(data)
1138 m["private"] = True
1139 m["recipient"] = {}
1140@@ -171,6 +205,13 @@
1141 return m
1142
1143 def _result(self, data):
1144+ """ Called when a search is done in gwibber. Parses the sender and sends the rest to _common()
1145+ for further parsing
1146+ Args:
1147+ data: A data object obtained from the StatusNet server containing a complete update
1148+ Returns:
1149+ m: A data object compatible with inserting into the Gwibber database for that update
1150+ """
1151 m = self._common(data)
1152
1153 if data["to_user_id"]:
1154@@ -187,6 +228,12 @@
1155 return m
1156
1157 def _profile(self, data):
1158+ """ Called when a user is clicked on.
1159+ Args:
1160+ data: A data object obtained from the StatusNet server containing a complete user
1161+ Returns:
1162+ A data object compatible with inserting into the Gwibber database for that user
1163+ """
1164 return {
1165 "name": data.get("name", data["screen_name"]),
1166 "service": "statusnet",
1167@@ -212,6 +259,16 @@
1168 }
1169
1170 def _get(self, path, parse="message", post=False, single=False, **args):
1171+ """ Establishes a connection with the StatusNet server and gets the data requested. Requires authentication.
1172+ Args:
1173+ path: The end of the url to look up on the StatusNet server
1174+ parse: The function to use to parse the data returned (message by default)
1175+ post: True is this is a send, False if a recieve (False by default)
1176+ single: True if a single checkin is requested, False if multiple (False by default)
1177+ **args: Args to be added to the url when accessed.
1178+ Returns:
1179+ A list of gwibber compatible objects which have been parsed by the parse function
1180+ """
1181 if not self.account.has_key("access_token") and not self.account.has_key("secret_token"):
1182 logger.error("%s unexpected result - %s", PROTOCOL_INFO["name"], _("Account needs to be re-authorized"))
1183 return [{"error": {"type": "auth", "account": self.account, "message": _("Account needs to be re-authorized")}}]
1184@@ -262,6 +319,13 @@
1185 return [self._result(m) for m in data]
1186
1187 def _search(self, **args):
1188+ """ Establishes a connection with the StatusNet server and gets the results of a search.
1189+ Does not require authentication
1190+ Args:
1191+ **args:
1192+ Returns:
1193+ A list of gwibber compatible objects which have been parsed by _result()
1194+ """
1195 data = network.Download("%s/api/search.json" % self.account["url_prefix"], util.compact(args))
1196 data = data.get_json()
1197
1198@@ -275,57 +339,159 @@
1199 return getattr(self, opname)(**args)
1200
1201 def receive(self, count=util.COUNT, since=None):
1202+ """ Gets the latest updates and adds them to the database.
1203+ Args:
1204+ None
1205+ Returns:
1206+ A list of gwibber compatible objects which have been parsed by _message()
1207+ """
1208 return self._get("statuses/friends_timeline.json", count=count, since_id=since, source="Gwibber")
1209
1210 def responses(self, count=util.COUNT, since=None):
1211+ """ Gets the latest replies and adds them to the database.
1212+ Args:
1213+ None
1214+ Returns:
1215+ A list of gwibber compatible objects which have been parsed by _responses()
1216+ """
1217 return self._get("statuses/mentions.json", count=count, since_id=since, source="Gwibber")
1218
1219 def private(self, count=util.COUNT, since=None):
1220+ """ Gets the latest direct messages sent and recieved and adds them to the database.
1221+ Args:
1222+ None
1223+ Returns:
1224+ A list of gwibber compatible objects which have been parsed by _private()
1225+ """
1226 private = self._get("direct_messages.json", "private", count=count, since_id=since, source="Gwibber") or []
1227 private_sent = self._get("direct_messages/sent.json", "private", count=count, since_id=since, source="Gwibber") or []
1228 return private + private_sent
1229
1230 def public(self, count=util.COUNT, since=None):
1231+ """ Gets the latest updates from the public timeline and adds them to the database.
1232+ Args:
1233+ None
1234+ Returns:
1235+ A list of gwibber compatible objects which have been parsed by _message()
1236+ """
1237 return self._get("statuses/public_timeline.json", source="Gwibber")
1238
1239 def search(self, query, count=util.COUNT, since=None):
1240+ """ Gets the latest results from a search and adds them to the database.
1241+ Args:
1242+ None
1243+ Returns:
1244+ A list of gwibber compatible objects which have been parsed by _search()
1245+ """
1246 return self._search(q=query, rpp=count, since_id=since, source="Gwibber")
1247
1248 def tag(self, query, count=util.COUNT, since=None):
1249+ """ Gets the latest results from a hashtag search and adds them to the database.
1250+ Args:
1251+ None
1252+ Returns:
1253+ A list of gwibber compatible objects which have been parsed by _search()
1254+ """
1255 return self._search(q="#%s" % query, count=count, since_id=since, source="Gwibber")
1256
1257 def delete(self, message):
1258+ """ Deletes a specified update from the StatusNet server
1259+ Args:
1260+ message: a gwibber compatible message object (from gwibber's database)
1261+ Returns:
1262+ Nothing
1263+ """
1264 self._get("statuses/destroy/%s.json" % message["mid"], None, post=True, do=1, source="Gwibber")
1265 return []
1266
1267 def like(self, message):
1268+ """ Favourites a specified update on the StatusNet server
1269+ Args:
1270+ message: a gwibber compatible message object (from gwibber's database)
1271+ Returns:
1272+ Nothing
1273+ """
1274 self._get("favorites/create/%s.json" % message["mid"], None, post=True, do=1, source="Gwibber")
1275 return []
1276
1277 def send(self, message):
1278+ """ Sends a message to the StatusNet server
1279+ Args:
1280+ message: The update's text
1281+ Returns:
1282+ Nothing
1283+ """
1284 return self._get("statuses/update.json", post=True, single=True, status=message, source="Gwibber")
1285
1286 def send_private(self, message, private):
1287+ """ Sends a direct message to the StatusNet server
1288+ Args:
1289+ message: The update's text
1290+ private: A gwibber compatible user object (from gwibber's database)
1291+ Returns:
1292+ Nothing
1293+ """
1294 return self._get("direct_messages/new.json", "private", post=True, single=True,
1295 text=message, screen_name=private["sender"]["nick"], source="Gwibber")
1296
1297 def send_thread(self, message, target):
1298+ """ Sends a reply to a user on the StatusNet server
1299+ Args:
1300+ message: The update's text
1301+ target: A gwibber compatible user object (from gwibber's database)
1302+ Returns:
1303+ Nothing
1304+ """
1305 return self._get("statuses/update.json", post=True, single=True,
1306 status=message, in_reply_to_status_id=target["mid"], source="Gwibber")
1307
1308 def retweet(self, message):
1309+ """ Shares an update
1310+ Args:
1311+ message: A gwibber compatible message object (from gwibber's database)
1312+ Returns:
1313+ Nothing
1314+ """
1315 return self._get("statuses/retweet/%s.json" % message["mid"], None, post=True, do=1, source="Gwibber")
1316
1317 def follow(self, screen_name):
1318+ """ Follows a user
1319+ Args:
1320+ screen_name: The screen name of the user to be followed
1321+ Returns:
1322+ Nothing
1323+ """
1324 return self._get("friendships/create.json", screen_name=screen_name, post=True, parse="follow", source="Gwibber")
1325
1326 def unfollow(self, screen_name):
1327+ """ Unfollows a user
1328+ Args:
1329+ screen_name: The screen name of the user to be unfollowed
1330+ Returns:
1331+ Nothing
1332+ """
1333 return self._get("friendships/destroy.json", screen_name=screen_name, post=True, parse="unfollow", source="Gwibber")
1334
1335 def profile(self, id=None, count=None, since=None):
1336+ """ Gets a user's profile
1337+ Args:
1338+ id: The user's screen name
1339+ count: Number of updates to get
1340+ since: Time to get updates since
1341+ Returns:
1342+ A list of gwibber compatible objects which have been parsed by _profile()
1343+ """
1344 return self._get("users/show.json", screen_name=id, count=count, since_id=since, parse="profile", source="Gwibber")
1345
1346 def user_messages(self, id=None, count=util.COUNT, since=None):
1347+ """ Gets a user's profile & timeline
1348+ Args:
1349+ id: The user's screen name
1350+ count: Number of updates to get
1351+ since: Time to get updates since
1352+ Returns:
1353+ A list of gwibber compatible objects which have been parsed by _profile()
1354+ """
1355 profiles = [self.profile(id)] or []
1356 messages = self._get("statuses/user_timeline.json", id=id, count=count, since_id=since, source="Gwibber") or []
1357 return messages + profiles
1358
1359=== modified file 'gwibber/microblog/plugins/statusnet/gtk/statusnet/__init__.py'
1360--- gwibber/microblog/plugins/statusnet/gtk/statusnet/__init__.py 2012-03-07 21:17:19 +0000
1361+++ gwibber/microblog/plugins/statusnet/gtk/statusnet/__init__.py 2012-05-13 20:44:18 +0000
1362@@ -67,6 +67,12 @@
1363 return True
1364
1365 def on_statusnet_auth_clicked(self, widget, data=None):
1366+ """ When the Authorize button is clicked, the Statusnet server authorisation window
1367+ is loaded for the user to enter their credentials for authorisation
1368+ Args:
1369+ widget:
1370+ data:
1371+ """
1372 self.url_prefix = self.ui.get_object("url_prefix").get_text()
1373 pref = "" if self.url_prefix.startswith("http") else "https://"
1374 self.url_prefix = pref + self.url_prefix
1375@@ -110,6 +116,10 @@
1376 self.ui.get_object("vbox_advanced").hide()
1377
1378 def on_statusnet_auth_title_change(self, web=None, title=None, data=None):
1379+ """ When the title of the authorisation window is changed, the user has entered their credentials
1380+ and pressed login. If login is successful, get the token & verifier from the callback uri. Exchange
1381+ these for the access token & secret. This is used for authentication for all subsequnt calls to the Statusnet server.
1382+ """
1383 saved = False
1384 if title.get_title() == "Success":
1385 try:
1386
1387=== modified file 'gwibber/microblog/plugins/twitter/__init__.py'
1388--- gwibber/microblog/plugins/twitter/__init__.py 2012-03-30 14:32:20 +0000
1389+++ gwibber/microblog/plugins/twitter/__init__.py 2012-05-13 20:44:18 +0000
1390@@ -60,6 +60,11 @@
1391 API_PREFIX = "https://api.twitter.com/1"
1392
1393 class Client ():
1394+ """ Client: The Client class is responsible for querying Twitter and turning the data obtained
1395+ into data that Gwibber can understand. Twitter uses a version of oauth for security.
1396+ Tokens have already been obtained when the account was set up in Gwibber and are used to
1397+ authenticate when getting data.
1398+ """
1399 def __init__(self, acct):
1400 self.service = util.getbus("Service")
1401 if acct.has_key("secret_token") and acct.has_key("password"): acct.pop("password")
1402@@ -73,6 +78,13 @@
1403 self.token = oauth.OAuthToken(acct["access_token"], acct["secret_token"])
1404
1405 def _common(self, data):
1406+ """ Parses messages into gwibber compatible forms. This function is common to all tweet types
1407+ and includes parsing of user mentions, hashtags, urls, images and videos
1408+ Args:
1409+ data: A data object obtained from Twitter containing a complete tweet
1410+ Returns:
1411+ m: A data object compatible with inserting into the Gwibber database for that tweet
1412+ """
1413 m = {}
1414 try:
1415 m["mid"] = str(data["id"])
1416@@ -84,7 +96,7 @@
1417 m["text"] = cgi.escape(m["text"])
1418 m["content"] = m["text"]
1419
1420- # Go through the entities in the tweet and use them to linkify/filter tweeks as appropriate
1421+ # Go through the entities in the tweet and use them to linkify/filter tweets as appropriate
1422 if data.has_key("entities"):
1423
1424 #Get mention entries
1425@@ -109,7 +121,7 @@
1426 pass
1427 hashtags.append(tag["text"])
1428
1429- # Get url entities - These usually go in the link stream, but if they're picturesor videos, they should go in the proper stream
1430+ # Get url entities - These usually go in the link stream, but if they're pictures or videos, they should go in the proper stream
1431 if data["entities"].has_key("urls"):
1432 for urls in data["entities"]["urls"]:
1433 url = cgi.escape (urls["url"])
1434@@ -201,6 +213,12 @@
1435 return m
1436
1437 def _user(self, user):
1438+ """ Parses the user portion of a tweet
1439+ Args:
1440+ user: A user object from a tweet
1441+ Returns:
1442+ A user object in a format compatible with gwibber's database
1443+ """
1444 return {
1445 "name": user.get("name", None),
1446 "nick": user.get("screen_name", None),
1447@@ -219,6 +237,14 @@
1448 }
1449
1450 def _message(self, data):
1451+ """ Parses messages into gwibber compatible forms. This is the initial function for
1452+ tweet parsing and parses retweeted status (the shared-by portion), source (the program the tweet was tweeted from)
1453+ and reply details (the in-reply-to portion). It sends the rest to _common() for further parsing
1454+ Args:
1455+ data: A data object obtained from Twitter containing a complete tweet
1456+ Returns:
1457+ m: A data object compatible with inserting into the Gwibber database for that tweet
1458+ """
1459 if type(data) != dict:
1460 logger.error("Cannot parse message data: %s", str(data))
1461 return {}
1462@@ -256,12 +282,27 @@
1463 return m
1464
1465 def _responses(self, data):
1466+ """ Sets the message type if the message should be in the replies stream.
1467+ It sends the rest to _message() for further parsing
1468+ Args:
1469+ data: A data object obtained from Twitter containing a complete tweet
1470+ Returns:
1471+ m: A data object compatible with inserting into the Gwibber database for that tweet
1472+ """
1473 m = self._message(data)
1474 m["type"] = None
1475
1476 return m
1477
1478 def _private(self, data):
1479+ """ Sets the message type and privacy if the message should be in the private stream.
1480+ Also parses the recipient as both sent & recieved messages can be in the private stream.
1481+ It sends the rest to _message() for further parsing
1482+ Args:
1483+ data: A data object obtained from Twitter containing a complete tweet
1484+ Returns:
1485+ m: A data object compatible with inserting into the Gwibber database for that tweet
1486+ """
1487 m = self._message(data)
1488 m["private"] = True
1489 m["type"] = None
1490@@ -279,6 +320,13 @@
1491 return m
1492
1493 def _result(self, data):
1494+ """ Called when a search is done in gwibber. Parses the sender and sends the rest to _common()
1495+ for further parsing
1496+ Args:
1497+ data: A data object obtained from Twitter containing a complete tweet
1498+ Returns:
1499+ m: A data object compatible with inserting into the Gwibber database for that tweet
1500+ """
1501 m = self._common(data)
1502
1503 if data["to_user_id"]:
1504@@ -296,6 +344,12 @@
1505 return m
1506
1507 def _profile(self, data):
1508+ """ Called when a user is clicked on.
1509+ Args:
1510+ data: A data object obtained from Twitter containing a complete user
1511+ Returns:
1512+ A data object compatible with inserting into the Gwibber database for that user
1513+ """
1514 if "error" in data:
1515 return {
1516 "error": data["error"]
1517@@ -324,7 +378,13 @@
1518 "time_zone": data.get("time_zone", "")
1519 }
1520
1521- def _list(self, data):
1522+ def _list(self, data):
1523+ """ Called when a list is clicked on.
1524+ Args:
1525+ data: A data object obtained from Twitter containing a complete list
1526+ Returns:
1527+ A data object compatible with inserting into the Gwibber database for that list
1528+ """
1529 return {
1530 "mid": data["id"],
1531 "service": "twitter",
1532@@ -347,6 +407,16 @@
1533 }
1534
1535 def _get(self, path, parse="message", post=False, single=False, **args):
1536+ """ Establishes a connection with Twitter and gets the data requested. Requires authentication.
1537+ Args:
1538+ path: The end of the url to look up on Twitter
1539+ parse: The function to use to parse the data returned (message by default)
1540+ post: True is this is a send, False if a recieve (False by default)
1541+ single: True if a single checkin is requested, False if multiple (False by default)
1542+ **args: Args to be added to the url when accessed.
1543+ Returns:
1544+ A list of gwibber compatible objects which have been parsed by the parse function
1545+ """
1546 url = "/".join((API_PREFIX, path))
1547
1548 request = oauth.OAuthRequest.from_consumer_and_token(self.consumer, self.token,
1549@@ -398,6 +468,13 @@
1550 else: return []
1551
1552 def _search(self, **args):
1553+ """ Establishes a connection with Twitter and gets the results of a search.
1554+ Does not require authentication
1555+ Args:
1556+ **args: The search terms
1557+ Returns:
1558+ A list of gwibber compatible objects which have been parsed by _result()
1559+ """
1560 data = network.Download("http://search.twitter.com/search.json", util.compact(args))
1561 data = data.get_json()["results"]
1562
1563@@ -411,64 +488,188 @@
1564 return getattr(self, opname)(**args)
1565
1566 def receive(self, count=util.COUNT, since=None):
1567+ """ Gets the latest tweets and adds them to the database.
1568+ Args:
1569+ count = number of updates to get
1570+ since = time to get updates since
1571+ Returns:
1572+ A list of gwibber compatible objects which have been parsed by _message()
1573+ """
1574 return self._get("statuses/home_timeline.json", include_entities=1, count=count, since_id=since)
1575
1576 def responses(self, count=util.COUNT, since=None):
1577+ """ Gets the latest replies and adds them to the database.
1578+ Args:
1579+ count = number of updates to get
1580+ since = time to get updates since
1581+ Returns:
1582+ A list of gwibber compatible objects which have been parsed by _responses()
1583+ """
1584 return self._get("statuses/mentions.json", "responses", include_entities=1, count=count, since_id=since)
1585
1586 def private(self, count=util.COUNT, since=None):
1587+ """ Gets the latest direct messages sent and recieved and adds them to the database.
1588+ Args:
1589+ count = number of updates to get
1590+ since = time to get updates since
1591+ Returns:
1592+ A list of gwibber compatible objects which have been parsed by _private()
1593+ """
1594 private = self._get("direct_messages.json", "private", include_entities=1, count=count, since_id=since) or []
1595 private_sent = self._get("direct_messages/sent.json", "private", count=count, since_id=since) or []
1596 return private + private_sent
1597
1598 def public(self):
1599+ """ Gets the latest tweets from the public timeline and adds them to the database.
1600+ Args:
1601+ None
1602+ Returns:
1603+ A list of gwibber compatible objects which have been parsed by _message()
1604+ """
1605 return self._get("statuses/public_timeline.json", include_entities=1)
1606
1607 def lists(self, **args):
1608+ """ Gets subscribed lists and adds them to the database.
1609+ Args:
1610+ None
1611+ Returns:
1612+ A list of gwibber compatible objects which have been parsed by _list()
1613+ """
1614 following = self._get("%s/lists/subscriptions.json" % self.account["username"], "list") or []
1615 lists = self._get("%s/lists.json" % self.account["username"], "list") or []
1616 return following + lists
1617
1618- def list(self, user, id, count=util.COUNT, since=None):
1619+ def list(self, user, id, count=util.COUNT, since=None):
1620+ """ Gets the latest tweets from subscribed lists and adds them to the database.
1621+ Args:
1622+ user = the user's name whose lists are to be got
1623+ id = the user's id whose lists are to be got
1624+ count = number of updates to get
1625+ since = time to get updates since
1626+ Returns:
1627+ A list of gwibber compatible objects which have been parsed by _message()
1628+ """
1629 return self._get("%s/lists/%s/statuses.json" % (user, id), include_entities=1, per_page=count, since_id=since)
1630
1631 def search(self, query, count=util.COUNT, since=None):
1632+ """ Gets the latest results from a search and adds them to the database.
1633+ Args:
1634+ query = the search query
1635+ count = number of updates to get
1636+ since = time to get updates since
1637+ Returns:
1638+ A list of gwibber compatible objects which have been parsed by _search()
1639+ """
1640 return self._search(include_entities=1, q=query, rpp=count, since_id=since)
1641
1642 def tag(self, query, count=util.COUNT, since=None):
1643+ """ Gets the latest results from a hashtag search and adds them to the database.
1644+ Args:
1645+ query = the search query (hashtag without the #)
1646+ count = number of updates to get
1647+ since = time to get updates since
1648+ Returns:
1649+ A list of gwibber compatible objects which have been parsed by _search()
1650+ """
1651 return self._search(q="#%s" % query, count=count, since_id=since)
1652
1653 def delete(self, message):
1654+ """ Deletes a specified tweet from twitter
1655+ Args:
1656+ message: a gwibber compatible message object (from gwibber's database)
1657+ Returns:
1658+ Nothing
1659+ """
1660 return self._get("statuses/destroy/%s.json" % message["mid"], None, post=True, do=1)
1661
1662 def like(self, message):
1663+ """ Favourites a specified tweet on twitter
1664+ Args:
1665+ message: a gwibber compatible message object (from gwibber's database)
1666+ Returns:
1667+ Nothing
1668+ """
1669 return self._get("favorites/create/%s.json" % message["mid"], None, post=True, do=1)
1670
1671 def send(self, message):
1672+ """ Sends a tweet to twitter
1673+ Args:
1674+ message: The tweet's text
1675+ Returns:
1676+ Nothing
1677+ """
1678 return self._get("statuses/update.json", post=True, single=True,
1679 status=message)
1680
1681 def send_private(self, message, private):
1682+ """ Sends a direct message to twitter
1683+ Args:
1684+ message: The tweet's text
1685+ private: A gwibber compatible user object (from gwibber's database)
1686+ Returns:
1687+ Nothing
1688+ """
1689 return self._get("direct_messages/new.json", "private", post=True, single=True,
1690 text=message, screen_name=private["sender"]["nick"])
1691
1692 def send_thread(self, message, target):
1693+ """ Sends a reply to a user on twitter
1694+ Args:
1695+ message: The tweet's text
1696+ target: A gwibber compatible user object (from gwibber's database)
1697+ Returns:
1698+ Nothing
1699+ """
1700 return self._get("statuses/update.json", post=True, single=True,
1701 status=message, in_reply_to_status_id=target["mid"])
1702
1703 def retweet(self, message):
1704+ """ Retweets a tweet
1705+ Args:
1706+ message: A gwibber compatible message object (from gwibber's database)
1707+ Returns:
1708+ Nothing
1709+ """
1710 return self._get("statuses/retweet/%s.json" % message["mid"], None, post=True, do=1)
1711
1712 def follow(self, screen_name):
1713+ """ Follows a user
1714+ Args:
1715+ screen_name: The screen name (@someone without the @) of the user to be followed
1716+ Returns:
1717+ Nothing
1718+ """
1719 return self._get("friendships/create.json", screen_name=screen_name, post=True, parse="follow")
1720
1721 def unfollow(self, screen_name):
1722+ """ Unfollows a user
1723+ Args:
1724+ screen_name: The screen name (@someone without the @) of the user to be unfollowed
1725+ Returns:
1726+ Nothing
1727+ """
1728 return self._get("friendships/destroy.json", screen_name=screen_name, post=True, parse="unfollow")
1729
1730 def profile(self, id=None, count=None, since=None):
1731+ """ Gets a user's profile
1732+ Args:
1733+ id: The user's screen name
1734+ count: Number of tweets to get
1735+ since: Time to get tweets since
1736+ Returns:
1737+ A list of gwibber compatible objects which have been parsed by _profile()
1738+ """
1739 return self._get("users/show.json", screen_name=id, count=count, since_id=since, parse="profile")
1740
1741 def user_messages(self, id=None, count=util.COUNT, since=None):
1742+ """ Gets a user's profile & timeline
1743+ Args:
1744+ id: The user's screen name
1745+ count: Number of tweets to get
1746+ since: Time to get tweets since
1747+ Returns:
1748+ A list of gwibber compatible objects which have been parsed by _profile()
1749+ """
1750 profiles = [self.profile(id)] or []
1751 messages = self._get("statuses/user_timeline.json", id=id, include_entities=1, count=count, since_id=since) or []
1752 return messages + profiles
1753
1754=== modified file 'gwibber/microblog/plugins/twitter/gtk/twitter/__init__.py'
1755--- gwibber/microblog/plugins/twitter/gtk/twitter/__init__.py 2012-03-07 21:17:19 +0000
1756+++ gwibber/microblog/plugins/twitter/gtk/twitter/__init__.py 2012-05-13 20:44:18 +0000
1757@@ -56,6 +56,12 @@
1758 return True
1759
1760 def on_twitter_auth_clicked(self, widget, data=None):
1761+ """ When the Authorize button is clicked, the Twitter authorisation window
1762+ is loaded for the user to enter their credentials for authorisation
1763+ Args:
1764+ widget:
1765+ data:
1766+ """
1767 self.winsize = self.window.get_size()
1768
1769 web = WebKit.WebView()
1770@@ -93,6 +99,10 @@
1771 self.dialog.infobar.set_message_type(Gtk.MessageType.INFO)
1772
1773 def on_twitter_auth_title_change(self, web=None, title=None, data=None):
1774+ """ When the title of the authorisation window is changed, the user has entered their credentials
1775+ and pressed login. If login is successful, get the token & verifier from the callback uri. Exchange
1776+ these for the access token & secret. This is used for authentication for all subsequnt calls to Twitter.
1777+ """
1778 saved = False
1779 uri = title.get_uri ()
1780 if hasattr(self.dialog, "infobar_content_area"):
1781
1782=== modified file 'gwibber/microblog/util/__init__.py'
1783--- gwibber/microblog/util/__init__.py 2012-04-20 21:16:37 +0000
1784+++ gwibber/microblog/util/__init__.py 2012-05-13 20:44:18 +0000
1785@@ -65,6 +65,12 @@
1786 return re.compile(r'"www.', re.U).sub('"http://www.', link)
1787
1788 def imgpreview(text):
1789+ """ Parses text for image short urls and convert them into image objects
1790+ Args:
1791+ text: the text to be parsed (an image url or a shorturl for an image)
1792+ Returns:
1793+ images: an image object
1794+ """
1795 images = []
1796
1797 # If the text is a direct link to a jpg
1798@@ -145,7 +151,6 @@
1799 'bcphotoshare': 'http://images.bcphotoshare.com/storages/@/thumbnail.jpg'
1800 }
1801
1802-
1803 for r, u in zip(thumbre, thumburi):
1804 for match in re.finditer(thumbre[r], text):
1805 if r == 'tweetphoto' or r == 'pic.gd' or r == 'moby.to':
1806@@ -155,6 +160,12 @@
1807 return images
1808
1809 def videopreview(text):
1810+ """ Parses text for video short urls and convert them into video objects
1811+ Args:
1812+ text: the text to be parsed (a shorturl for a video)
1813+ Returns:
1814+ images: a video object
1815+ """
1816 videos = []
1817
1818 thumbre = {
1819@@ -178,7 +189,7 @@
1820
1821 for r, u in zip(thumbre, thumburi):
1822 for match in re.finditer(thumbre[r], text):
1823- videos.append({ "src": thumburi[u].replace('@', match.group(1)), "url" : text})
1824+ videos.append({ "src": thumburi[u].replace('@', match.group(1)), "url": text})
1825 return videos
1826
1827 def compact(data):

Subscribers

People subscribed via source and target branches