[tor-commits] [bridgedb/master] Add more documentation to captcha.ReCaptcha class and its methods.

[isis at torproject.org]

commit c011ab8cacca785d30d076eb243c98d2988ec396
Author: Isis Lovecruft <isis at torproject.org>
Date:   Tue Mar 11 20:51:01 2014 +0000

    Add more documentation to captcha.ReCaptcha class and its methods.
---
 lib/bridgedb/captcha.py |   18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/lib/bridgedb/captcha.py b/lib/bridgedb/captcha.py
index 728cfaf..721f72e 100644
--- a/lib/bridgedb/captcha.py
+++ b/lib/bridgedb/captcha.py
@@ -81,9 +81,19 @@ class Captcha(object):
 
 
 class ReCaptcha(Captcha):
-    """A reCaptcha CAPTCHA."""
+    """A reCaptcha CAPTCHA.
+
+    :ivar str image: The CAPTCHA image.
+    :ivar str challenge: The ``'recaptcha_challenge_response'`` HTTP form
+        field to pass to the client along with the CAPTCHA image.
+    """
 
     def __init__(self, pubkey=None, privkey=None):
+        """Create a new ReCaptcha CAPTCHA.
+
+        :param str pubkey: The public reCaptcha API key.
+        :param str privkey: The private reCaptcha API key.
+        """
         super(ReCaptcha, self).__init__()
         self.pubkey = pubkey
         self.privkey = privkey
@@ -96,6 +106,10 @@ class ReCaptcha(Captcha):
         HTML to extract the CAPTCHA image and challenge string. The image is
         stored at ``ReCaptcha.image`` and the challenge string at
         ``ReCaptcha.challenge``.
+
+        :raises ReCaptchaKeyError: If either the :ivar:`pubkey` or
+            :ivar:`privkey` are missing.
+        :raises HTTPError: If the server returned any HTTP error status code.
         """
         if not self.pubkey or not self.privkey:
             raise ReCaptchaKeyError('You must supply recaptcha API keys')
@@ -103,7 +117,7 @@ class ReCaptcha(Captcha):
         urlbase = API_SSL_SERVER
         form = "/noscript?k=%s" % self.pubkey
 
-        # extract and store image from captcha
+        # Extract and store image from recaptcha
         html = urllib2.urlopen(urlbase + form).read()
         soup = BeautifulSoup(html)
         imgurl = urlbase + "/" +  soup.find('img')['src']