Added docstrings to long_tweets package

src/sessions/twitter/client.py

@@ -1,11 +1,12 @@
 # -*- coding: utf-8 -*-
-import config
 import random
 import webbrowser
+import logging
+import config
+from requests import certs
 from twython import Twython, TwythonError
 from keys import keyring
-from requests import certs
-import logging
+
 log = logging.getLogger("sessionTwitter")
 
 class twitter(object):

src/sessions/twitter/long_tweets/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+""" this package  holds different modules to extract information regarding long tweets. A long tweet contains more than one tweet (such a quoted tweet), or is made via services like twishort."""

src/sessions/twitter/long_tweets/tweets.py

@@ -19,6 +19,9 @@
 from sessions.twitter import utils
 
 def is_long(tweet):
+ """ Check if the passed tweet contains a quote in its metadata.
+  tweet dict: a tweet dictionary.
+  returns True if a quote is detected, False otherwise."""
  if tweet.has_key("quoted_status_id") and tweet.has_key("quoted_status"):
   return tweet["quoted_status_id"]
  elif tweet.has_key("retweeted_status") and tweet["retweeted_status"].has_key("quoted_status_id") and tweet["retweeted_status"].has_key("quoted_status"):
@@ -26,6 +29,9 @@ def is_long(tweet):
  return False
 
 def clear_url(tweet):
+ """ Reads data from a quoted tweet and removes the link to the Status from the tweet's text.
+  tweet dict: a tweet dictionary.
+  returns a tweet dictionary without the URL to the status ID in its text to display."""
  if tweet.has_key("retweeted_status"):
   if tweet["retweeted_status"].has_key("full_text"):
    value = "full_text"

src/sessions/twitter/long_tweets/twishort.py

@@ -16,20 +16,26 @@
 #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 ############################################################
+import logging
 import requests
 import keys
-import logging
-log = logging.getLogger("long_tweets.twishort")
-from sessions.twitter import utils
 from requests_oauthlib import OAuth1Session
+from sessions.twitter import utils
+
+log = logging.getLogger("long_tweets.twishort")
 
 def get_twishort_uri(url):
+ """ Takes A twishort URl and returns the twishort ID.
+  url str: an url like http://twishort.com/id.
+  returns a twishort ID if the URL is valid, False otherwise."""
  try:
   return url.split("twishort.com/")[1]
  except ValueError:
   return False
 
 def is_long(tweet):
+ """ Check if the passed tweet is made with Twishort.
+  returns True if is a long tweet, False otherwise."""
  long = False
  for url in range(0, len(tweet["entities"]["urls"])):
   try:
@@ -53,17 +59,25 @@ def is_long(tweet):
  return long
 
 def get_full_text(uri):
+ """ Get Twishort's full text.
+  uri str: Twishort's identifier.
+  returns the contents of the tweet."""
  try:
   r = requests.get("http://api.twishort.com/1.1/get.json", params={"uri": uri, "api_key": keys.keyring.get("twishort_api_key")})
   msg = r.json()["text"]
   # Try to parse possible HTML entities.
-  from twitter.compose import StripChars
+  from sessions.twitter.compose import StripChars
   msg = StripChars(msg)
   return msg
  except:
   return False
 
 def create_tweet(user_token, user_secret, text, media=0):
+ """ Send a tweet to be extended by using Twishort.
+ user_token, user_secret str: Twitter user access key and secret, used by TWBlue to authorise against Twitter.
+ text str: Tweet text, max 10000 characters.
+ media int: Not used currently.
+ Returns text to be placed in the Tweet if the post has been succeeded, 0 otherwise."""
  twitter = OAuth1Session(keys.keyring.get("api_key"), client_secret=keys.keyring.get("api_secret"), resource_owner_key=user_token, resource_owner_secret=user_secret)
  twishort_key=keys.keyring.get("twishort_api_key")
  x_auth_service_provider = "https://api.twitter.com/1.1/account/verify_credentials.json"
@@ -84,4 +98,4 @@ def create_tweet(user_token, user_secret, text, media=0):
   return response.json()["text_to_tweet"]
  except:
   print "There was a problem creating a long tweet"
-  return 0
+  return 0