added docs and removed lambdas

indicoio/text/sentiment.py

@@ -4,14 +4,57 @@ import json
 from indicoio import JSON_HEADERS
 from indicoio.utils import normalize
 
-base_url = lambda c: "http://api.indico.io/%s" % c
+def political(text):
+    """
+    Given input text, returns a probability distribution over the political alignment of the speaker.
 
-def political(test_text):
-    data_dict = json.dumps({'text': test_text})
-    response = requests.post(base_url("political"), data=data_dict, headers=JSON_HEADERS)
+    Example usage:
+
+    .. code-block:: python
+
+       >>> from indicoio import political
+       >>> import numpy as np
+       >>> text = 'Wish we had more bike lanes. \
+       Hopefully, driverless cars will chance economics from ownership to fee for service.'
+       >>> affiliation = political(text)
+       >>> affiliation
+       {u'Libertarian': 0.4923755446986322, u'Green': 0.2974443102818122, 
+       u'Liberal': 0.13730032938784784, u'Conservative': 0.07287981563170784}
+       >>> least_like = affiliation.keys()[np.argmin(affiliation.values())]
+       >>> most_like = affiliation.keys()[np.argmax(affiliation.values())]
+       >>> 'This text is most like %s and least like %s'%(most_like,least_like)
+       u'This text is most like Libertarian and least like Conservative'
+
+    :param text: The text to be analyzed.
+    :type text: str or unicode
+    :rtype: Dictionary of party probability pairs
+    """
+
+    data_dict = json.dumps({'text': text})
+    response = requests.post("http://api.indico.io/political", data=data_dict, headers=JSON_HEADERS)
     return json.loads(response.content)
 
-def posneg(test_text):
-    data_dict = json.dumps({'text': test_text})
-    response = requests.post(base_url("sentiment"), data=data_dict, headers=JSON_HEADERS)
+def posneg(text):
+    """
+    Given input text, returns a scalar estimate of the sentiment of that text.
+    Values are roughly in the range 0 to 1 with 0.5 indicating neutral sentiment.
+    Likewise, 0 would suggest very negative sentiment and 1 would suggest very positive sentiment.
+
+    Example usage:
+
+    .. code-block:: python
+
+       >>> from indicoio import sentiment
+       >>> text = 'Thanks everyone for the birthday wishes!! It was a crazy few days ><'
+       >>> sentiment = sentiment(text)
+       >>> sentiment
+       {u'Sentiment': 0.6946439339979863}
+
+    :param text: The text to be analyzed.
+    :type text: str or unicode
+    :rtype: Dictionary containing Sentiment key with a float value
+    """
+    
+    data_dict = json.dumps({'text': text})
+    response = requests.post("http://api.indico.io/sentiment", data=data_dict, headers=JSON_HEADERS)
     return json.loads(response.content)