From: Ben Darnell Date: Sun, 13 Jul 2014 22:19:29 +0000 (-0400) Subject: Update gen docs: deemphasize Task, Callback, and Wait. X-Git-Tag: v4.0.0~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3bcbb55d6c12775901429dfebdf4e272bb5b139b;p=thirdparty%2Ftornado.git Update gen docs: deemphasize Task, Callback, and Wait. --- diff --git a/docs/gen.rst b/docs/gen.rst index 5380dae59..c010ed418 100644 --- a/docs/gen.rst +++ b/docs/gen.rst @@ -10,27 +10,10 @@ .. autofunction:: engine - Yield points - ------------ + Utility functions + ----------------- - Instances of the following classes may be used in yield expressions - in the generator. `Futures <.Future>` may be yielded as well; - their result method will be called automatically when they are - ready. Additionally, lists of any combination of these objects may - be yielded; the result is a list of the results of each yield point - in the same order. Yielding dicts with these objects in values will - return dict with results at the same keys. - - .. autofunction:: Task - - .. autoclass:: Callback - - .. autoclass:: Wait - - .. autoclass:: WaitAll - - .. autoclass:: YieldPoint - :members: + .. autoexception:: Return .. autofunction:: with_timeout .. autoexception:: TimeoutError @@ -40,16 +23,30 @@ .. autodata:: moment :annotation: - Other classes - ------------- - - .. autoexception:: Return + .. autofunction:: Task .. class:: Arguments - The result of a yield expression whose callback had more than one + The result of a `Task` or `Wait` whose callback had more than one argument (or keyword arguments). The `Arguments` object is a `collections.namedtuple` and can be used either as a tuple ``(args, kwargs)`` or an object with attributes ``args`` and ``kwargs``. + + Legacy interface + ---------------- + + Before support for `Futures <.Future>` was introduced in Tornado 3.0, + coroutines used subclasses of `YieldPoint` in their ``yield`` expressions. + These classes are still supported but should generally not be used + except for compatibility with older interfaces. + + .. autoclass:: YieldPoint + :members: + + .. autoclass:: Callback + + .. autoclass:: Wait + + .. autoclass:: WaitAll diff --git a/docs/guide/intro.rst b/docs/guide/intro.rst index b4a057a42..ba28c773b 100644 --- a/docs/guide/intro.rst +++ b/docs/guide/intro.rst @@ -9,7 +9,7 @@ can scale to tens of thousands of open connections, making it ideal for `WebSockets `_, and other applications that require a long-lived connection to each user. -Tornado can be roughly divided into three major components: +Tornado can be roughly divided into four major components: * A web framework (including `.RequestHandler` which is subclassed to create web applications, and various supporting classes). @@ -18,6 +18,9 @@ Tornado can be roughly divided into three major components: * An asynchronous networking library (`.IOLoop` and `.IOStream`), which serve as the building blocks for the HTTP components and can also be used to implement other protocols. +* A coroutine library (`tornado.gen`) which allows asynchronous + code to be written in a more straightforward way than chaining + callbacks. The Tornado web framework and HTTP server together offer a full-stack alternative to `WSGI `_. diff --git a/tornado/gen.py b/tornado/gen.py index 9548b5f52..06f2715d6 100644 --- a/tornado/gen.py +++ b/tornado/gen.py @@ -29,16 +29,7 @@ could be written with ``gen`` as:: Most asynchronous functions in Tornado return a `.Future`; yielding this object returns its `~.Future.result`. -For functions that do not return ``Futures``, `Task` works with any -function that takes a ``callback`` keyword argument (most Tornado functions -can be used in either style, although the ``Future`` style is preferred -since it is both shorter and provides better exception handling):: - - @gen.coroutine - def get(self): - yield gen.Task(AsyncHTTPClient().fetch, "http://example.com") - -You can also yield a list or dict of ``Futures`` and/or ``Tasks``, which will be +You can also yield a list or dict of ``Futures``, which will be started at the same time and run in parallel; a list or dict of results will be returned when they are all finished:: @@ -54,30 +45,6 @@ be returned when they are all finished:: .. versionchanged:: 3.2 Dict support added. - -For more complicated interfaces, `Task` can be split into two parts: -`Callback` and `Wait`:: - - class GenAsyncHandler2(RequestHandler): - @gen.coroutine - def get(self): - http_client = AsyncHTTPClient() - http_client.fetch("http://example.com", - callback=(yield gen.Callback("key"))) - response = yield gen.Wait("key") - do_something_with_response(response) - self.render("template.html") - -The ``key`` argument to `Callback` and `Wait` allows for multiple -asynchronous operations to be started at different times and proceed -in parallel: yield several callbacks with different keys, then wait -for them once all the async operations have started. - -The result of a `Wait` or `Task` yield expression depends on how the callback -was run. If it was called with no arguments, the result is ``None``. If -it was called with one argument, the result is that argument. If it was -called with more than one argument or any keyword arguments, the result -is an `Arguments` object, which is a named tuple ``(args, kwargs)``. """ from __future__ import absolute_import, division, print_function, with_statement @@ -252,8 +219,8 @@ class Return(Exception): class YieldPoint(object): """Base class for objects that may be yielded from the generator. - Applications do not normally need to use this class, but it may be - subclassed to provide additional yielding behavior. + .. deprecated:: 4.0 + Use `Futures <.Future>` instead. """ def start(self, runner): """Called by the runner after the generator has yielded. @@ -289,6 +256,9 @@ class Callback(YieldPoint): The callback may be called with zero or one arguments; if an argument is given it will be returned by `Wait`. + + .. deprecated:: 4.0 + Use `Futures <.Future>` instead. """ def __init__(self, key): self.key = key @@ -305,7 +275,11 @@ class Callback(YieldPoint): class Wait(YieldPoint): - """Returns the argument passed to the result of a previous `Callback`.""" + """Returns the argument passed to the result of a previous `Callback`. + + .. deprecated:: 4.0 + Use `Futures <.Future>` instead. + """ def __init__(self, key): self.key = key @@ -326,6 +300,9 @@ class WaitAll(YieldPoint): a list of results in the same order. `WaitAll` is equivalent to yielding a list of `Wait` objects. + + .. deprecated:: 4.0 + Use `Futures <.Future>` instead. """ def __init__(self, keys): self.keys = keys @@ -341,20 +318,12 @@ class WaitAll(YieldPoint): def Task(func, *args, **kwargs): - """Runs a single asynchronous operation. + """Adapts a callback-based asynchronous function for use in coroutines. Takes a function (and optional additional arguments) and runs it with those arguments plus a ``callback`` keyword argument. The argument passed to the callback is returned as the result of the yield expression. - A `Task` is equivalent to a `Callback`/`Wait` pair (with a unique - key generated automatically):: - - result = yield gen.Task(func, args) - - func(args, callback=(yield gen.Callback(key))) - result = yield gen.Wait(key) - .. versionchanged:: 4.0 ``gen.Task`` is now a function that returns a `.Future`, instead of a subclass of `YieldPoint`. It still behaves the same way when