tornado.gen — Simplify asynchronous code¶
tornado.gen is a generator-based interface to make it easier to
work in an asynchronous environment. Code using the
is technically asynchronous, but it is written as a single generator
instead of a collection of separate functions.
For example, the following asynchronous handler:
class AsyncHandler(RequestHandler): @asynchronous def get(self): http_client = AsyncHTTPClient() http_client.fetch("http://example.com", callback=self.on_fetch) def on_fetch(self, response): do_something_with_response(response) self.render("template.html")
could be written with
class GenAsyncHandler(RequestHandler): @gen.coroutine def get(self): http_client = AsyncHTTPClient() response = yield http_client.fetch("http://example.com") do_something_with_response(response) self.render("template.html")
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:
@gen.coroutine def get(self): http_client = AsyncHTTPClient() response1, response2 = yield [http_client.fetch(url1), http_client.fetch(url2)] response_dict = yield dict(response3=http_client.fetch(url3), response4=http_client.fetch(url4)) response3 = response_dict['response3'] response4 = response_dict['response4']
Changed in version 3.2: Dict support added.
Decorator for asynchronous generators.
Any generator that yields objects from this module must be wrapped in either this decorator or
Coroutines may “return” by raising the special exception
Return(value). In Python 3.3+, it is also possible for the function to simply use the
return valuestatement (prior to Python 3.3 generators were not allowed to also return values). In all versions of Python a coroutine that simply wishes to exit early may use the
returnstatement without a value.
Functions with this decorator return a
Future. Additionally, they may be called with a
callbackkeyword argument, which will be invoked with the future’s result when it resolves. If the coroutine fails, the callback will not be run and an exception will be raised into the surrounding
callbackargument is not visible inside the decorated function; it is handled by the decorator itself.
From the caller’s perspective,
@gen.coroutineis similar to the combination of
Callback-oriented decorator for asynchronous generators.
This is an older interface; for new code that does not need to be compatible with versions of Tornado older than 3.0 the
coroutinedecorator is recommended instead.
In most cases, functions decorated with
engineshould take a
callbackargument and invoke it with their result when they are finished. One notable exception is the
RequestHandlerHTTP verb methods, which use
self.finish()in place of a callback argument.
Special exception to return a value from a
If this exception is raised, its value argument is used as the result of the coroutine:
@gen.coroutine def fetch_json(url): response = yield AsyncHTTPClient().fetch(url) raise gen.Return(json_decode(response.body))
In Python 3.3, this exception is no longer necessary: the
returnstatement can be used directly to return a value (previously
returnwith a value could not be combined in the same function).
By analogy with the return statement, the value argument is optional, but it is never necessary to
raise gen.Return(). The
returnstatement can be used with no arguments instead.
with_timeout(timeout, future, io_loop=None)¶
Futurein a timeout.
TimeoutErrorif the input future does not complete before
timeout, which may be specified in any form allowed by
datetime.timedeltaor an absolute time relative to
Currently only supports Futures, not other
New in version 4.0.
Exception raised by
xis already a
Future, it is simply returned; otherwise it is wrapped in a new
Future. This is suitable for use as
result = yield gen.maybe_future(f())when you don’t know whether
A special object which may be yielded to allow the IOLoop to run for one iteration.
This is not needed in normal use but it can be helpful in long-running coroutines that are likely to yield Futures that are ready instantly.
New in version 4.0.
Task(func, *args, **kwargs)¶
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
callbackkeyword argument. The argument passed to the callback is returned as the result of the yield expression.
Before support for
Futures was introduced in Tornado 3.0,
coroutines used subclasses of
YieldPoint in their
These classes are still supported but should generally not be used
except for compatibility with older interfaces.
Base class for objects that may be yielded from the generator.
Called by the runner after the generator has yielded.
No other methods will be called on this object before
Called by the runner to determine whether to resume the generator.
Returns a boolean; may be called more than once.
Returns a callable object that will allow a matching
The key may be any value suitable for use as a dictionary key, and is used to match
Callbacksto their corresponding
Waits. The key must be unique among outstanding callbacks within a single run of the generator function, but may be reused across different runs of the same function (so constants generally work fine).
The callback may be called with zero or one arguments; if an argument is given it will be returned by