]> git.ipfire.org Git - thirdparty/tornado.git/commitdiff
Finish automatic documentation
authorBen Darnell <ben@bendarnell.com>
Sat, 11 Jun 2011 20:31:29 +0000 (13:31 -0700)
committerBen Darnell <ben@bendarnell.com>
Sat, 11 Jun 2011 20:31:29 +0000 (13:31 -0700)
16 files changed:
tornado/auth.py
tornado/database.py
tornado/options.py
tornado/stack_context.py
tornado/testing.py
tornado/websocket.py
tornado/wsgi.py
website/sphinx/auth.rst
website/sphinx/autoreload.rst
website/sphinx/database.rst
website/sphinx/httputil.rst
website/sphinx/options.rst
website/sphinx/stack_context.rst
website/sphinx/testing.rst
website/sphinx/websocket.rst
website/sphinx/wsgi.rst

index 056e8a6e445c925f4225c0cf73614f1b33c59b95..d4f50369b71703afb8e90070d7d2556d30bbd071 100644 (file)
@@ -28,20 +28,20 @@ They all take slightly different arguments due to the fact all these
 services implement authentication and authorization slightly differently.
 See the individual service classes below for complete documentation.
 
-Example usage for Google OpenID:
+Example usage for Google OpenID::
 
-class GoogleHandler(tornado.web.RequestHandler, tornado.auth.GoogleMixin):
-    @tornado.web.asynchronous
-    def get(self):
-        if self.get_argument("openid.mode", None):
-            self.get_authenticated_user(self.async_callback(self._on_auth))
-            return
-        self.authenticate_redirect()
+    class GoogleHandler(tornado.web.RequestHandler, tornado.auth.GoogleMixin):
+        @tornado.web.asynchronous
+        def get(self):
+            if self.get_argument("openid.mode", None):
+                self.get_authenticated_user(self.async_callback(self._on_auth))
+                return
+            self.authenticate_redirect()
 
-    def _on_auth(self, user):
-        if not user:
-            raise tornado.web.HTTPError(500, "Google auth failed")
-        # Save the user with, e.g., set_secure_cookie()
+        def _on_auth(self, user):
+            if not user:
+                raise tornado.web.HTTPError(500, "Google auth failed")
+            # Save the user with, e.g., set_secure_cookie()
 
 """
 
@@ -414,21 +414,21 @@ class TwitterMixin(OAuthMixin):
     you registered as your application's Callback URL.
 
     When your application is set up, you can use this Mixin like this
-    to authenticate the user with Twitter and get access to their stream:
+    to authenticate the user with Twitter and get access to their stream::
 
-    class TwitterHandler(tornado.web.RequestHandler,
-                         tornado.auth.TwitterMixin):
-        @tornado.web.asynchronous
-        def get(self):
-            if self.get_argument("oauth_token", None):
-                self.get_authenticated_user(self.async_callback(self._on_auth))
-                return
-            self.authorize_redirect()
+        class TwitterHandler(tornado.web.RequestHandler,
+                             tornado.auth.TwitterMixin):
+            @tornado.web.asynchronous
+            def get(self):
+                if self.get_argument("oauth_token", None):
+                    self.get_authenticated_user(self.async_callback(self._on_auth))
+                    return
+                self.authorize_redirect()
 
-        def _on_auth(self, user):
-            if not user:
-                raise tornado.web.HTTPError(500, "Twitter auth failed")
-            # Save the user using, e.g., set_secure_cookie()
+            def _on_auth(self, user):
+                if not user:
+                    raise tornado.web.HTTPError(500, "Twitter auth failed")
+                # Save the user using, e.g., set_secure_cookie()
 
     The user object returned by get_authenticated_user() includes the
     attributes 'username', 'name', and all of the custom Twitter user
@@ -472,25 +472,25 @@ class TwitterMixin(OAuthMixin):
         through authorize_redirect() and get_authenticated_user(). The
         user returned through that process includes an 'access_token'
         attribute that can be used to make authenticated requests via
-        this method. Example usage:
-
-        class MainHandler(tornado.web.RequestHandler,
-                          tornado.auth.TwitterMixin):
-            @tornado.web.authenticated
-            @tornado.web.asynchronous
-            def get(self):
-                self.twitter_request(
-                    "/statuses/update",
-                    post_args={"status": "Testing Tornado Web Server"},
-                    access_token=user["access_token"],
-                    callback=self.async_callback(self._on_post))
-
-            def _on_post(self, new_entry):
-                if not new_entry:
-                    # Call failed; perhaps missing permission?
-                    self.authorize_redirect()
-                    return
-                self.finish("Posted a message!")
+        this method. Example usage::
+
+            class MainHandler(tornado.web.RequestHandler,
+                              tornado.auth.TwitterMixin):
+                @tornado.web.authenticated
+                @tornado.web.asynchronous
+                def get(self):
+                    self.twitter_request(
+                        "/statuses/update",
+                        post_args={"status": "Testing Tornado Web Server"},
+                        access_token=user["access_token"],
+                        callback=self.async_callback(self._on_post))
+
+                def _on_post(self, new_entry):
+                    if not new_entry:
+                        # Call failed; perhaps missing permission?
+                        self.authorize_redirect()
+                        return
+                    self.finish("Posted a message!")
 
         """
         # Add the OAuth resource request signature if we have credentials
@@ -551,21 +551,21 @@ class FriendFeedMixin(OAuthMixin):
     application's Callback URL.
 
     When your application is set up, you can use this Mixin like this
-    to authenticate the user with FriendFeed and get access to their feed:
+    to authenticate the user with FriendFeed and get access to their feed::
 
-    class FriendFeedHandler(tornado.web.RequestHandler,
-                            tornado.auth.FriendFeedMixin):
-        @tornado.web.asynchronous
-        def get(self):
-            if self.get_argument("oauth_token", None):
-                self.get_authenticated_user(self.async_callback(self._on_auth))
-                return
-            self.authorize_redirect()
+        class FriendFeedHandler(tornado.web.RequestHandler,
+                                tornado.auth.FriendFeedMixin):
+            @tornado.web.asynchronous
+            def get(self):
+                if self.get_argument("oauth_token", None):
+                    self.get_authenticated_user(self.async_callback(self._on_auth))
+                    return
+                self.authorize_redirect()
 
-        def _on_auth(self, user):
-            if not user:
-                raise tornado.web.HTTPError(500, "FriendFeed auth failed")
-            # Save the user using, e.g., set_secure_cookie()
+            def _on_auth(self, user):
+                if not user:
+                    raise tornado.web.HTTPError(500, "FriendFeed auth failed")
+                # Save the user using, e.g., set_secure_cookie()
 
     The user object returned by get_authenticated_user() includes the
     attributes 'username', 'name', and 'description' in addition to
@@ -595,25 +595,25 @@ class FriendFeedMixin(OAuthMixin):
         through authorize_redirect() and get_authenticated_user(). The
         user returned through that process includes an 'access_token'
         attribute that can be used to make authenticated requests via
-        this method. Example usage:
-
-        class MainHandler(tornado.web.RequestHandler,
-                          tornado.auth.FriendFeedMixin):
-            @tornado.web.authenticated
-            @tornado.web.asynchronous
-            def get(self):
-                self.friendfeed_request(
-                    "/entry",
-                    post_args={"body": "Testing Tornado Web Server"},
-                    access_token=self.current_user["access_token"],
-                    callback=self.async_callback(self._on_post))
-
-            def _on_post(self, new_entry):
-                if not new_entry:
-                    # Call failed; perhaps missing permission?
-                    self.authorize_redirect()
-                    return
-                self.finish("Posted a message!")
+        this method. Example usage::
+
+            class MainHandler(tornado.web.RequestHandler,
+                              tornado.auth.FriendFeedMixin):
+                @tornado.web.authenticated
+                @tornado.web.asynchronous
+                def get(self):
+                    self.friendfeed_request(
+                        "/entry",
+                        post_args={"body": "Testing Tornado Web Server"},
+                        access_token=self.current_user["access_token"],
+                        callback=self.async_callback(self._on_post))
+
+                def _on_post(self, new_entry):
+                    if not new_entry:
+                        # Call failed; perhaps missing permission?
+                        self.authorize_redirect()
+                        return
+                    self.finish("Posted a message!")
 
         """
         # Add the OAuth resource request signature if we have credentials
@@ -672,20 +672,20 @@ class GoogleMixin(OpenIdMixin, OAuthMixin):
     Google, redirect with authenticate_redirect(). On return, parse the
     response with get_authenticated_user(). We send a dict containing the
     values for the user, including 'email', 'name', and 'locale'.
-    Example usage:
+    Example usage::
 
-    class GoogleHandler(tornado.web.RequestHandler, tornado.auth.GoogleMixin):
-       @tornado.web.asynchronous
-       def get(self):
-           if self.get_argument("openid.mode", None):
-               self.get_authenticated_user(self.async_callback(self._on_auth))
-               return
-        self.authenticate_redirect()
+        class GoogleHandler(tornado.web.RequestHandler, tornado.auth.GoogleMixin):
+           @tornado.web.asynchronous
+           def get(self):
+               if self.get_argument("openid.mode", None):
+                   self.get_authenticated_user(self.async_callback(self._on_auth))
+                   return
+            self.authenticate_redirect()
 
-        def _on_auth(self, user):
-            if not user:
-                raise tornado.web.HTTPError(500, "Google auth failed")
-            # Save the user with, e.g., set_secure_cookie()
+            def _on_auth(self, user):
+                if not user:
+                    raise tornado.web.HTTPError(500, "Google auth failed")
+                # Save the user with, e.g., set_secure_cookie()
 
     """
     _OPENID_ENDPOINT = "https://www.google.com/accounts/o8/ud"
@@ -746,21 +746,21 @@ class FacebookMixin(object):
     'facebook_api_key' and 'facebook_secret'.
 
     When your application is set up, you can use this Mixin like this
-    to authenticate the user with Facebook:
+    to authenticate the user with Facebook::
 
-    class FacebookHandler(tornado.web.RequestHandler,
-                          tornado.auth.FacebookMixin):
-        @tornado.web.asynchronous
-        def get(self):
-            if self.get_argument("session", None):
-                self.get_authenticated_user(self.async_callback(self._on_auth))
-                return
-            self.authenticate_redirect()
+        class FacebookHandler(tornado.web.RequestHandler,
+                              tornado.auth.FacebookMixin):
+            @tornado.web.asynchronous
+            def get(self):
+                if self.get_argument("session", None):
+                    self.get_authenticated_user(self.async_callback(self._on_auth))
+                    return
+                self.authenticate_redirect()
 
-        def _on_auth(self, user):
-            if not user:
-                raise tornado.web.HTTPError(500, "Facebook auth failed")
-            # Save the user using, e.g., set_secure_cookie()
+            def _on_auth(self, user):
+                if not user:
+                    raise tornado.web.HTTPError(500, "Facebook auth failed")
+                # Save the user using, e.g., set_secure_cookie()
 
     The user object returned by get_authenticated_user() includes the
     attributes 'facebook_uid' and 'name' in addition to session attributes
@@ -840,24 +840,24 @@ class FacebookMixin(object):
         The available Facebook methods are documented here:
         http://wiki.developers.facebook.com/index.php/API
 
-        Here is an example for the stream.get() method:
-
-        class MainHandler(tornado.web.RequestHandler,
-                          tornado.auth.FacebookMixin):
-            @tornado.web.authenticated
-            @tornado.web.asynchronous
-            def get(self):
-                self.facebook_request(
-                    method="stream.get",
-                    callback=self.async_callback(self._on_stream),
-                    session_key=self.current_user["session_key"])
-
-            def _on_stream(self, stream):
-                if stream is None:
-                   # Not authorized to read the stream yet?
-                   self.redirect(self.authorize_redirect("read_stream"))
-                   return
-                self.render("stream.html", stream=stream)
+        Here is an example for the stream.get() method::
+
+            class MainHandler(tornado.web.RequestHandler,
+                              tornado.auth.FacebookMixin):
+                @tornado.web.authenticated
+                @tornado.web.asynchronous
+                def get(self):
+                    self.facebook_request(
+                        method="stream.get",
+                        callback=self.async_callback(self._on_stream),
+                        session_key=self.current_user["session_key"])
+
+                def _on_stream(self, stream):
+                    if stream is None:
+                       # Not authorized to read the stream yet?
+                       self.redirect(self.authorize_redirect("read_stream"))
+                       return
+                    self.render("stream.html", stream=stream)
 
         """
         self.require_setting("facebook_api_key", "Facebook Connect")
@@ -926,26 +926,27 @@ class FacebookGraphMixin(OAuth2Mixin):
                               code, callback, extra_fields=None):
       """ Handles the login for the Facebook user, returning a user object.
 
-      Example usage:
-      class FacebookGraphLoginHandler(LoginHandler, tornado.auth.FacebookGraphMixin):
-        @tornado.web.asynchronous
-        def get(self):
-            if self.get_argument("code", False):
-                self.get_authenticated_user(
-                  redirect_uri='/auth/facebookgraph/',
-                  client_id=self.settings["facebook_api_key"],
-                  client_secret=self.settings["facebook_secret"],
-                  code=self.get_argument("code"),
-                  callback=self.async_callback(
-                    self._on_login))
-                return
-            self.authorize_redirect(redirect_uri='/auth/facebookgraph/',
-                                    client_id=self.settings["facebook_api_key"],
-                                    extra_params={"scope": "read_stream,offline_access"})
+      Example usage::
 
-        def _on_login(self, user):
-          logging.error(user)
-          self.finish()
+          class FacebookGraphLoginHandler(LoginHandler, tornado.auth.FacebookGraphMixin):
+            @tornado.web.asynchronous
+            def get(self):
+                if self.get_argument("code", False):
+                    self.get_authenticated_user(
+                      redirect_uri='/auth/facebookgraph/',
+                      client_id=self.settings["facebook_api_key"],
+                      client_secret=self.settings["facebook_secret"],
+                      code=self.get_argument("code"),
+                      callback=self.async_callback(
+                        self._on_login))
+                    return
+                self.authorize_redirect(redirect_uri='/auth/facebookgraph/',
+                                        client_id=self.settings["facebook_api_key"],
+                                        extra_params={"scope": "read_stream,offline_access"})
+
+            def _on_login(self, user):
+              logging.error(user)
+              self.finish()
 
       """
       http = httpclient.AsyncHTTPClient()
@@ -1011,25 +1012,25 @@ class FacebookGraphMixin(OAuth2Mixin):
         through authorize_redirect() and get_authenticated_user(). The
         user returned through that process includes an 'access_token'
         attribute that can be used to make authenticated requests via
-        this method. Example usage:
-
-        class MainHandler(tornado.web.RequestHandler,
-                          tornado.auth.FacebookGraphMixin):
-            @tornado.web.authenticated
-            @tornado.web.asynchronous
-            def get(self):
-                self.facebook_request(
-                    "/me/feed",
-                    post_args={"message": "I am posting from my Tornado application!"},
-                    access_token=self.current_user["access_token"],
-                    callback=self.async_callback(self._on_post))
-
-            def _on_post(self, new_entry):
-                if not new_entry:
-                    # Call failed; perhaps missing permission?
-                    self.authorize_redirect()
-                    return
-                self.finish("Posted a message!")
+        this method. Example usage::
+
+            class MainHandler(tornado.web.RequestHandler,
+                              tornado.auth.FacebookGraphMixin):
+                @tornado.web.authenticated
+                @tornado.web.asynchronous
+                def get(self):
+                    self.facebook_request(
+                        "/me/feed",
+                        post_args={"message": "I am posting from my Tornado application!"},
+                        access_token=self.current_user["access_token"],
+                        callback=self.async_callback(self._on_post))
+
+                def _on_post(self, new_entry):
+                    if not new_entry:
+                        # Call failed; perhaps missing permission?
+                        self.authorize_redirect()
+                        return
+                    self.finish("Posted a message!")
 
         """
         url = "https://graph.facebook.com" + path
index 38873f94d64476e49f65dbafc5512bef069861da..74daab6dc83a1ce0989093598a27f8e75bcf3df6 100644 (file)
@@ -28,7 +28,7 @@ class Connection(object):
     """A lightweight wrapper around MySQLdb DB-API connections.
 
     The main value we provide is wrapping rows in a dict/object so that
-    columns can be accessed by name. Typical usage:
+    columns can be accessed by name. Typical usage::
 
         db = database.Connection("localhost", "mydatabase")
         for article in db.query("SELECT * FROM articles"):
index fa48c97192b88c5bb37054c4dde2c904c153d270..e41e36785b7efecf94a96f3d4db9b2971be861f4 100644 (file)
@@ -16,7 +16,7 @@
 
 """A command line parsing module that lets modules define their own options.
 
-Each module defines its own options, e.g.,
+Each module defines its own options, e.g.::
 
     from tornado.options import define, options
 
@@ -31,14 +31,14 @@ Each module defines its own options, e.g.,
 The main() method of your application does not need to be aware of all of
 the options used throughout your program; they are all automatically loaded
 when the modules are loaded. Your main() method can parse the command line
-or parse a config file with:
+or parse a config file with::
 
     import tornado.options
     tornado.options.parse_config_file("/etc/server.conf")
     tornado.options.parse_command_line()
 
 Command line formats are what you would expect ("--myoption=myvalue").
-Config files are just Python files. Global names become options, e.g.,
+Config files are just Python files. Global names become options, e.g.::
 
     myoption = "myvalue"
     myotheroption = "myothervalue"
@@ -77,7 +77,7 @@ def define(name, default=None, type=None, help=None, metavar=None,
     turns into range(x, y) - very useful for long integer ranges.
 
     help and metavar are used to construct the automatically generated
-    command line help string. The help message is formatted like:
+    command line help string. The help message is formatted like::
 
        --name=METAVAR      help string
 
index e59d5c01a463294a9e24b0d469cced8edccb4a98..5b012c53d367a36d053edea7d76e30ea8866f523 100644 (file)
@@ -29,7 +29,8 @@ wrapping each AsyncHTTPClient callback in async_callback) to the mechanisms
 that transfer control from one context to another (e.g. AsyncHTTPClient
 itself, IOLoop, thread pools, etc).
 
-Example usage:
+Example usage::
+
     @contextlib.contextmanager
     def die_on_error():
         try:
@@ -65,9 +66,12 @@ class StackContext(object):
 
         Note that the parameter is a callable that returns a context
         manager, not the context itself.  That is, where for a
-        non-transferable context manager you would say
+        non-transferable context manager you would say::
+
           with my_context():
-        StackContext takes the function itself rather than its result:
+
+        StackContext takes the function itself rather than its result::
+
           with StackContext(my_context):
         '''
         self.context_factory = context_factory
index cd6837cfaac29e2d37db800cc2856cb8ebab203b..9c42e8a5f5814b905277e52b14d9a6078d0e8bee 100644 (file)
@@ -2,10 +2,13 @@
 """Support classes for automated testing.
 
 This module contains three parts:
+
 * AsyncTestCase/AsyncHTTPTestCase:  Subclasses of unittest.TestCase
   with additional support for testing asynchronous (IOLoop-based) code.
+
 * LogTrapTestCase:  Subclass of unittest.TestCase that discards log output
   from tests that pass and only produces output for failing tests.
+
 * main(): A simple test runner (wrapper around unittest.main()) with support
   for the tornado.autoreload module to rerun the tests when code changes.
 
@@ -56,7 +59,8 @@ class AsyncTestCase(unittest.TestCase):
     returned from self.wait.  It is possible to have multiple
     wait/stop cycles in the same test.
 
-    Example:
+    Example::
+
         # This test uses an asynchronous style similar to most async
         # application code.
         class MyTestCase(AsyncTestCase):
@@ -196,7 +200,8 @@ class AsyncHTTPTestCase(AsyncTestCase):
     Tests will typically use the provided self.http_client to fetch
     URLs from this server.
 
-    Example:
+    Example::
+
         class MyHTTPTest(AsyncHTTPTestCase):
             def get_app(self):
                 return Application([('/', MyHandler)...])
@@ -303,8 +308,10 @@ class LogTrapTestCase(unittest.TestCase):
 def main():
     """A simple test runner with autoreload support.
 
-    The easiest way to run a test is via the command line:
+    The easiest way to run a test is via the command line::
+
         python -m tornado.testing --autoreload tornado.test.stack_context_test
+
     See the standard library unittest module for ways in which tests can
     be specified.
 
@@ -312,7 +319,8 @@ def main():
     tornado/test/runtests.py.  This script should define a method all()
     which returns a test suite and then call tornado.testing.main().
     Note that even when a test script is used, the all() test suite may
-    be overridden by naming a single test on the command line.
+    be overridden by naming a single test on the command line::
+
         # Runs all tests
         tornado/test/runtests.py --autoreload
         # Runs one test
index 316ffb5f60ab86939d86008139505a7a2a6dd589..104349d730619bc8ee7b4bf8d9773cc1c09cd939 100644 (file)
@@ -33,7 +33,7 @@ class WebSocketHandler(tornado.web.RequestHandler):
     http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76.
 
     Here is an example Web Socket handler that echos back all received messages
-    back to the client:
+    back to the client::
 
       class EchoWebSocket(websocket.WebSocketHandler):
           def open(self):
@@ -53,7 +53,7 @@ class WebSocketHandler(tornado.web.RequestHandler):
     implement open() method rather than get() or post().
 
     If you map the handler above to "/websocket" in your application, you can
-    invoke it in JavaScript with:
+    invoke it in JavaScript with::
 
       var ws = new WebSocket("ws://localhost:8888/websocket");
       ws.onopen = function() {
index e500dfea9d526cbe1463ec77d28cdfc6b2cf284f..ab87a4ceaa2f01860a0b8457957e77e8686186cb 100644 (file)
@@ -22,7 +22,7 @@ non-blocking requests properly). If you call self.flush() or other
 asynchronous methods in your request handlers running in a WSGIApplication,
 we throw an exception.
 
-Example usage:
+Example usage::
 
     import tornado.web
     import tornado.wsgi
@@ -165,10 +165,10 @@ class HTTPRequest(object):
 
 
 class WSGIContainer(object):
-    """Makes a WSGI-compatible function runnable on Tornado's HTTP server.
+    r"""Makes a WSGI-compatible function runnable on Tornado's HTTP server.
 
     Wrap a WSGI function in a WSGIContainer and pass it to HTTPServer to
-    run it. For example:
+    run it. For example::
 
         def simple_app(environ, start_response):
             status = "200 OK"
index f05fca6f9a89caf2078e58c5a80a87a92c867c13..b0f9ebf874ceb654b454511f892a4a79b08270b4 100644 (file)
@@ -2,3 +2,4 @@
 ======================
 
 .. automodule:: tornado.auth
+   :members:
index cedb3960ceb7f3027071861c96717c9966daccba..01ab31483c55a92b84914eb5043414f4bab849dc 100644 (file)
@@ -2,3 +2,4 @@
 ======================
 
 .. automodule:: tornado.autoreload
+   :members:
index 5ba77c0984d2767e35dc055a2547674dbe3f3f85..7a7dc8153c74f2d2740b1b6c75b6c2eae0fd70a6 100644 (file)
@@ -2,3 +2,4 @@
 ======================
 
 .. automodule:: tornado.database
+   :members:
index 7cfef4970a70c2274ad23a7350b484fddd99a00b..80417759455b0690b0634f2c5f73a23d2720909c 100644 (file)
@@ -2,3 +2,4 @@
 ======================
 
 .. automodule:: tornado.httputil
+   :members:
index a6ce5a572b7890fdf1743952a40991f97901d3e3..c6a3e10a634ee2914993aa472f43cab1ac920dd5 100644 (file)
@@ -2,3 +2,4 @@
 ======================
 
 .. automodule:: tornado.options
+   :members:
index 36a7de3ecdc96cb0fb5b20abc0c09293d65f65b0..95a14f8102b14dc8c6bb585199fe22a73937e147 100644 (file)
@@ -2,3 +2,4 @@
 =========================
 
 .. automodule:: tornado.stack_context
+   :members:
index a01d143117d0be284dd6e1d67a9a49588b88dc52..65caf01616a8811998dc744c34ceca2fd128c9f3 100644 (file)
@@ -2,3 +2,4 @@
 ======================
 
 .. automodule:: tornado.testing
+   :members:
index f09078d6550b2c03c85ac5327902232ef564a577..6c064feef63ae46a1d42d39713daabae7314f5b7 100644 (file)
@@ -2,3 +2,4 @@
 ======================
 
 .. automodule:: tornado.websocket
+   :members:
index b893340acdc97ff27ea2ba0ae09688e86738b645..37876b8788e8942b48265357bf92a716faf996d1 100644 (file)
@@ -2,3 +2,4 @@
 ======================
 
 .. automodule:: tornado.wsgi
+   :members: