.PHONY: all
all: sphinx
+# No -W for doctests because that disallows tests with empty output.
+SPHINX_DOCTEST_OPTS=-n -d build/doctress .
SPHINXOPTS=-n -W -d build/doctrees .
.PHONY: sphinx
.PHONY: doctest
doctest:
- sphinx-build -b doctest $(SPHINXOPTS) build/doctest
+ sphinx-build -b doctest $(SPHINX_DOCTEST_OPTS) build/doctest
clean:
rm -rf build
``tornado.auth`` --- Third-party login with OpenID and OAuth
============================================================
+.. testsetup::
+
+ import tornado.auth, tornado.gen, tornado.web
+
.. automodule:: tornado.auth
Common protocols
``tornado.concurrent`` --- Work with threads and futures
========================================================
+.. testsetup::
+
+ from tornado.concurrent import *
+ from tornado import gen
+
.. automodule:: tornado.concurrent
:members:
:exclude-members: Future, TracebackFuture
``tornado.gen`` --- Simplify asynchronous code
==============================================
+.. testsetup::
+
+ from tornado.web import *
+ from tornado import gen
+
.. automodule:: tornado.gen
Decorators
Examples
~~~~~~~~
-Here is a sample synchronous function::
+Here is a sample synchronous function:
+
+.. testcode::
from tornado.httpclient import HTTPClient
response = http_client.fetch(url)
return response.body
+.. testoutput::
+ :hide:
+
And here is the same function rewritten to be asynchronous with a
-callback argument::
+callback argument:
+
+.. testcode::
from tornado.httpclient import AsyncHTTPClient
callback(response.body)
http_client.fetch(url, callback=handle_response)
-And again with a `.Future` instead of a callback::
+.. testoutput::
+ :hide:
+
+And again with a `.Future` instead of a callback:
+
+.. testcode::
from tornado.concurrent import Future
lambda f: my_future.set_result(f.result()))
return my_future
+.. testoutput::
+ :hide:
+
The raw `.Future` version is more complex, but ``Futures`` are
nonetheless recommended practice in Tornado because they have two
major advantages. Error handling is more consistent since the
``Futures`` lend themselves well to use with coroutines. Coroutines
will be discussed in depth in the next section of this guide. Here is
the coroutine version of our sample function, which is very similar to
-the original synchronous version::
+the original synchronous version:
+
+.. testcode::
from tornado import gen
response = yield http_client.fetch(url)
raise gen.Return(response.body)
+.. testoutput::
+ :hide:
+
The statement ``raise gen.Return(response.body)`` is an artifact of
Python 2 (and 3.2), in which generators aren't allowed to return
values. To overcome this, Tornado coroutines raise a special kind of
Coroutines
==========
+.. testsetup::
+
+ from tornado import gen
+
**Coroutines** are the recommended way to write asynchronous code in
Tornado. Coroutines use the Python ``yield`` keyword to suspend and
resume execution instead of a chain of callbacks (cooperative
To interact with asynchronous code that uses callbacks instead of
`.Future`, wrap the call in a `.Task`. This will add the callback
-argument for you and return a `.Future` which you can yield::
+argument for you and return a `.Future` which you can yield:
+
+.. testcode::
@gen.coroutine
def call_task():
# some_function(other_args, callback=callback)
yield gen.Task(some_function, other_args)
+.. testoutput::
+ :hide:
+
Calling blocking functions
^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^
The coroutine decorator recognizes lists and dicts whose values are
-``Futures``, and waits for all of those ``Futures`` in parallel::
+``Futures``, and waits for all of those ``Futures`` in parallel:
+
+.. testcode::
@gen.coroutine
def parallel_fetch(url1, url2):
for url in urls}
# responses is a dict {url: HTTPResponse}
+.. testoutput::
+ :hide:
+
Interleaving
^^^^^^^^^^^^
Sometimes it is useful to save a `.Future` instead of yielding it
-immediately, so you can start another operation before waiting::
+immediately, so you can start another operation before waiting:
+
+.. testcode::
@gen.coroutine
def get(self):
fetch_future = self.fetch_next_chunk()
yield self.flush()
+.. testoutput::
+ :hide:
+
Looping
^^^^^^^
import motor
db = motor.MotorClient().test
-
+
@gen.coroutine
def loop_example(collection):
cursor = db.collection.find()
Since Tornado supplies its own HTTPServer, running and deploying it is
a little different from other Python web frameworks. Instead of
configuring a WSGI container to find your application, you write a
-``main()`` function that starts the server::
+``main()`` function that starts the server:
+
+.. testcode::
def main():
app = make_app()
if __name__ == '__main__':
main()
+.. testoutput::
+ :hide:
+
Configure your operating system or process manager to run this program to
start the server. Please note that it may be necessary to increase the number
of open files per process (to avoid "Too many open files"-Error).
Tornado includes a built-in multi-process mode to start several
processes at once. This requires a slight alteration to the standard
-main function::
+main function:
+
+.. testcode::
def main():
app = make_app()
server.start(0) # forks one process per cpu
IOLoop.current().start()
+.. testoutput::
+ :hide:
+
This is the easiest way to start multiple processes and have them all
share the same port, although it has some limitations. First, each
child process will have its own IOLoop, so it is important that
You can convert a Tornado `.Application` to a WSGI application
with `tornado.wsgi.WSGIAdapter`. In this example, configure
-your WSGI container to find the ``application`` object::
+your WSGI container to find the ``application`` object:
+
+.. testcode::
import tornado.web
import tornado.wsgi
])
application = tornado.wsgi.WSGIAdapter(tornado_app)
+.. testoutput::
+ :hide:
+
See the `appengine example application
<https://github.com/tornadoweb/tornado/tree/stable/demos/appengine>`_ for a
full-featured AppEngine app built on Tornado.
Authentication and security
===========================
+.. testsetup::
+
+ import tornado.web
+
Cookies and secure cookies
~~~~~~~~~~~~~~~~~~~~~~~~~~
You can set cookies in the user's browser with the ``set_cookie``
-method::
+method:
+
+.. testcode::
class MainHandler(tornado.web.RequestHandler):
def get(self):
else:
self.write("Your cookie was set!")
+.. testoutput::
+ :hide:
+
Cookies are not secure and can easily be modified by clients. If you
need to set cookies to, e.g., identify the currently logged in user,
you need to sign your cookies to prevent forgery. Tornado supports
`~.RequestHandler.get_secure_cookie` methods. To use these methods,
you need to specify a secret key named ``cookie_secret`` when you
create your application. You can pass in application settings as
-keyword arguments to your application::
+keyword arguments to your application:
+
+.. testcode::
application = tornado.web.Application([
(r"/", MainHandler),
], cookie_secret="__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__")
+.. testoutput::
+ :hide:
+
Signed cookies contain the encoded value of the cookie in addition to a
timestamp and an `HMAC <http://en.wikipedia.org/wiki/HMAC>`_ signature.
If the cookie is old or if the signature doesn't match,
``get_secure_cookie`` will return ``None`` just as if the cookie isn't
-set. The secure version of the example above::
+set. The secure version of the example above:
+
+.. testcode::
class MainHandler(tornado.web.RequestHandler):
def get(self):
else:
self.write("Your cookie was set!")
+.. testoutput::
+ :hide:
+
Tornado's secure cookies guarantee integrity but not confidentiality.
That is, the cookie cannot be modified but its contents can be seen by the
user. The ``cookie_secret`` is a symmetric key and must be kept secret --
override the ``get_current_user()`` method in your request handlers to
determine the current user based on, e.g., the value of a cookie. Here
is an example that lets users log into the application simply by
-specifying a nickname, which is then saved in a cookie::
+specifying a nickname, which is then saved in a cookie:
+
+.. testcode::
class BaseHandler(tornado.web.RequestHandler):
def get_current_user(self):
(r"/login", LoginHandler),
], cookie_secret="__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__")
+.. testoutput::
+ :hide:
+
You can require that the user be logged in using the `Python
decorator <http://www.python.org/dev/peps/pep-0318/>`_
`tornado.web.authenticated`. If a request goes to a method with this
decorator, and the user is not logged in, they will be redirected to
``login_url`` (another application setting). The example above could be
-rewritten::
+rewritten:
+
+.. testcode::
class MainHandler(BaseHandler):
@tornado.web.authenticated
(r"/login", LoginHandler),
], **settings)
+.. testoutput::
+ :hide:
+
If you decorate ``post()`` methods with the ``authenticated``
decorator, and the user is not logged in, the server will send a
``403`` response. The ``@authenticated`` decorator is simply
behalf.
Here is an example handler that uses Google for authentication, saving
-the Google credentials in a cookie for later access::
+the Google credentials in a cookie for later access:
+
+.. testcode::
class GoogleHandler(tornado.web.RequestHandler, tornado.auth.GoogleMixin):
@tornado.web.asynchronous
return
# Save the user with, e.g., set_secure_cookie()
+.. testoutput::
+ :hide:
+
See the `tornado.auth` module documentation for more details.
.. _xsrf:
forged.
Tornado comes with built-in XSRF protection. To include it in your site,
-include the application setting ``xsrf_cookies``::
+include the application setting ``xsrf_cookies``:
+
+.. testcode::
settings = {
"cookie_secret": "__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__",
(r"/login", LoginHandler),
], **settings)
+.. testoutput::
+ :hide:
+
If ``xsrf_cookies`` is set, the Tornado web application will set the
``_xsrf`` cookie for all users and reject all ``POST``, ``PUT``, and
``DELETE`` requests that do not contain a correct ``_xsrf`` value. If
.. currentmodule:: tornado.web
+.. testsetup::
+
+ import tornado.web
+
Structure of a Tornado web application
======================================
routes incoming requests to handlers, and a ``main()`` function
to start the server.
-A minimal "hello world" example looks something like this::
+A minimal "hello world" example looks something like this:
+
+.. testcode::
from tornado.ioloop import IOLoop
from tornado.web import RequestHandler, Application, url
app.listen(8888)
IOLoop.current().start()
+.. testoutput::
+ :hide:
+
The ``Application`` object
~~~~~~~~~~~~~~~~~~~~~~~~~~
and is made available in methods like `~.RequestHandler.get_query_argument`
and `~.RequestHandler.get_body_argument`.
-::
+.. testcode::
class MyFormHandler(RequestHandler):
def get(self):
self.set_header("Content-Type", "text/plain")
self.write("You wrote " + self.get_body_argument("message"))
+.. testoutput::
+ :hide:
+
Since the HTML form encoding is ambiguous as to whether an argument is
a single value or a list with one element, `.RequestHandler` has
distinct methods to allow the application to indicate whether or not
simply hang.
Here is an example that makes a call to the FriendFeed API using
-Tornado's built-in `.AsyncHTTPClient`::
+Tornado's built-in `.AsyncHTTPClient`:
+
+.. testcode::
class MainHandler(tornado.web.RequestHandler):
@tornado.web.asynchronous
"from the FriendFeed API")
self.finish()
+.. testoutput::
+ :hide:
+
When ``get()`` returns, the request has not finished. When the HTTP
client eventually calls ``on_response()``, the request is still open,
and the response is finally flushed to the client with the call to
``self.finish()``.
-For comparison, here is the same example using a coroutine::
+For comparison, here is the same example using a coroutine:
+
+.. testcode::
class MainHandler(tornado.web.RequestHandler):
@tornado.gen.coroutine
self.write("Fetched " + str(len(json["entries"])) + " entries "
"from the FriendFeed API")
+.. testoutput::
+ :hide:
+
For a more advanced asynchronous example, take a look at the `chat
example application
<https://github.com/tornadoweb/tornado/tree/stable/demos/chat>`_, which
Templates and UI
================
+.. testsetup::
+
+ import tornado.web
+
Tornado includes a simple, fast, and flexible templating language.
This section describes that language as well as related issues
such as internationalization.
If you saved this template as "template.html" and put it in the same
directory as your Python file, you could render this template with:
-::
+.. testcode::
class MainHandler(tornado.web.RequestHandler):
def get(self):
items = ["Item 1", "Item 2", "Item 3"]
self.render("template.html", title="My title", items=items)
+.. testoutput::
+ :hide:
+
Tornado templates support *control statements* and *expressions*.
Control statements are surrounded by ``{%`` and ``%}``, e.g.,
``{% if len(items) > 2 %}``. Expressions are surrounded by ``{{`` and
header sent by the user's browser. We choose ``en_US`` if we can't find
an appropriate ``Accept-Language`` value. If you let user's set their
locale as a preference, you can override this default locale selection
-by overriding `.RequestHandler.get_user_locale`::
+by overriding `.RequestHandler.get_user_locale`:
+
+.. testcode::
class BaseHandler(tornado.web.RequestHandler):
def get_current_user(self):
return None
return self.current_user.prefs["locale"]
+.. testoutput::
+ :hide:
+
If ``get_user_locale`` returns ``None``, we fall back on the
``Accept-Language`` header.
``tornado.web`` --- ``RequestHandler`` and ``Application`` classes
==================================================================
+.. testsetup::
+
+ from tornado.web import *
+
.. automodule:: tornado.web
Request handlers
``tornado.websocket`` --- Bidirectional communication to the browser
====================================================================
+.. testsetup::
+
+ import tornado.websocket
+
.. automodule:: tornado.websocket
.. autoclass:: WebSocketHandler
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:
+
+.. testcode::
class GoogleOAuth2LoginHandler(tornado.web.RequestHandler,
tornado.auth.GoogleOAuth2Mixin):
response_type='code',
extra_params={'approval_prompt': 'auto'})
+.. testoutput::
+ :hide:
+
+
.. versionchanged:: 4.0
All of the callback interfaces in this module are now guaranteed
to run their callback with an argument of ``None`` on error.
URL 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:
+
+ .. testcode::
class TwitterLoginHandler(tornado.web.RequestHandler,
tornado.auth.TwitterMixin):
else:
yield self.authorize_redirect()
+ .. testoutput::
+ :hide:
+
The user object returned by `~OAuthMixin.get_authenticated_user`
includes the attributes ``username``, ``name``, ``access_token``,
and all of the custom Twitter user attributes described at
`~OAuthMixin.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::
+ usage:
+
+ .. testcode::
class MainHandler(tornado.web.RequestHandler,
tornado.auth.TwitterMixin):
return
self.finish("Posted a message!")
+ .. testoutput::
+ :hide:
+
"""
if path.startswith('http:') or path.startswith('https:'):
# Raw urls are useful for e.g. search which doesn't follow the
for the URL 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 FriendFeed and get access to their feed::
+ to authenticate the user with FriendFeed and get access to their feed:
+
+ .. testcode::
class FriendFeedLoginHandler(tornado.web.RequestHandler,
tornado.auth.FriendFeedMixin):
else:
yield self.authorize_redirect()
+ .. testoutput::
+ :hide:
+
+
The user object returned by `~OAuthMixin.get_authenticated_user()` includes the
attributes ``username``, ``name``, and ``description`` in addition to
``access_token``. You should save the access token with the user;
can be used to make authenticated requests via this
method.
- Example usage::
+ Example usage:
+
+ .. testcode::
class MainHandler(tornado.web.RequestHandler,
tornado.auth.FriendFeedMixin):
return
self.finish("Posted a message!")
+ .. testoutput::
+ :hide:
+
"""
# Add the OAuth resource request signature if we have credentials
url = "http://friendfeed-api.com/v2" + path
the values for the user, including ``email``, ``name``, and
``locale``.
- Example usage::
+ Example usage:
+
+ .. testcode::
class GoogleLoginHandler(tornado.web.RequestHandler,
tornado.auth.GoogleMixin):
# Save the user with e.g. set_secure_cookie()
else:
yield self.authenticate_redirect()
+
+ .. testoutput::
+ :hide:
+
"""
_OPENID_ENDPOINT = "https://www.google.com/accounts/o8/ud"
_OAUTH_ACCESS_TOKEN_URL = "https://www.google.com/accounts/OAuthGetAccessToken"
def get_authenticated_user(self, redirect_uri, code, callback):
"""Handles the login for the Google user, returning a user object.
- Example usage::
+ Example usage:
+
+ .. testcode::
class GoogleOAuth2LoginHandler(tornado.web.RequestHandler,
tornado.auth.GoogleOAuth2Mixin):
scope=['profile', 'email'],
response_type='code',
extra_params={'approval_prompt': 'auto'})
+
+ .. testoutput::
+ :hide:
+
"""
http = self.get_auth_http_client()
body = urllib_parse.urlencode({
``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:
+
+ .. testcode::
class FacebookHandler(tornado.web.RequestHandler,
tornado.auth.FacebookMixin):
raise tornado.web.HTTPError(500, "Facebook auth failed")
# Save the user using, e.g., set_secure_cookie()
+ .. testoutput::
+ :hide:
+
The user object returned by `get_authenticated_user` includes the
attributes ``facebook_uid`` and ``name`` in addition to session attributes
like ``session_key``. You should save the session key with the user; it is
The available Facebook methods are documented here:
http://wiki.developers.facebook.com/index.php/API
- Here is an example for the stream.get() method::
+ Here is an example for the stream.get() method:
+
+ .. testcode::
class MainHandler(tornado.web.RequestHandler,
tornado.auth.FacebookMixin):
return
self.render("stream.html", stream=stream)
+ .. testoutput::
+ :hide:
+
"""
self.require_setting("facebook_api_key", "Facebook Connect")
self.require_setting("facebook_secret", "Facebook Connect")
code, callback, extra_fields=None):
"""Handles the login for the Facebook user, returning a user object.
- Example usage::
+ Example usage:
+
+ .. testcode::
- class FacebookGraphLoginHandler(LoginHandler, tornado.auth.FacebookGraphMixin):
+ class FacebookGraphLoginHandler(tornado.web.RequestHandler,
+ tornado.auth.FacebookGraphMixin):
@tornado.gen.coroutine
def get(self):
if self.get_argument("code", False):
redirect_uri='/auth/facebookgraph/',
client_id=self.settings["facebook_api_key"],
extra_params={"scope": "read_stream,offline_access"})
+
+ .. testoutput::
+ :hide:
+
"""
http = self.get_auth_http_client()
args = {
process includes an ``access_token`` attribute that can be
used to make authenticated requests via this method.
- Example usage::
+ Example usage:
+
+ ..testcode::
class MainHandler(tornado.web.RequestHandler,
tornado.auth.FacebookGraphMixin):
return
self.finish("Posted a message!")
+ .. testoutput::
+ :hide:
+
The given path is relative to ``self._FACEBOOK_BASE_URL``,
by default "https://graph.facebook.com".
wait for the function to complete (perhaps by yielding it in a
`.gen.engine` function, or passing it to `.IOLoop.add_future`).
- Usage::
+ Usage:
+
+ .. testcode::
@return_future
def future_func(arg1, arg2, callback):
yield future_func(arg1, arg2)
callback()
+ ..
+
Note that ``@return_future`` and ``@gen.engine`` can be applied to the
same function, provided ``@return_future`` appears first. However,
consider using ``@gen.coroutine`` instead of this combination.
is technically asynchronous, but it is written as a single generator
instead of a collection of separate functions.
-For example, the following asynchronous handler::
+For example, the following asynchronous handler:
+
+.. testcode::
class AsyncHandler(RequestHandler):
@asynchronous
do_something_with_response(response)
self.render("template.html")
-could be written with ``gen`` as::
+.. testoutput::
+ :hide:
+
+could be written with ``gen`` as:
+
+.. testcode::
class GenAsyncHandler(RequestHandler):
@gen.coroutine
do_something_with_response(response)
self.render("template.html")
+.. testoutput::
+ :hide:
+
Most asynchronous functions in Tornado return a `.Future`;
yielding this object returns its `~.Future.result`.
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::
+be returned when they are all finished:
+
+.. testcode::
@gen.coroutine
def get(self):
response3 = response_dict['response3']
response4 = response_dict['response4']
+.. testoutput::
+ :hide:
+
If the `~functools.singledispatch` library is available (standard in
Python 3.4, available via the `singledispatch
<https://pypi.python.org/pypi/singledispatch>`_ package on older
If you need to get the result of each future as soon as possible,
or if you need the result of some futures even if others produce
- errors, you can use ``WaitIterator``:
-
- ::
+ errors, you can use ``WaitIterator``::
wait_iterator = gen.WaitIterator(future1, future2)
while not wait_iterator.done():
try:
result = yield wait_iterator.next()
except Exception as e:
- print "Error {} from {}".format(e, wait_iterator.current_future)
+ print("Error {} from {}".format(e, wait_iterator.current_future))
else:
- print "Result {} recieved from {} at {}".format(
+ print("Result {} recieved from {} at {}".format(
result, wait_iterator.current_future,
- wait_iterator.current_index)
+ wait_iterator.current_index))
Because results are returned as soon as they are available the
output from the iterator *will not be in the same order as the
simultaneous connections, you should use a system that supports
either ``epoll`` or ``kqueue``.
- Example usage for a simple TCP server::
+ Example usage for a simple TCP server:
+
+ .. testcode::
import errno
import functools
- import ioloop
+ import tornado.ioloop
import socket
def connection_ready(sock, fd, events):
while True:
try:
connection, address = sock.accept()
- except socket.error, e:
+ except socket.error as e:
if e.args[0] not in (errno.EWOULDBLOCK, errno.EAGAIN):
raise
return
connection.setblocking(0)
handle_connection(connection, address)
- sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
- sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
- sock.setblocking(0)
- sock.bind(("", port))
- sock.listen(128)
+ if __name__ == '__main__':
+ sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
+ sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ sock.setblocking(0)
+ sock.bind(("", port))
+ sock.listen(128)
+
+ io_loop = tornado.ioloop.IOLoop.instance()
+ callback = functools.partial(connection_ready, sock)
+ io_loop.add_handler(sock.fileno(), callback, io_loop.READ)
+ io_loop.start()
- io_loop = ioloop.IOLoop.instance()
- callback = functools.partial(connection_ready, sock)
- io_loop.add_handler(sock.fileno(), callback, io_loop.READ)
- io_loop.start()
+ .. testoutput::
+ :hide:
"""
# Constants from the epoll module
connected before passing it to the `IOStream` or connected with
`IOStream.connect`.
- A very simple (and broken) HTTP client using this class::
+ A very simple (and broken) HTTP client using this class:
+
+ .. testcode::
import tornado.ioloop
import tornado.iostream
stream.read_bytes(int(headers[b"Content-Length"]), on_body)
def on_body(data):
- print data
+ print(data)
stream.close()
tornado.ioloop.IOLoop.instance().stop()
- s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
- stream = tornado.iostream.IOStream(s)
- stream.connect(("friendfeed.com", 80), send_request)
- tornado.ioloop.IOLoop.instance().start()
+ if __name__ == '__main__':
+ s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
+ stream = tornado.iostream.IOStream(s)
+ stream.connect(("friendfeed.com", 80), send_request)
+ tornado.ioloop.IOLoop.instance().start()
+
+ .. testoutput::
+ :hide:
+
"""
def __init__(self, socket, *args, **kwargs):
self.socket = socket
making it ideal for `long polling
<http://en.wikipedia.org/wiki/Push_technology#Long_polling>`_.
-Here is a simple "Hello, world" example app::
+Here is a simple "Hello, world" example app:
+
+.. testcode::
import tornado.ioloop
import tornado.web
application.listen(8888)
tornado.ioloop.IOLoop.instance().start()
+.. testoutput::
+ :hide:
+
+
See the :doc:`guide` for additional information.
Thread-safety notes
method returns. It is up to the request handler to call
`self.finish() <RequestHandler.finish>` to finish the HTTP
request. Without this decorator, the request is automatically
- finished when the ``get()`` or ``post()`` method returns. Example::
+ finished when the ``get()`` or ``post()`` method returns. Example:
- class MyRequestHandler(web.RequestHandler):
- @web.asynchronous
+ .. testcode::
+
+ class MyRequestHandler(RequestHandler):
+ @asynchronous
def get(self):
http = httpclient.AsyncHTTPClient()
http.fetch("http://friendfeed.com/", self._on_download)
self.write("Downloaded!")
self.finish()
+ .. testoutput::
+ :hide:
+
.. versionadded:: 3.1
The ability to use ``@gen.coroutine`` without ``@asynchronous``.
"""
http://tools.ietf.org/html/rfc6455.
Here is an example WebSocket handler that echos back all received messages
- back to the client::
+ back to the client:
- class EchoWebSocket(websocket.WebSocketHandler):
+ .. testcode::
+
+ class EchoWebSocket(tornado.websocket.WebSocketHandler):
def open(self):
- print "WebSocket opened"
+ print("WebSocket opened")
def on_message(self, message):
self.write_message(u"You said: " + message)
def on_close(self):
- print "WebSocket closed"
+ print("WebSocket closed")
+
+ .. testoutput::
+ :hide:
WebSockets are not standard HTTP connections. The "handshake" is
HTTP, but after the handshake, the protocol is
[testenv:py2-sphinx-doctest]
changedir = docs
setenv = TORNADO_EXTENSION=0
+# No -W for doctests because that disallows tests with empty output.
commands =
- sphinx-build -q -E -n -W -b doctest . {envtmpdir}/doctest
+ sphinx-build -q -E -n -b doctest . {envtmpdir}/doctest
[testenv:py3-sphinx-doctest]
changedir = docs
setenv = TORNADO_EXTENSION=0
commands =
- sphinx-build -q -E -n -W -b doctest . {envtmpdir}/doctest
+ sphinx-build -q -E -n -b doctest . {envtmpdir}/doctest
projects / thirdparty / tornado.git / commitdiff
