Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Finish automatic documentation

  • Loading branch information...
commit 96c2f2f21f6a9a406e6824471a36dafbd33201c3 1 parent f6b3651
@bdarnell bdarnell authored
View
315 tornado/auth.py
@@ -28,20 +28,20 @@
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 @@ def twitter_request(self, path, callback, access_token=None,
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 @@ def friendfeed_request(self, path, callback, access_token=None,
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 @@ def facebook_request(self, method, callback, **args):
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 @@ def get_authenticated_user(self, redirect_uri, client_id, client_secret,
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 @@ def facebook_request(self, path, callback, access_token=None,
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
View
2  tornado/database.py
@@ -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"):
View
8 tornado/options.py
@@ -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 @@ def connect():
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
View
10 tornado/stack_context.py
@@ -29,7 +29,8 @@
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 @@ def __init__(self, context_factory):
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
View
16 tornado/testing.py
@@ -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 @@ def run(self, result=None):
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
View
4 tornado/websocket.py
@@ -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 @@ def on_close(self):
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() {
View
6 tornado/wsgi.py
@@ -22,7 +22,7 @@
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 @@ def request_time(self):
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"
View
1  website/sphinx/auth.rst
@@ -2,3 +2,4 @@
======================
.. automodule:: tornado.auth
+ :members:
View
1  website/sphinx/autoreload.rst
@@ -2,3 +2,4 @@
======================
.. automodule:: tornado.autoreload
+ :members:
View
1  website/sphinx/database.rst
@@ -2,3 +2,4 @@
======================
.. automodule:: tornado.database
+ :members:
View
1  website/sphinx/httputil.rst
@@ -2,3 +2,4 @@
======================
.. automodule:: tornado.httputil
+ :members:
View
1  website/sphinx/options.rst
@@ -2,3 +2,4 @@
======================
.. automodule:: tornado.options
+ :members:
View
1  website/sphinx/stack_context.rst
@@ -2,3 +2,4 @@
=========================
.. automodule:: tornado.stack_context
+ :members:
View
1  website/sphinx/testing.rst
@@ -2,3 +2,4 @@
======================
.. automodule:: tornado.testing
+ :members:
View
1  website/sphinx/websocket.rst
@@ -2,3 +2,4 @@
======================
.. automodule:: tornado.websocket
+ :members:
View
1  website/sphinx/wsgi.rst
@@ -2,3 +2,4 @@
======================
.. automodule:: tornado.wsgi
+ :members:
Please sign in to comment.
Something went wrong with that request. Please try again.