Permalink
Browse files

Expand docs for @asynchronous decorator and other cleanups.

Closes #742.
  • Loading branch information...
1 parent efeb350 commit e4bba5ce216daca80bc9bb151a18f4220fe26c78 @bdarnell bdarnell committed Apr 18, 2013
Showing with 20 additions and 10 deletions.
  1. +9 −6 docs/web.rst
  2. +2 −2 tornado/gen.py
  3. +1 −1 tornado/testing.py
  4. +8 −1 tornado/web.py
View
@@ -14,8 +14,10 @@
.. automethod:: RequestHandler.prepare
.. automethod:: RequestHandler.on_finish
- Implement any of the following methods to handle the corresponding
- HTTP method.
+ .. _verbs:
+
+ Implement any of the following methods (collectively known as the
+ HTTP verb methods) to handle the corresponding HTTP method.
.. automethod:: RequestHandler.get
.. automethod:: RequestHandler.post
@@ -38,10 +40,11 @@
.. attribute:: RequestHandler.path_args
.. attribute:: RequestHandler.path_kwargs
- The ``path_args`` and ``path_kwargs`` attributes contain the positional
- and keyword arguments that are passed to the `get`/`post`/etc methods.
- These attributes are set before those methods are called, so the values
- are available during `prepare`.
+ The ``path_args`` and ``path_kwargs`` attributes contain the
+ positional and keyword arguments that are passed to the
+ :ref:`HTTP verb methods <verbs>`. These attributes are set
+ before those methods are called, so the values are available
+ during `prepare`.
Output
^^^^^^
View
@@ -121,7 +121,7 @@ def engine(func):
In most cases, functions decorated with `engine` should take
a ``callback`` argument and invoke it with their result when
they are finished. One notable exception is the
- `~tornado.web.RequestHandler` ``get``/``post``/etc methods,
+ `~tornado.web.RequestHandler` :ref:`HTTP verb methods <verbs>`,
which use ``self.finish()`` in place of a callback argument.
"""
@functools.wraps(func)
@@ -166,7 +166,7 @@ def coroutine(func):
Any generator that yields objects from this module must be wrapped
in either this decorator or `engine`. These decorators only work
on functions that are already asynchronous. For
- `~tornado.web.RequestHandler` ``get``/``post``/etc methods, this
+ `~tornado.web.RequestHandler` :ref:`HTTP verb methods <verbs>` methods, this
means that both the `tornado.web.asynchronous` and
`tornado.gen.coroutine` decorators must be used (for proper
exception handling, ``asynchronous`` should come before
View
@@ -386,7 +386,7 @@ def test_something(self):
By default, ``@gen_test`` times out after 5 seconds. The timeout may be
overridden globally with the ASYNC_TEST_TIMEOUT environment variable,
- or for each test with the ``timeout`` keyword argument:
+ or for each test with the ``timeout`` keyword argument::
class MyTest(AsyncHTTPTestCase):
@gen_test(timeout=10)
View
@@ -194,7 +194,7 @@ def options(self, *args, **kwargs):
raise HTTPError(405)
def prepare(self):
- """Called at the beginning of a request before `get`/`post`/etc.
+ """Called at the beginning of a request before `get`/`post`/etc.
Override this method to perform common initialization regardless
of the request method.
@@ -1152,6 +1152,13 @@ def _clear_headers_for_304(self):
def asynchronous(method):
"""Wrap request handler methods with this if they are asynchronous.
+ This decorator should only be applied to the :ref:`HTTP verb
+ methods <verbs>`; its behavior is undefined for any other method.
+ This decorator does not *make* a method asynchronous; it tells
+ the framework that the method *is* asynchronous. For this decorator
+ to be useful the method must (at least sometimes) do something
+ asynchronous.
+
If this decorator is given, the response is not finished when the
method returns. It is up to the request handler to call
`self.finish() <RequestHandler.finish>` to finish the HTTP

0 comments on commit e4bba5c

Please sign in to comment.