Permalink
Browse files

Finish this round of doc updates

  • Loading branch information...
1 parent 6d5ebab commit 300d23111d6c5fe755a18ba411bd01a7b19ac20f @bdarnell bdarnell committed Jun 19, 2011
View
@@ -697,9 +697,9 @@ def authorize_redirect(self, oauth_scope, callback_uri=None,
Some of the available resources are:
- Gmail Contacts - http://www.google.com/m8/feeds/
- Calendar - http://www.google.com/calendar/feeds/
- Finance - http://finance.google.com/finance/feeds/
+ * Gmail Contacts - http://www.google.com/m8/feeds/
+ * Calendar - http://www.google.com/calendar/feeds/
+ * Finance - http://finance.google.com/finance/feeds/
You can authorize multiple resources by separating the resource
URLs with a space.
@@ -740,6 +740,9 @@ def _oauth_get_user(self, access_token, callback):
class FacebookMixin(object):
"""Facebook Connect authentication.
+ New applications should consider using `FacebookGraphMixin` below instead
+ of this class.
+
To authenticate with Facebook, register your application with
Facebook at http://www.facebook.com/developers/apps.php. Then
copy your API Key and Application Secret to the application settings
@@ -799,10 +802,10 @@ def authorize_redirect(self, extended_permissions, callback_uri=None,
http://wiki.developers.facebook.com/index.php/Extended_permission.
The most common resource types include:
- publish_stream
- read_stream
- email
- sms
+ * publish_stream
+ * read_stream
+ * email
+ * sms
extended_permissions can be a single permission name or a list of
names. To get the session secret and session key, call
@@ -918,13 +921,14 @@ def _signature(self, args):
return hashlib.md5(body).hexdigest()
class FacebookGraphMixin(OAuth2Mixin):
+ """Facebook authentication using the new Graph API and OAuth2."""
_OAUTH_ACCESS_TOKEN_URL = "https://graph.facebook.com/oauth/access_token?"
_OAUTH_AUTHORIZE_URL = "https://graph.facebook.com/oauth/authorize?"
_OAUTH_NO_CALLBACKS = False
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.
+ """Handles the login for the Facebook user, returning a user object.
Example usage::
View
@@ -16,8 +16,14 @@
"""A module to automatically restart the server when a module is modified.
+Most applications should not call this module directly. Instead, pass the
+keyword argument ``debug=True`` to the `tornado.web.Application` constructor.
+This will enable autoreload mode as well as checking for changes to templates
+and static resources.
+
This module depends on IOLoop, so it will not work in WSGI applications
-and Google AppEngine.
+and Google AppEngine. It also will not work correctly when HTTPServer's
+multi-process mode is used.
"""
import functools
View
@@ -310,7 +310,10 @@ class Error(Exception):
def enable_pretty_logging():
- """Turns on formatted logging output as configured."""
+ """Turns on formatted logging output as configured.
+
+ This is called automatically by `parse_command_line`.
+ """
root_logger = logging.getLogger()
if options.log_file_prefix:
channel = logging.handlers.RotatingFileHandler(
View
@@ -61,19 +61,19 @@ def __init__(self):
_state = _State()
class StackContext(object):
- def __init__(self, context_factory):
- '''Establishes the given context as a StackContext that will be transferred.
+ '''Establishes the given context as a StackContext that will be transferred.
- 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::
+ 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::
- with my_context():
+ 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):
- '''
+ with StackContext(my_context):
+ '''
+ def __init__(self, context_factory):
self.context_factory = context_factory
# Note that some of this code is duplicated in ExceptionStackContext
@@ -98,19 +98,19 @@ def __exit__(self, type, value, traceback):
_state.contexts = self.old_contexts
class ExceptionStackContext(object):
+ '''Specialization of StackContext for exception handling.
+
+ The supplied exception_handler function will be called in the
+ event of an uncaught exception in this context. The semantics are
+ similar to a try/finally clause, and intended use cases are to log
+ an error, close a socket, or similar cleanup actions. The
+ exc_info triple (type, value, traceback) will be passed to the
+ exception_handler function.
+
+ If the exception handler returns true, the exception will be
+ consumed and will not be propagated to other exception handlers.
+ '''
def __init__(self, exception_handler):
- '''Specialization of StackContext for exception handling.
-
- The supplied exception_handler function will be called in the
- event of an uncaught exception in this context. The semantics are
- similar to a try/finally clause, and intended use cases are to log
- an error, close a socket, or similar cleanup actions. The
- exc_info triple (type, value, traceback) will be passed to the
- exception_handler function.
-
- If the exception handler returns true, the exception will be
- consumed and will not be propagated to other exception handlers.
- '''
self.exception_handler = exception_handler
def __enter__(self):
View
@@ -3,13 +3,13 @@
This module contains three parts:
-* AsyncTestCase/AsyncHTTPTestCase: Subclasses of unittest.TestCase
+* `AsyncTestCase`/`AsyncHTTPTestCase`: Subclasses of unittest.TestCase
with additional support for testing asynchronous (IOLoop-based) code.
-* LogTrapTestCase: Subclass of unittest.TestCase that discards log output
+* `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
+* `main()`: A simple test runner (wrapper around unittest.main()) with support
for the tornado.autoreload module to rerun the tests when code changes.
These components may be used together or independently. In particular,
View
@@ -1,17 +1,16 @@
+"""Server-side implementation of the WebSocket protocol.
+
+`WebSockets <http://dev.w3.org/html5/websockets/>`_ allow for bidirectional
+communication between the browser and server.
+
+.. warning::
+
+ The WebSocket protocol is still in development. This module currently
+ implements the "draft76" version of the protocol, which is supported
+ only by Chrome and Safari. See this `browser compatibility table
+ <http://en.wikipedia.org/wiki/WebSockets#Browser_support>`_ on Wikipedia.
+"""
# Author: Jacob Kristhammar, 2010
-#
-# Updated version of websocket.py[1] that implements latest[2] stable version
-# of the websocket protocol.
-#
-# NB. It's no longer possible to manually select which callback that should
-# be invoked upon message reception. Instead you must override the
-# on_message(message) method to handle incoming messsages.
-# This also means that you don't have to explicitly invoke
-# receive_message, in fact you shouldn't.
-#
-# [1] http://github.com/facebook/tornado/blob/
-# 2c89b89536bbfa081745336bb5ab5465c448cb8a/tornado/websocket.py
-# [2] http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76
import functools
import hashlib
View
@@ -16,38 +16,17 @@
"""WSGI support for the Tornado web framework.
-We export WSGIApplication, which is very similar to web.Application, except
-no asynchronous methods are supported (since WSGI does not support
-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::
-
- import tornado.web
- import tornado.wsgi
- import wsgiref.simple_server
-
- class MainHandler(tornado.web.RequestHandler):
- def get(self):
- self.write("Hello, world")
-
- if __name__ == "__main__":
- application = tornado.wsgi.WSGIApplication([
- (r"/", MainHandler),
- ])
- server = wsgiref.simple_server.make_server('', 8888, application)
- server.serve_forever()
-
-See the 'appengine' demo for an example of using this module to run
-a Tornado app on Google AppEngine.
-
-Since no asynchronous methods are available for WSGI applications, the
-httpclient and auth modules are both not available for WSGI applications.
-
-We also export WSGIContainer, which lets you run other WSGI-compatible
-frameworks on the Tornado HTTP server and I/O loop. See WSGIContainer for
-details and documentation.
+WSGI is the Python standard for web servers, and allows for interoperability
+between Tornado and other Python web frameworks and servers. This module
+provides WSGI support in two ways:
+
+* `WSGIApplication` is a version of `tornado.web.Application` that can run
+ inside a WSGI server. This is useful for running a Tornado app on another
+ HTTP server, such as Google App Engine. See the `WSGIApplication` class
+ documentation for limitations that apply.
+* `WSGIContainer` lets you run other WSGI applications and frameworks on the
+ Tornado HTTP server. For example, with this class you can mix Django
+ and Tornado handlers in a single server.
"""
import cgi
@@ -70,10 +49,38 @@ def get(self):
from cStringIO import StringIO as BytesIO # python 2
class WSGIApplication(web.Application):
- """A WSGI-equivalent of web.Application.
+ """A WSGI equivalent of `tornado.web.Application`.
+ WSGIApplication is very similar to web.Application, except no
+ asynchronous methods are supported (since WSGI does not support
+ 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::
+
+ import tornado.web
+ import tornado.wsgi
+ import wsgiref.simple_server
+
+ class MainHandler(tornado.web.RequestHandler):
+ def get(self):
+ self.write("Hello, world")
+
+ if __name__ == "__main__":
+ application = tornado.wsgi.WSGIApplication([
+ (r"/", MainHandler),
+ ])
+ server = wsgiref.simple_server.make_server('', 8888, application)
+ server.serve_forever()
+
+ See the 'appengine' demo for an example of using this module to run
+ a Tornado app on Google AppEngine.
+
+ Since no asynchronous methods are available for WSGI applications, the
+ httpclient and auth modules are both not available for WSGI applications.
We support the same interface, but handlers running in a WSGIApplication
- do not support flush() or asynchronous methods.
+ do not support flush() or asynchronous methods.
"""
def __init__(self, handlers=None, default_host="", **settings):
web.Application.__init__(self, handlers, default_host, transforms=[],
@@ -94,7 +101,7 @@ def __call__(self, environ, start_response):
class HTTPRequest(object):
- """Mimics httpserver.HTTPRequest for WSGI applications."""
+ """Mimics `tornado.httpserver.HTTPRequest` for WSGI applications."""
def __init__(self, environ):
"""Parses the given WSGI environ to construct the request."""
self.method = environ["REQUEST_METHOD"]
@@ -182,8 +189,11 @@ def simple_app(environ, start_response):
tornado.ioloop.IOLoop.instance().start()
This class is intended to let other frameworks (Django, web.py, etc)
- run on the Tornado HTTP server and I/O loop. It has not yet been
- thoroughly tested in production.
+ run on the Tornado HTTP server and I/O loop.
+
+ The `tornado.web.FallbackHandler` class is often useful for mixing
+ Tornado and WSGI apps in the same server. See
+ https://github.com/bdarnell/django-tornado-demo for a complete example.
"""
def __init__(self, wsgi_application):
self.wsgi_application = wsgi_application
View
@@ -2,4 +2,42 @@
============================================================
.. automodule:: tornado.auth
- :members:
+
+ Common protocols
+ ----------------
+
+ .. autoclass:: OpenIdMixin
+ :members:
+
+ .. autoclass:: OAuthMixin
+ :members:
+
+ .. autoclass:: OAuth2Mixin
+ :members:
+
+ Twitter
+ -------
+
+ .. autoclass:: TwitterMixin
+ :members:
+
+ FriendFeed
+ ----------
+
+ .. autoclass:: FriendFeedMixin
+ :members:
+
+ Google
+ ------
+
+ .. autoclass:: GoogleMixin
+ :members:
+
+ Facebook
+ --------
+
+ .. autoclass:: FacebookMixin
+ :members:
+
+ .. autoclass:: FacebookGraphMixin
+ :members:
View
@@ -2,4 +2,23 @@
==================================================================
.. automodule:: tornado.testing
- :members:
+
+ Asynchronous test cases
+ -----------------------
+
+ .. autoclass:: AsyncTestCase
+ :members:
+
+ .. autoclass:: AsyncHTTPTestCase
+ :members:
+
+ Controlling log output
+ ----------------------
+
+ .. autoclass:: LogTrapTestCase
+ :members:
+
+ Test runner
+ -----------
+
+ .. autofunction:: main
View
@@ -2,4 +2,18 @@
==============================================================================
.. automodule:: tornado.wsgi
- :members:
+
+ WSGIApplication
+ ---------------
+
+ .. autoclass:: WSGIApplication
+ :members:
+
+ .. autoclass:: HTTPRequest
+ :members:
+
+ WSGIContainer
+ -------------
+
+ .. autoclass:: WSGIContainer
+ :members:

0 comments on commit 300d231

Please sign in to comment.