[tor-commits] [bridgedb/master] Reformat docstrings and update some descriptions in bridgedb.HTTPServer.

isis at torproject.org isis at torproject.org
Sun Mar 16 19:04:58 UTC 2014


commit ebf0ef7c3900646de957cd73551531b33541b761
Author: Isis Lovecruft <isis at torproject.org>
Date:   Wed Mar 12 00:01:00 2014 +0000

    Reformat docstrings and update some descriptions in bridgedb.HTTPServer.
---
 lib/bridgedb/HTTPServer.py |  123 ++++++++++++++++++++++++--------------------
 1 file changed, 66 insertions(+), 57 deletions(-)

diff --git a/lib/bridgedb/HTTPServer.py b/lib/bridgedb/HTTPServer.py
index 9411ec1..4deac25 100644
--- a/lib/bridgedb/HTTPServer.py
+++ b/lib/bridgedb/HTTPServer.py
@@ -28,6 +28,7 @@ import bridgedb.Util as Util
 
 from recaptcha.client import captcha as recaptcha
 from bridgedb import captcha
+from bridgedb import crypto
 from bridgedb.Filters import filterBridgesByIP6, filterBridgesByIP4
 from bridgedb.Filters import filterBridgesByTransport
 from bridgedb.Filters import filterBridgesByNotBlockedIn
@@ -153,9 +154,9 @@ class CaptchaProtectedResource(twisted.web.resource.Resource):
         :type request: :api:`twisted.web.http.Request`
         :param request: A ``Request`` object for 'bridges.html'.
         :returns: A redirect for a request for a new CAPTCHA if there was a
-                  problem. Otherwise, returns a 2-tuple of strings, the first
-                  is the client's CAPTCHA solution from the text input area,
-                  and the second is the challenge string.
+            problem. Otherwise, returns a 2-tuple of strings, the first is the
+            client's CAPTCHA solution from the text input area, and the second
+            is the challenge string.
         """
         try:
             challenge = request.args['captcha_challenge_field'][0]
@@ -169,7 +170,7 @@ class CaptchaProtectedResource(twisted.web.resource.Resource):
 
         :rtype: bool
         :returns: ``True`` if the client correctly solved the CAPTCHA;
-                  ``False`` otherwise.
+            ``False`` otherwise.
         """
         return False
 
@@ -178,10 +179,10 @@ class CaptchaProtectedResource(twisted.web.resource.Resource):
 
         :type request: :api:`twisted.web.http.Request`
         :param request: A ``Request`` object for a page which should be
-                        protected by a CAPTCHA.
+            protected by a CAPTCHA.
         :rtype: str
         :returns: A rendered HTML page containing a ReCaptcha challenge image
-                  for the client to solve.
+            for the client to solve.
         """
         image, challenge = self.getCaptchaImage(request)
 
@@ -204,11 +205,12 @@ class CaptchaProtectedResource(twisted.web.resource.Resource):
         request. Otherwise, redirect them back to a new CAPTCHA page.
 
         :type request: :api:`twisted.web.http.Request`
+
         :param request: A ``Request`` object, including POST arguments which
-                        should include two key/value pairs: one key being
-                        ``'captcha_challenge_field'``, and the other,
-                        ``'captcha_response_field'``. These POST arguments
-                        should be obtained from :meth:`render_GET`.
+            should include two key/value pairs: one key being
+            ``'captcha_challenge_field'``, and the other,
+            ``'captcha_response_field'``. These POST arguments should be
+            obtained from :meth:`render_GET`.
         :rtype: str
         :returns: A rendered HTML page containing a ReCaptcha challenge image
                   for the client to solve.
@@ -227,7 +229,7 @@ class CaptchaProtectedResource(twisted.web.resource.Resource):
 
 class GimpCaptchaProtectedResource(CaptchaProtectedResource):
     """A web resource which uses a local cache of CAPTCHAs, generated with
-    gimp-captcha.
+    gimp-captcha_, to protect another resource.
 
     .. _gimp-captcha: https://github.com/isislovecruft/gimp-captcha
     """
@@ -245,7 +247,6 @@ class GimpCaptchaProtectedResource(CaptchaProtectedResource):
         a completely random IP is generated and sent instead.
 
         :type request: :api:`twisted.web.http.Request`
-
         :param request: A ``Request`` object, including POST arguments which
             should include two key/value pairs: one key being
             ``'captcha_challenge_field'``, and the other,
@@ -268,6 +269,9 @@ class GimpCaptchaProtectedResource(CaptchaProtectedResource):
         :meth:`~bridgedb.captcha.GimpCaptcha.get` method to return a random
         CAPTCHA and challenge string.
 
+        :type request: :api:`twisted.web.http.Request`
+        :param request: A client's initial request for some other resource
+            which is protected by this one (i.e. protected by a CAPTCHA).
         :returns: A 2-tuple of ``(image, challenge)``, where::
             - ``image`` is a string holding a binary, JPEG-encoded image.
             - ``challenge`` is a unique string associated with the request.
@@ -286,14 +290,15 @@ class GimpCaptchaProtectedResource(CaptchaProtectedResource):
         return (c.image, c.challenge)
 
     def render_GET(self, request):
-        """Retrieve a ReCaptcha from the API server and serve it to the client.
+        """Get a random CAPTCHA from our local cache directory and serve it to
+        the client.
 
         :type request: :api:`twisted.web.http.Request`
         :param request: A ``Request`` object for a page which should be
-                        protected by a CAPTCHA.
+            protected by a CAPTCHA.
         :rtype: str
         :returns: A rendered HTML page containing a ReCaptcha challenge image
-                  for the client to solve.
+           for the client to solve.
         """
         return CaptchaProtectedResource.render_GET(self, request)
 
@@ -306,13 +311,13 @@ class GimpCaptchaProtectedResource(CaptchaProtectedResource):
 
         :type request: :api:`twisted.web.http.Request`
         :param request: A ``Request`` object, including POST arguments which
-                        should include two key/value pairs: one key being
-                        ``'captcha_challenge_field'``, and the other,
-                        ``'captcha_response_field'``. These POST arguments
-                        should be obtained from :meth:`render_GET`.
+            should include two key/value pairs: one key being
+            ``'captcha_challenge_field'``, and the other,
+            ``'captcha_response_field'``. These POST arguments should be
+            obtained from :meth:`render_GET`.
         :rtype: str
         :returns: A rendered HTML page containing a ReCaptcha challenge image
-                  for the client to solve.
+            for the client to solve.
         """
         return CaptchaProtectedResource.render_POST(self, request)
 
@@ -375,10 +380,10 @@ class ReCaptchaProtectedResource(CaptchaProtectedResource):
 
         :type request: :api:`twisted.web.http.Request`
         :param request: A ``Request`` object, including POST arguments which
-                        should include two key/value pairs: one key being
-                        ``'captcha_challenge_field'``, and the other,
-                        ``'captcha_response_field'``. These POST arguments
-                        should be obtained from :meth:`render_GET`.
+            should include two key/value pairs: one key being
+            ``'captcha_challenge_field'``, and the other,
+            ``'captcha_response_field'``. These POST arguments should be
+            obtained from :meth:`render_GET`.
         :rtupe: bool
         :returns: True, if the CAPTCHA solution was valid; False otherwise.
         """
@@ -418,11 +423,12 @@ class ReCaptchaProtectedResource(CaptchaProtectedResource):
         request. Otherwise, redirect them back to a new CAPTCHA page.
 
         :type request: :api:`twisted.web.http.Request`
+
         :param request: A ``Request`` object, including POST arguments which
-                        should include two key/value pairs: one key being
-                        ``'captcha_challenge_field'``, and the other,
-                        ``'captcha_response_field'``. These POST arguments
-                        should be obtained from :meth:`render_GET`.
+            should include two key/value pairs: one key being
+            ``'captcha_challenge_field'``, and the other,
+            ``'captcha_response_field'``. These POST arguments should be
+            obtained from :meth:`render_GET`.
         :rtype: str
         :returns: A rendered HTML page containing a ReCaptcha challenge image
                   for the client to solve.
@@ -430,7 +436,6 @@ class ReCaptchaProtectedResource(CaptchaProtectedResource):
         return CaptchaProtectedResource.render_POST(self, request)
 
 
-
 class WebResourceOptions(twisted.web.resource.Resource):
     """This resource is used by Twisted Web to give a web page with
        additional options that the user may use to specify the criteria
@@ -468,20 +473,19 @@ class WebResourceBridges(twisted.web.resource.Resource):
 
     def __init__(self, distributor, schedule, N=1, useForwardedHeader=False,
                  includeFingerprints=True):
-        """Create a new WebResource.
+        """Create a new resource for displaying bridges to a client.
 
         :type distributor: :class:`IPBasedDistributor`
         :param distributor: The mechanism to retrieve bridges for this
-                            distributor.
+            distributor.
         :type schedule: :class:`IntervalSchedule`
         :param schedule: The time period used to tweak the bridge selection
-                         procedure.
+            procedure.
         :param int N: The number of bridges to hand out per query.
         :param bool useForwardedHeader: Whether or not we should use the the
-                                        X-Forwarded-For header instead of the
-                                        source IP address.
+            X-Forwarded-For header instead of the source IP address.
         :param bool includeFingerprints: Do we include the bridge's
-                                         fingerprint in the response?
+            fingerprint in the response?
         """
         gettext.install("bridgedb", unicode=True)
         twisted.web.resource.Resource.__init__(self)
@@ -502,7 +506,7 @@ class WebResourceBridges(twisted.web.resource.Resource):
 
         :type request: :api:`twisted.web.http.Request`
         :param request: A ``Request`` object containing the HTTP method, full
-                        URI, and any URL/POST arguments and headers present.
+            URI, and any URL/POST arguments and headers present.
         :rtype: str
         :returns: A plaintext or HTML response to serve.
         """
@@ -519,7 +523,7 @@ class WebResourceBridges(twisted.web.resource.Resource):
 
         :type request: :api:`twisted.web.http.Request`
         :param request: A ``Request`` object containing the HTTP method, full
-                        URI, and any URL/POST arguments and headers present.
+            URI, and any URL/POST arguments and headers present.
         :rtype: str
         :returns: A plaintext or HTML response to serve.
         """
@@ -613,17 +617,16 @@ class WebResourceBridges(twisted.web.resource.Resource):
 
         :type request: :api:`twisted.web.http.Request`
         :param request: A ``Request`` object containing the HTTP method, full
-                        URI, and any URL/POST arguments and headers present.
+            URI, and any URL/POST arguments and headers present.
         :type bridgeLines: list or None
         :param bridgeLines: A list of strings used to configure a Tor client
-                            to use a bridge.
+            to use a bridge.
         :param bool rtl: If ``True``, the language used for the response to
-                         the client should be rendered right-to-left.
+            the client should be rendered right-to-left.
         :type format: str or None
         :param format: If ``'plain'``, return a plaintext response. Otherwise,
-                       use the :file:`bridgedb/templates/bridges.html`
-                       template to render an HTML response page which includes
-                       the **bridges**.
+            use the :file:`bridgedb/templates/bridges.html` template to render
+            an HTML response page which includes the **bridges**.
         :rtype: str
         :returns: A plaintext or HTML response to serve.
         """
@@ -670,20 +673,26 @@ class WebRoot(twisted.web.resource.Resource):
 
 def addWebServer(cfg, dist, sched):
     """Set up a web server.
-         cfg -- a configuration object from Main.  We use these options:
-                HTTPS_N_BRIDGES_PER_ANSWER
-                HTTP_UNENCRYPTED_PORT
-                HTTP_UNENCRYPTED_BIND_IP
-                HTTP_USE_IP_FROM_FORWARDED_HEADER
-                HTTPS_PORT
-                HTTPS_BIND_IP
-                HTTPS_USE_IP_FROM_FORWARDED_HEADER
-                RECAPTCHA_ENABLED
-                RECAPTCHA_PUB_KEY
-                RECAPTCHA_PRIV_KEY
-                RECAPTCHA_REMOTEIP
-         dist -- an IPBasedDistributor object.
-         sched -- an IntervalSchedule object.
+
+    :param cfg: A configuration object from :mod:`bridgedb.Main`. Currently,
+         we use these options::
+             HTTPS_N_BRIDGES_PER_ANSWER
+             HTTP_UNENCRYPTED_PORT
+             HTTP_UNENCRYPTED_BIND_IP
+             HTTP_USE_IP_FROM_FORWARDED_HEADER
+             HTTPS_PORT
+             HTTPS_BIND_IP
+             HTTPS_USE_IP_FROM_FORWARDED_HEADER
+             RECAPTCHA_ENABLED
+             RECAPTCHA_PUB_KEY
+             RECAPTCHA_PRIV_KEY
+             RECAPTCHA_REMOTEIP
+             GIMP_CAPTCHA_ENABLED
+             GIMP_CAPTCHA_DIR
+    :type dist: :class:`bridgedb.Dist.IPBasedDistributor`
+    :param dist: A bridge distributor.
+    :type sched: :class:`bridgedb.Time.IntervalSchedule`
+    :param sched: DOCDOC
     """
     httpdist = twisted.web.resource.Resource()
     httpdist.putChild('', WebRoot())





More information about the tor-commits mailing list