¶

Blocking¶

A function blocks when it waits for something to happen before returning. A function may block for many reasons: network I/O, disk I/O, mutexes, etc. In fact, every function blocks, at least a little bit, while it is running and using the CPU (for an extreme example that demonstrates why CPU blocking must be taken as seriously as other kinds of blocking, consider password hashing functions like bcrypt, which by design use hundreds of milliseconds of CPU time, far more than a typical network or disk access).

A function can be blocking in some respects and non-blocking in others. For example, tornado.httpclient in the default configuration blocks on DNS resolution but not on other network access (to mitigate this use ThreadedResolver or a tornado.curl_httpclient with a properly-configured build of libcurl). In the context of Tornado we generally talk about blocking in the context of network I/O, although all kinds of blocking are to be minimized.

Asynchronous¶

An asynchronous function returns before it is finished, and generally causes some work to happen in the background before triggering some future action in the application (as opposed to normal synchronous functions, which do everything they are going to do before returning). There are many styles of asynchronous interfaces:

• Callback argument
• Return a placeholder (Future, Promise, Deferred)
• Deliver to a queue
• Callback registry (e.g. POSIX signals)

Regardless of which type of interface is used, asynchronous functions by definition interact differently with their callers; there is no free way to make a synchronous function asynchronous in a way that is transparent to its callers (systems like gevent use lightweight threads to offer performance comparable to asynchronous systems, but they do not actually make things asynchronous).

Examples¶

Here is a sample synchronous function:

from tornado.httpclient import HTTPClient

def synchronous_fetch(url):
    http_client = HTTPClient()
    response = http_client.fetch(url)
    return response.body

And here is the same function rewritten to be asynchronous with a callback argument:

from tornado.httpclient import AsyncHTTPClient

def asynchronous_fetch(url, callback):
    http_client = AsyncHTTPClient()
    def handle_response(response):
        callback(response.body)
    http_client.fetch(url, callback=handle_response)

And again with a Future instead of a callback:

from tornado.concurrent import Future

def async_fetch_future(url):
    http_client = AsyncHTTPClient()
    my_future = Future()
    fetch_future = http_client.fetch(url)
    fetch_future.add_done_callback(
        lambda f: my_future.set_result(f.result()))
    return my_future

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 Future.result method can simply raise an exception (as opposed to the ad-hoc error handling common in callback-oriented interfaces), and 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:

from tornado import gen

@gen.coroutine
def fetch_coroutine(url):
    http_client = AsyncHTTPClient()
    response = yield http_client.fetch(url)
    raise gen.Return(response.body)

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 exception called a Return. The coroutine catches this exception and treats it like a returned value. In Python 3.3 and later, a return response.body achieves the same result.

How it works¶

A function containing yield is a generator. All generators are asynchronous; when called they return a generator object instead of running to completion. The @gen.coroutine decorator communicates with the generator via the yield expressions, and with the coroutine’s caller by returning a Future.

Here is a simplified version of the coroutine decorator’s inner loop:

# Simplified inner loop of tornado.gen.Runner
def run(self):
    # send(x) makes the current yield return x.
    # It returns when the next yield is reached
    future = self.gen.send(self.next)
    def callback(f):
        self.next = f.result()
        self.run()
    future.add_done_callback(callback)

The decorator receives a Future from the generator, waits (without blocking) for that Future to complete, then “unwraps” the Future and sends the result back into the generator as the result of the yield expression. Most asynchronous code never touches the Future class directly except to immediately pass the Future returned by an asynchronous function to a yield expression.

Coroutine patterns¶

@gen.coroutine
def call_task():
    # Note that there are no parens on some_function.
    # This will be translated by Task into
    #   some_function(other_args, callback=callback)
    yield gen.Task(some_function, other_args)

thread_pool = ThreadPoolExecutor(4)

@gen.coroutine
def call_blocking():
    yield thread_pool.submit(blocking_func, args)

@gen.coroutine
def parallel_fetch(url1, url2):
    resp1, resp2 = yield [http_client.fetch(url1),
                          http_client.fetch(url2)]

@gen.coroutine
def parallel_fetch_many(urls):
    responses = yield [http_client.fetch(url) for url in urls]
    # responses is a list of HTTPResponses in the same order

@gen.coroutine
def parallel_fetch_dict(urls):
    responses = yield {url: http_client.fetch(url)
                        for url in urls}
    # responses is a dict {url: HTTPResponse}

@gen.coroutine
def get(self):
    fetch_future = self.fetch_next_chunk()
    while True:
        chunk = yield fetch_future
        if chunk is None: break
        self.write(chunk)
        fetch_future = self.fetch_next_chunk()
        yield self.flush()

import motor
db = motor.MotorClient().test

@gen.coroutine
def loop_example(collection):
    cursor = db.collection.find()
    while (yield cursor.fetch_next):
        doc = cursor.next_object()

The Application object¶

The Application object is responsible for global configuration, including the routing table that maps requests to handlers.

The routing table is a list of URLSpec objects (or tuples), each of which contains (at least) a regular expression and a handler class. Order matters; the first matching rule is used. If the regular expression contains capturing groups, these groups are the path arguments and will be passed to the handler’s HTTP method. If a dictionary is passed as the third element of the URLSpec, it supplies the initialization arguments which will be passed to RequestHandler.initialize. Finally, the URLSpec may have a name, which will allow it to be used with RequestHandler.reverse_url.

For example, in this fragment the root URL / is mapped to MainHandler and URLs of the form /story/ followed by a number are mapped to StoryHandler. That number is passed (as a string) to StoryHandler.get.

class MainHandler(RequestHandler):
    def get(self):
        self.write('<a href="%s">link to story 1</a>' %
                   self.reverse_url("story", "1"))

class StoryHandler(RequestHandler):
    def initialize(self, db):
        self.db = db

    def get(self, story_id):
        self.write("this is story %s" % story_id)

app = Application([
    url(r"/", MainHandler),
    url(r"/story/([0-9]+)", StoryHandler, dict(db=db), name="story")
    ])

The Application constructor takes many keyword arguments that can be used to customize the behavior of the application and enable optional features; see Application.settings for the complete list.

Subclassing RequestHandler¶

Most of the work of a Tornado web application is done in subclasses of RequestHandler. The main entry point for a handler subclass is a method named after the HTTP method being handled: get(), post(), etc. Each handler may define one or more of these methods to handle different HTTP actions. As described above, these methods will be called with arguments corresponding to the capturing groups of the routing rule that matched.

Within a handler, call methods such as RequestHandler.render or RequestHandler.write to produce a response. render() loads a Template by name and renders it with the given arguments. write() is used for non-template-based output; it accepts strings, bytes, and dictionaries (dicts will be encoded as JSON).

Many methods in RequestHandler are designed to be overridden in subclasses and be used throughout the application. It is common to define a BaseHandler class that overrides methods such as write_error and get_current_user and then subclass your own BaseHandler instead of RequestHandler for all your specific handlers.

Handling request input¶

The request handler can access the object representing the current request with self.request. See the class definition for HTTPServerRequest for a complete list of attributes.

Request data in the formats used by HTML forms will be parsed for you and is made available in methods like get_query_argument and get_body_argument.

class MyFormHandler(RequestHandler):
    def get(self):
        self.write('<html><body><form action="/myform" method="POST">'
                   '<input type="text" name="message">'
                   '<input type="submit" value="Submit">'
                   '</form></body></html>')

    def post(self):
        self.set_header("Content-Type", "text/plain")
        self.write("You wrote " + self.get_body_argument("message"))

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 it expects a list. For lists, use get_query_arguments and get_body_arguments instead of their singular counterparts.

Files uploaded via a form are available in self.request.files, which maps names (the name of the HTML <input type="file"> element) to a list of files. Each file is a dictionary of the form {"filename":..., "content_type":..., "body":...}. The files object is only present if the files were uploaded with a form wrapper (i.e. a multipart/form-data Content-Type); if this format was not used the raw uploaded data is available in self.request.body. By default uploaded files are fully buffered in memory; if you need to handle files that are too large to comfortably keep in memory see the stream_request_body class decorator.

Due to the quirks of the HTML form encoding (e.g. the ambiguity around singular versus plural arguments), Tornado does not attempt to unify form arguments with other types of input. In particular, we do not parse JSON request bodies. Applications that wish to use JSON instead of form-encoding may override prepare to parse their requests:

def prepare(self):
    if self.request.headers["Content-Type"].startswith("application/json"):
        self.json_args = json.loads(self.request.body)
    else:
        self.json_args = None

Overriding RequestHandler methods¶

In addition to get()/post()/etc, certain other methods in RequestHandler are designed to be overridden by subclasses when necessary. On every request, the following sequence of calls takes place:

1. A new RequestHandler object is created on each request
2. initialize() is called with the initalization arguments from the Application configuration. initialize should typically just save the arguments passed into member variables; it may not produce any output or call methods like send_error.
3. prepare() is called. This is most useful in a base class shared by all of your handler subclasses, as prepare is called no matter which HTTP method is used. prepare may produce output; if it calls finish (or redirect, etc), processing stops here.
4. One of the HTTP methods is called: get(), post(), put(), etc. If the URL regular expression contains capturing groups, they are passed as arguments to this method.
5. When the request is finished, on_finish() is called. For synchronous handlers this is immediately after get() (etc) return; for asynchronous handlers it is after the call to finish().

All methods designed to be overridden are noted as such in the RequestHandler documentation. Some of the most commonly overridden methods include:

• write_error - outputs HTML for use on error pages.
• on_connection_close - called when the client disconnects; applications may choose to detect this case and halt further processing. Note that there is no guarantee that a closed connection can be detected promptly.
• get_current_user - see User authentication
• get_user_locale - returns Locale object to use for the current user
• set_default_headers - may be used to set additional headers on the response (such as a custom Server header)

Error Handling¶

If a handler raises an exception, Tornado will call RequestHandler.write_error to generate an error page. tornado.web.HTTPError can be used to generate a specified status code; all other exceptions return a 500 status.

The default error page includes a stack trace in debug mode and a one-line description of the error (e.g. “500: Internal Server Error”) otherwise. To produce a custom error page, override RequestHandler.write_error (probably in a base class shared by all your handlers). This method may produce output normally via methods such as write and render. If the error was caused by an exception, an exc_info triple will be passed as a keyword argument (note that this exception is not guaranteed to be the current exception in sys.exc_info, so write_error must use e.g. traceback.format_exception instead of traceback.format_exc).

It is also possible to generate an error page from regular handler methods instead of write_error by calling set_status, writing a response, and returning. The special exception tornado.web.Finish may be raised to terminate the handler without calling write_error in situations where simply returning is not convenient.

For 404 errors, use the default_handler_class Application setting. This handler should override prepare instead of a more specific method like get() so it works with any HTTP method. It should produce its error page as described above: either by raising a HTTPError(404) and overriding write_error, or calling self.set_status(404) and producing the response directly in prepare().

Redirection¶

There are two main ways you can redirect requests in Tornado: RequestHandler.redirect and with the RedirectHandler.

You can use self.redirect() within a RequestHandler method to redirect users elsewhere. There is also an optional parameter permanent which you can use to indicate that the redirection is considered permanent. The default value of permanent is False, which generates a 302 Found HTTP response code and is appropriate for things like redirecting users after successful POST requests. If permanent is true, the 301 Moved Permanently HTTP response code is used, which is useful for e.g. redirecting to a canonical URL for a page in an SEO-friendly manner.

RedirectHandler lets you configure redirects directly in your Application routing table. For example, to configure a single static redirect:

app = tornado.web.Application([
    url(r"/app", tornado.web.RedirectHandler,
        dict(url="http://itunes.apple.com/my-app-id")),
    ])

RedirectHandler also supports regular expression substitutions. The following rule redirects all requests beginning with /pictures/ to the prefix /photos/ instead:

app = tornado.web.Application([
    url(r"/photos/(.*)", MyPhotoHandler),
    url(r"/pictures/(.*)", tornado.web.RedirectHandler,
        dict(url=r"/photos/\1")),
    ])

Unlike RequestHandler.redirect, RedirectHandler uses permanent redirects by default. This is because the routing table does not change at runtime and is presumed to be permanent, while redirects found in handlers are likely to be the result of other logic that may change. To send a temporary redirect with a RedirectHandler, add permanent=False to the RedirectHandler initialization arguments.

Asynchronous handlers¶

Tornado handlers are synchronous by default: when the get()/post() method returns, the request is considered finished and the response is sent. Since all other requests are blocked while one handler is running, any long-running handler should be made asynchronous so it can call its slow operations in a non-blocking way. This topic is covered in more detail in Asynchronous and non-Blocking I/O; this section is about the particulars of asynchronous techniques in RequestHandler subclasses.

The simplest way to make a handler asynchronous is to use the coroutine decorator. This allows you to perform non-blocking I/O with the yield keyword, and no response will be sent until the coroutine has returned. See Coroutines for more details.

In some cases, coroutines may be less convenient than a callback-oriented style, in which case the tornado.web.asynchronous decorator can be used instead. When this decorator is used the response is not automatically sent; instead the request will be kept open until some callback calls RequestHandler.finish. It is up to the application to ensure that this method is called, or else the user’s browser will simply hang.

Here is an example that makes a call to the FriendFeed API using Tornado’s built-in AsyncHTTPClient:

class MainHandler(tornado.web.RequestHandler):
    @tornado.web.asynchronous
    def get(self):
        http = tornado.httpclient.AsyncHTTPClient()
        http.fetch("http://friendfeed-api.com/v2/feed/bret",
                   callback=self.on_response)

    def on_response(self, response):
        if response.error: raise tornado.web.HTTPError(500)
        json = tornado.escape.json_decode(response.body)
        self.write("Fetched " + str(len(json["entries"])) + " entries "
                   "from the FriendFeed API")
        self.finish()

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:

class MainHandler(tornado.web.RequestHandler):
    @tornado.gen.coroutine
    def get(self):
        http = tornado.httpclient.AsyncHTTPClient()
        response = yield http.fetch("http://friendfeed-api.com/v2/feed/bret")
        json = tornado.escape.json_decode(response.body)
        self.write("Fetched " + str(len(json["entries"])) + " entries "
                   "from the FriendFeed API")

For a more advanced asynchronous example, take a look at the chat example application, which implements an AJAX chat room using long polling. Users of long polling may want to override on_connection_close() to clean up after the client closes the connection (but see that method’s docstring for caveats).

Configuring templates¶

By default, Tornado looks for template files in the same directory as the .py files that refer to them. To put your template files in a different directory, use the template_path Application setting (or override RequestHandler.get_template_path if you have different template paths for different handlers).

To load templates from a non-filesystem location, subclass tornado.template.BaseLoader and pass an instance as the template_loader application setting.

Compiled templates are cached by default; to turn off this caching and reload templates so changes to the underlying files are always visible, use the application settings compiled_template_cache=False or debug=True.

Template syntax¶

A Tornado template is just HTML (or any other text-based format) with Python control sequences and expressions embedded within the markup:

<html>
   <head>
      <title>{{ title }}</title>
   </head>
   <body>
     <ul>
       {% for item in items %}
         <li>{{ escape(item) }}</li>
       {% end %}
     </ul>
   </body>
 </html>

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:

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        items = ["Item 1", "Item 2", "Item 3"]
        self.render("template.html", title="My title", items=items)

Tornado templates support control statements and expressions. Control statements are surrounded by {% and %}, e.g., {% if len(items) > 2 %}. Expressions are surrounded by {{ and }}, e.g., {{ items[0] }}.

Control statements more or less map exactly to Python statements. We support if, for, while, and try, all of which are terminated with {% end %}. We also support template inheritance using the extends and block statements, which are described in detail in the documentation for the tornado.template.

Expressions can be any Python expression, including function calls. Template code is executed in a namespace that includes the following objects and functions (Note that this list applies to templates rendered using RequestHandler.render and render_string. If you’re using the tornado.template module directly outside of a RequestHandler many of these entries are not present).

• escape: alias for tornado.escape.xhtml_escape
• xhtml_escape: alias for tornado.escape.xhtml_escape
• url_escape: alias for tornado.escape.url_escape
• json_encode: alias for tornado.escape.json_encode
• squeeze: alias for tornado.escape.squeeze
• linkify: alias for tornado.escape.linkify
• datetime: the Python datetime module
• handler: the current RequestHandler object
• request: alias for handler.request
• current_user: alias for handler.current_user
• locale: alias for handler.locale
• _: alias for handler.locale.translate
• static_url: alias for handler.static_url
• xsrf_form_html: alias for handler.xsrf_form_html
• reverse_url: alias for Application.reverse_url
• All entries from the ui_methods and ui_modules Application settings
• Any keyword arguments passed to render or render_string

When you are building a real application, you are going to want to use all of the features of Tornado templates, especially template inheritance. Read all about those features in the tornado.template section (some features, including UIModules are implemented in the tornado.web module)

Under the hood, Tornado templates are translated directly to Python. The expressions you include in your template are copied verbatim into a Python function representing your template. We don’t try to prevent anything in the template language; we created it explicitly to provide the flexibility that other, stricter templating systems prevent. Consequently, if you write random stuff inside of your template expressions, you will get random Python errors when you execute the template.

All template output is escaped by default, using the tornado.escape.xhtml_escape function. This behavior can be changed globally by passing autoescape=None to the Application or tornado.template.Loader constructors, for a template file with the {% autoescape None %} directive, or for a single expression by replacing {{ ... }} with {% raw ...%}. Additionally, in each of these places the name of an alternative escaping function may be used instead of None.

Note that while Tornado’s automatic escaping is helpful in avoiding XSS vulnerabilities, it is not sufficient in all cases. Expressions that appear in certain locations, such as in Javascript or CSS, may need additional escaping. Additionally, either care must be taken to always use double quotes and xhtml_escape in HTML attributes that may contain untrusted content, or a separate escaping function must be used for attributes (see e.g. http://wonko.com/post/html-escaping)

Internationalization¶

The locale of the current user (whether they are logged in or not) is always available as self.locale in the request handler and as locale in templates. The name of the locale (e.g., en_US) is available as locale.name, and you can translate strings with the Locale.translate method. Templates also have the global function call _() available for string translation. The translate function has two forms:

_("Translate this string")

which translates the string directly based on the current locale, and:

_("A person liked this", "%(num)d people liked this",
  len(people)) % {"num": len(people)}

which translates a string that can be singular or plural based on the value of the third argument. In the example above, a translation of the first string will be returned if len(people) is 1, or a translation of the second string will be returned otherwise.

The most common pattern for translations is to use Python named placeholders for variables (the %(num)d in the example above) since placeholders can move around on translation.

Here is a properly internationalized template:

<html>
   <head>
      <title>FriendFeed - {{ _("Sign in") }}</title>
   </head>
   <body>
     <form action="{{ request.path }}" method="post">
       <div>{{ _("Username") }} <input type="text" name="username"/></div>
       <div>{{ _("Password") }} <input type="password" name="password"/></div>
       <div><input type="submit" value="{{ _("Sign in") }}"/></div>
       {% module xsrf_form_html() %}
     </form>
   </body>
 </html>

By default, we detect the user’s locale using the Accept-Language 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:

class BaseHandler(tornado.web.RequestHandler):
    def get_current_user(self):
        user_id = self.get_secure_cookie("user")
        if not user_id: return None
        return self.backend.get_user_by_id(user_id)

    def get_user_locale(self):
        if "locale" not in self.current_user.prefs:
            # Use the Accept-Language header
            return None
        return self.current_user.prefs["locale"]

If get_user_locale returns None, we fall back on the Accept-Language header.

The tornado.locale module supports loading translations in two formats: the .mo format used by gettext and related tools, and a simple .csv format. An application will generally call either tornado.locale.load_translations or tornado.locale.load_gettext_translations once at startup; see those methods for more details on the supported formats..

You can get the list of supported locales in your application with tornado.locale.get_supported_locales(). The user’s locale is chosen to be the closest match based on the supported locales. For example, if the user’s locale is es_GT, and the es locale is supported, self.locale will be es for that request. We fall back on en_US if no close match can be found.

UI modules¶

Tornado supports UI modules to make it easy to support standard, reusable UI widgets across your application. UI modules are like special function calls to render components of your page, and they can come packaged with their own CSS and JavaScript.

For example, if you are implementing a blog, and you want to have blog entries appear on both the blog home page and on each blog entry page, you can make an Entry module to render them on both pages. First, create a Python module for your UI modules, e.g., uimodules.py:

class Entry(tornado.web.UIModule):
    def render(self, entry, show_comments=False):
        return self.render_string(
            "module-entry.html", entry=entry, show_comments=show_comments)

Tell Tornado to use uimodules.py using the ui_modules setting in your application:

from . import uimodules

class HomeHandler(tornado.web.RequestHandler):
    def get(self):
        entries = self.db.query("SELECT * FROM entries ORDER BY date DESC")
        self.render("home.html", entries=entries)

class EntryHandler(tornado.web.RequestHandler):
    def get(self, entry_id):
        entry = self.db.get("SELECT * FROM entries WHERE id = %s", entry_id)
        if not entry: raise tornado.web.HTTPError(404)
        self.render("entry.html", entry=entry)

settings = {
    "ui_modules": uimodules,
}
application = tornado.web.Application([
    (r"/", HomeHandler),
    (r"/entry/([0-9]+)", EntryHandler),
], **settings)

Within a template, you can call a module with the {% module %} statement. For example, you could call the Entry module from both home.html:

{% for entry in entries %}
  {% module Entry(entry) %}
{% end %}

and entry.html:

{% module Entry(entry, show_comments=True) %}

Modules can include custom CSS and JavaScript functions by overriding the embedded_css, embedded_javascript, javascript_files, or css_files methods:

class Entry(tornado.web.UIModule):
    def embedded_css(self):
        return ".entry { margin-bottom: 1em; }"

    def render(self, entry, show_comments=False):
        return self.render_string(
            "module-entry.html", show_comments=show_comments)

Module CSS and JavaScript will be included once no matter how many times a module is used on a page. CSS is always included in the <head> of the page, and JavaScript is always included just before the </body> tag at the end of the page.

When additional Python code is not required, a template file itself may be used as a module. For example, the preceding example could be rewritten to put the following in module-entry.html:

{{ set_resources(embedded_css=".entry { margin-bottom: 1em; }") }}
<!-- more template html... -->

This revised template module would be invoked with:

{% module Template("module-entry.html", show_comments=True) %}

The set_resources function is only available in templates invoked via {% module Template(...) %}. Unlike the {% include ... %} directive, template modules have a distinct namespace from their containing template - they can only see the global template namespace and their own keyword arguments.

Cookies and secure cookies¶

You can set cookies in the user’s browser with the set_cookie method:

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        if not self.get_cookie("mycookie"):
            self.set_cookie("mycookie", "myvalue")
            self.write("Your cookie was not set yet!")
        else:
            self.write("Your cookie was set!")

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 signed cookies with the set_secure_cookie and 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:

application = tornado.web.Application([
    (r"/", MainHandler),
], cookie_secret="__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__")

Signed cookies contain the encoded value of the cookie in addition to a timestamp and an 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:

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        if not self.get_secure_cookie("mycookie"):
            self.set_secure_cookie("mycookie", "myvalue")
            self.write("Your cookie was not set yet!")
        else:
            self.write("Your cookie was set!")

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 – anyone who obtains the value of this key could produce their own signed cookies.

By default, Tornado’s secure cookies expire after 30 days. To change this, use the expires_days keyword argument to set_secure_cookie and the max_age_days argument to get_secure_cookie. These two values are passed separately so that you may e.g. have a cookie that is valid for 30 days for most purposes, but for certain sensitive actions (such as changing billing information) you use a smaller max_age_days when reading the cookie.

User authentication¶

The currently authenticated user is available in every request handler as self.current_user, and in every template as current_user. By default, current_user is None.

To implement user authentication in your application, you need to 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:

class BaseHandler(tornado.web.RequestHandler):
    def get_current_user(self):
        return self.get_secure_cookie("user")

class MainHandler(BaseHandler):
    def get(self):
        if not self.current_user:
            self.redirect("/login")
            return
        name = tornado.escape.xhtml_escape(self.current_user)
        self.write("Hello, " + name)

class LoginHandler(BaseHandler):
    def get(self):
        self.write('<html><body><form action="/login" method="post">'
                   'Name: <input type="text" name="name">'
                   '<input type="submit" value="Sign in">'
                   '</form></body></html>')

    def post(self):
        self.set_secure_cookie("user", self.get_argument("name"))
        self.redirect("/")

application = tornado.web.Application([
    (r"/", MainHandler),
    (r"/login", LoginHandler),
], cookie_secret="__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__")

You can require that the user be logged in using the Python decorator 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:

class MainHandler(BaseHandler):
    @tornado.web.authenticated
    def get(self):
        name = tornado.escape.xhtml_escape(self.current_user)
        self.write("Hello, " + name)

settings = {
    "cookie_secret": "__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__",
    "login_url": "/login",
}
application = tornado.web.Application([
    (r"/", MainHandler),
    (r"/login", LoginHandler),
], **settings)

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 shorthand for if not self.current_user: self.redirect() and may not be appropriate for non-browser-based login schemes.

Check out the Tornado Blog example application for a complete example that uses authentication (and stores user data in a MySQL database).

Third party authentication¶

The tornado.auth module implements the authentication and authorization protocols for a number of the most popular sites on the web, including Google/Gmail, Facebook, Twitter, and FriendFeed. The module includes methods to log users in via these sites and, where applicable, methods to authorize access to the service so you can, e.g., download a user’s address book or publish a Twitter message on their behalf.

Here is an example handler that uses Google for authentication, saving the Google credentials in a cookie for later access:

class GoogleHandler(tornado.web.RequestHandler, tornado.auth.GoogleMixin):
    @tornado.web.asynchronous
    def get(self):
        if self.get_argument("openid.mode", None):
            self.get_authenticated_user(self._on_auth)
            return
        self.authenticate_redirect()

    def _on_auth(self, user):
        if not user:
            self.authenticate_redirect()
            return
        # Save the user with, e.g., set_secure_cookie()

See the tornado.auth module documentation for more details.

Cross-site request forgery protection¶

Cross-site request forgery, or XSRF, is a common problem for personalized web applications. See the Wikipedia article for more information on how XSRF works.

The generally accepted solution to prevent XSRF is to cookie every user with an unpredictable value and include that value as an additional argument with every form submission on your site. If the cookie and the value in the form submission do not match, then the request is likely forged.

Tornado comes with built-in XSRF protection. To include it in your site, include the application setting xsrf_cookies:

settings = {
    "cookie_secret": "__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__",
    "login_url": "/login",
    "xsrf_cookies": True,
}
application = tornado.web.Application([
    (r"/", MainHandler),
    (r"/login", LoginHandler),
], **settings)

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 you turn this setting on, you need to instrument all forms that submit via POST to contain this field. You can do this with the special UIModule xsrf_form_html(), available in all templates:

<form action="/new_message" method="post">
  {% module xsrf_form_html() %}
  <input type="text" name="message"/>
  <input type="submit" value="Post"/>
</form>

If you submit AJAX POST requests, you will also need to instrument your JavaScript to include the _xsrf value with each request. This is the jQuery function we use at FriendFeed for AJAX POST requests that automatically adds the _xsrf value to all requests:

function getCookie(name) {
    var r = document.cookie.match("\\b" + name + "=([^;]*)\\b");
    return r ? r[1] : undefined;
}

jQuery.postJSON = function(url, args, callback) {
    args._xsrf = getCookie("_xsrf");
    $.ajax({url: url, data: $.param(args), dataType: "text", type: "POST",
        success: function(response) {
        callback(eval("(" + response + ")"));
    }});
};

For PUT and DELETE requests (as well as POST requests that do not use form-encoded arguments), the XSRF token may also be passed via an HTTP header named X-XSRFToken. The XSRF cookie is normally set when xsrf_form_html is used, but in a pure-Javascript application that does not use any regular forms you may need to access self.xsrf_token manually (just reading the property is enough to set the cookie as a side effect).

If you need to customize XSRF behavior on a per-handler basis, you can override RequestHandler.check_xsrf_cookie(). For example, if you have an API whose authentication does not use cookies, you may want to disable XSRF protection by making check_xsrf_cookie() do nothing. However, if you support both cookie and non-cookie-based authentication, it is important that XSRF protection be used whenever the current request is authenticated with a cookie.

Processes and ports¶

Due to the Python GIL (Global Interpreter Lock), it is necessary to run multiple Python processes to take full advantage of multi-CPU machines. Typically it is best to run one process per CPU.

Tornado includes a built-in multi-process mode to start several processes at once. This requires a slight alteration to the standard main function:

def main():
    app = make_app()
    server = tornado.httpserver.HTTPServer(app)
    server.bind(8888)
    server.start(0)  # forks one process per cpu
    IOLoop.current().start()

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 nothing touch the global IOLoop instance (even indirectly) before the fork. Second, it is difficult to do zero-downtime updates in this model. Finally, since all the processes share the same port it is more difficult to monitor them individually.

For more sophisticated deployments, it is recommended to start the processes independently, and have each one listen on a different port. The “process groups” feature of supervisord is one good way to arrange this. When each process uses a different port, an external load balancer such as HAProxy or nginx is usually needed to present a single address to outside visitors.

Running behind a load balancer¶

When running behind a load balancer like nginx, it is recommended to pass xheaders=True to the HTTPServer constructor. This will tell Tornado to use headers like X-Real-IP to get the user’s IP address instead of attributing all traffic to the balancer’s IP address.

This is a barebones nginx config file that is structurally similar to the one we use at FriendFeed. It assumes nginx and the Tornado servers are running on the same machine, and the four Tornado servers are running on ports 8000 - 8003:

user nginx;
worker_processes 1;

error_log /var/log/nginx/error.log;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
    use epoll;
}

http {
    # Enumerate all the Tornado servers here
    upstream frontends {
        server 127.0.0.1:8000;
        server 127.0.0.1:8001;
        server 127.0.0.1:8002;
        server 127.0.0.1:8003;
    }

    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    access_log /var/log/nginx/access.log;

    keepalive_timeout 65;
    proxy_read_timeout 200;
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    gzip on;
    gzip_min_length 1000;
    gzip_proxied any;
    gzip_types text/plain text/html text/css text/xml
               application/x-javascript application/xml
               application/atom+xml text/javascript;

    # Only retry if there was a communication error, not a timeout
    # on the Tornado server (to avoid propagating "queries of death"
    # to all frontends)
    proxy_next_upstream error;

    server {
        listen 80;

        # Allow file uploads
        client_max_body_size 50M;

        location ^~ /static/ {
            root /var/www;
            if ($query_string) {
                expires max;
            }
        }
        location = /favicon.ico {
            rewrite (.*) /static/favicon.ico;
        }
        location = /robots.txt {
            rewrite (.*) /static/robots.txt;
        }

        location / {
            proxy_pass_header Server;
            proxy_set_header Host $http_host;
            proxy_redirect off;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Scheme $scheme;
            proxy_pass http://frontends;
        }
    }
}

Static files and aggressive file caching¶

You can serve static files from Tornado by specifying the static_path setting in your application:

settings = {
    "static_path": os.path.join(os.path.dirname(__file__), "static"),
    "cookie_secret": "__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__",
    "login_url": "/login",
    "xsrf_cookies": True,
}
application = tornado.web.Application([
    (r"/", MainHandler),
    (r"/login", LoginHandler),
    (r"/(apple-touch-icon\.png)", tornado.web.StaticFileHandler,
     dict(path=settings['static_path'])),
], **settings)

This setting will automatically make all requests that start with /static/ serve from that static directory, e.g., http://localhost:8888/static/foo.png will serve the file foo.png from the specified static directory. We also automatically serve /robots.txt and /favicon.ico from the static directory (even though they don’t start with the /static/ prefix).

In the above settings, we have explicitly configured Tornado to serve apple-touch-icon.png from the root with the StaticFileHandler, though it is physically in the static file directory. (The capturing group in that regular expression is necessary to tell StaticFileHandler the requested filename; recall that capturing groups are passed to handlers as method arguments.) You could do the same thing to serve e.g. sitemap.xml from the site root. Of course, you can also avoid faking a root apple-touch-icon.png by using the appropriate <link /> tag in your HTML.

To improve performance, it is generally a good idea for browsers to cache static resources aggressively so browsers won’t send unnecessary If-Modified-Since or Etag requests that might block the rendering of the page. Tornado supports this out of the box with static content versioning.

To use this feature, use the static_url method in your templates rather than typing the URL of the static file directly in your HTML:

<html>
   <head>
      <title>FriendFeed - {{ _("Home") }}</title>
   </head>
   <body>
     <div><img src="{{ static_url("images/logo.png") }}"/></div>
   </body>
 </html>

The static_url() function will translate that relative path to a URI that looks like /static/images/logo.png?v=aae54. The v argument is a hash of the content in logo.png, and its presence makes the Tornado server send cache headers to the user’s browser that will make the browser cache the content indefinitely.

Since the v argument is based on the content of the file, if you update a file and restart your server, it will start sending a new v value, so the user’s browser will automatically fetch the new file. If the file’s contents don’t change, the browser will continue to use a locally cached copy without ever checking for updates on the server, significantly improving rendering performance.

In production, you probably want to serve static files from a more optimized static file server like nginx. You can configure most any web server to recognize the version tags used by static_url() and set caching headers accordingly. Here is the relevant portion of the nginx configuration we use at FriendFeed:

location /static/ {
    root /var/friendfeed/static;
    if ($query_string) {
        expires max;
    }
 }

Debug mode and automatic reloading¶

If you pass debug=True to the Application constructor, the app will be run in debug/development mode. In this mode, several features intended for convenience while developing will be enabled (each of which is also available as an individual flag; if both are specified the individual flag takes precedence):

• autoreload=True: The app will watch for changes to its source files and reload itself when anything changes. This reduces the need to manually restart the server during development. However, certain failures (such as syntax errors at import time) can still take the server down in a way that debug mode cannot currently recover from.
• compiled_template_cache=False: Templates will not be cached.
• static_hash_cache=False: Static file hashes (used by the static_url function) will not be cached
• serve_traceback=True: When an exception in a RequestHandler is not caught, an error page including a stack trace will be generated.

Autoreload mode is not compatible with the multi-process mode of HTTPServer. You must not give HTTPServer.start an argument other than 1 (or call tornado.process.fork_processes) if you are using autoreload mode.

The automatic reloading feature of debug mode is available as a standalone module in tornado.autoreload. The two can be used in combination to provide extra robustness against syntax errors: set autoreload=True within the app to detect changes while it is running, and start it with python -m tornado.autoreload myserver.py to catch any syntax errors or other errors at startup.

Reloading loses any Python interpreter command-line arguments (e.g. -u) because it re-executes Python using sys.executable and sys.argv. Additionally, modifying these variables will cause reloading to behave incorrectly.

On some platforms (including Windows and Mac OSX prior to 10.6), the process cannot be updated “in-place”, so when a code change is detected the old server exits and a new one starts. This has been known to confuse some IDEs.

WSGI and Google App Engine¶

Tornado is normally intended to be run on its own, without a WSGI container. However, in some environments (such as Google App Engine), only WSGI is allowed and applications cannot run their own servers. In this case Tornado supports a limited mode of operation that does not support asynchronous operation but allows a subset of Tornado’s functionality in a WSGI-only environment. The features that are not allowed in WSGI mode include coroutines, the @asynchronous decorator, AsyncHTTPClient, the auth module, and WebSockets.

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:

import tornado.web
import tornado.wsgi

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        self.write("Hello, world")

tornado_app = tornado.web.Application([
    (r"/", MainHandler),
])
application = tornado.wsgi.WSGIAdapter(tornado_app)

See the appengine example application for a full-featured AppEngine app built on Tornado.

Thread-safety notes¶

In general, methods on RequestHandler and elsewhere in Tornado are not thread-safe. In particular, methods such as write(), finish(), and flush() must only be called from the main thread. If you use multiple threads it is important to use IOLoop.add_callback to transfer control back to the main thread before finishing the request.

Request handlers¶

class tornado.web.RequestHandler(application, request, **kwargs)[源代码]¶

Base class for HTTP request handlers.

Subclasses must define at least one of the methods defined in the “Entry points” section below.

Application configuration¶

class tornado.web.Application(handlers=None, default_host='', transforms=None, **settings)[源代码]¶

A collection of request handlers that make up a web application.

Instances of this class are callable and can be passed directly to HTTPServer to serve the application:

application = web.Application([
    (r"/", MainPageHandler),
])
http_server = httpserver.HTTPServer(application)
http_server.listen(8080)
ioloop.IOLoop.current().start()

The constructor for this class takes in a list of URLSpec objects or (regexp, request_class) tuples. When we receive requests, we iterate over the list in order and instantiate an instance of the first request class whose regexp matches the request path. The request class can be specified as either a class object or a (fully-qualified) name.

Each tuple can contain additional elements, which correspond to the arguments to the URLSpec constructor. (Prior to Tornado 3.2, this only tuples of two or three elements were allowed).

A dictionary may be passed as the third element of the tuple, which will be used as keyword arguments to the handler’s constructor and initialize method. This pattern is used for the StaticFileHandler in this example (note that a StaticFileHandler can be installed automatically with the static_path setting described below):

application = web.Application([
    (r"/static/(.*)", web.StaticFileHandler, {"path": "/var/www"}),
])

We support virtual hosts with the add_handlers method, which takes in a host regular expression as the first argument:

application.add_handlers(r"www\.myhost\.com", [
    (r"/article/([0-9]+)", ArticleHandler),
])

You can serve static files by sending the static_path setting as a keyword argument. We will serve those files from the /static/ URI (this is configurable with the static_url_prefix setting), and we will serve /favicon.ico and /robots.txt from the same directory. A custom subclass of StaticFileHandler can be specified with the static_handler_class setting.

settings¶

Additional keyword arguments passed to the constructor are saved in the settings dictionary, and are often referred to in documentation as “application settings”. Settings are used to customize various aspects of Tornado (although in some cases richer customization is possible by overriding methods in a subclass of RequestHandler). Some applications also like to use the settings dictionary as a way to make application-specific settings available to handlers without using global variables. Settings used in Tornado are described below.

General settings:

• autoreload: If True, the server process will restart when any source files change, as described in Debug mode and automatic reloading. This option is new in Tornado 3.2; previously this functionality was controlled by the debug setting.
• debug: Shorthand for several debug mode settings, described in Debug mode and automatic reloading. Setting debug=True is equivalent to autoreload=True, compiled_template_cache=False, static_hash_cache=False, serve_traceback=True.
• default_handler_class and default_handler_args: This handler will be used if no other match is found; use this to implement custom 404 pages (new in Tornado 3.2).
• compress_response: If True, responses in textual formats will be compressed automatically. New in Tornado 4.0.
• gzip: Deprecated alias for compress_response since Tornado 4.0.
• log_function: This function will be called at the end of every request to log the result (with one argument, the RequestHandler object). The default implementation writes to the logging module’s root logger. May also be customized by overriding Application.log_request.
• serve_traceback: If true, the default error page will include the traceback of the error. This option is new in Tornado 3.2; previously this functionality was controlled by the debug setting.
• ui_modules and ui_methods: May be set to a mapping of UIModule or UI methods to be made available to templates. May be set to a module, dictionary, or a list of modules and/or dicts. See UI modules for more details.

Authentication and security settings:

• cookie_secret: Used by RequestHandler.get_secure_cookie and set_secure_cookie to sign cookies.
• login_url: The authenticated decorator will redirect to this url if the user is not logged in. Can be further customized by overriding RequestHandler.get_login_url
• xsrf_cookies: If true, Cross-site request forgery protection will be enabled.
• xsrf_cookie_version: Controls the version of new XSRF cookies produced by this server. Should generally be left at the default (which will always be the highest supported version), but may be set to a lower value temporarily during version transitions. New in Tornado 3.2.2, which introduced XSRF cookie version 2.
• twitter_consumer_key, twitter_consumer_secret, friendfeed_consumer_key, friendfeed_consumer_secret, google_consumer_key, google_consumer_secret, facebook_api_key, facebook_secret: Used in the tornado.auth module to authenticate to various APIs.

Template settings:

• autoescape: Controls automatic escaping for templates. May be set to None to disable escaping, or to the name of a function that all output should be passed through. Defaults to "xhtml_escape". Can be changed on a per-template basis with the {% autoescape %} directive.
• compiled_template_cache: Default is True; if False templates will be recompiled on every request. This option is new in Tornado 3.2; previously this functionality was controlled by the debug setting.
• template_path: Directory containing template files. Can be further customized by overriding RequestHandler.get_template_path
• template_loader: Assign to an instance of tornado.template.BaseLoader to customize template loading. If this setting is used the template_path and autoescape settings are ignored. Can be further customized by overriding RequestHandler.create_template_loader.

Static file settings:

• static_hash_cache: Default is True; if False static urls will be recomputed on every request. This option is new in Tornado 3.2; previously this functionality was controlled by the debug setting.
• static_path: Directory from which static files will be served.
• static_url_prefix: Url prefix for static files, defaults to "/static/".
• static_handler_class, static_handler_args: May be set to use a different handler for static files instead of the default tornado.web.StaticFileHandler. static_handler_args, if set, should be a dictionary of keyword arguments to be passed to the handler’s initialize method.

listen(port, address='', **kwargs)[源代码]¶

Starts an HTTP server for this application on the given port.

This is a convenience alias for creating an HTTPServer object and calling its listen method. Keyword arguments not supported by HTTPServer.listen are passed to the HTTPServer constructor. For advanced uses (e.g. multi-process mode), do not use this method; create an HTTPServer and call its TCPServer.bind/TCPServer.start methods directly.

Note that after calling this method you still need to call IOLoop.current().start() to start the server.

add_handlers(host_pattern, host_handlers)[源代码]¶

Appends the given handlers to our handler list.

Host patterns are processed sequentially in the order they were added. All matching patterns will be considered.

reverse_url(name, *args)[源代码]¶

Returns a URL path for handler named name

The handler must be added to the application as a named URLSpec.

Args will be substituted for capturing groups in the URLSpec regex. They will be converted to strings if necessary, encoded as utf8, and url-escaped.

log_request(handler)[源代码]¶

Writes a completed HTTP request to the logs.

By default writes to the python root logger. To change this behavior either subclass Application and override this method, or pass a function in the application settings dictionary as log_function.

class tornado.web.URLSpec(pattern, handler, kwargs=None, name=None)[源代码]¶

Specifies mappings between URLs and handlers.

Parameters:

• pattern: Regular expression to be matched. Any groups in the regex will be passed in to the handler’s get/post/etc methods as arguments.
• handler: RequestHandler subclass to be invoked.
• kwargs (optional): A dictionary of additional arguments to be passed to the handler’s constructor.
• name (optional): A name for this handler. Used by Application.reverse_url.

The URLSpec class is also available under the name tornado.web.url.

Decorators¶

tornado.web.asynchronous(method)[源代码]¶

Wrap request handler methods with this if they are asynchronous.

This decorator is for callback-style asynchronous methods; for coroutines, use the @gen.coroutine decorator without @asynchronous. (It is legal for legacy reasons to use the two decorators together provided @asynchronous is first, but @asynchronous will be ignored in this case)

This decorator should only be applied to the HTTP verb methods; 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() to finish the HTTP request. Without this decorator, the request is automatically finished when the get() or post() method returns. Example:

3.1 新版功能: The ability to use @gen.coroutine without @asynchronous.

tornado.web.authenticated(method)[源代码]¶

Decorate methods with this to require that the user be logged in.

If the user is not logged in, they will be redirected to the configured login url.

If you configure a login url with a query parameter, Tornado will assume you know what you’re doing and use it as-is. If not, it will add a next parameter so the login page knows where to send you once you’re logged in.

tornado.web.addslash(method)[源代码]¶

Use this decorator to add a missing trailing slash to the request path.

For example, a request to /foo would redirect to /foo/ with this decorator. Your request handler mapping should use a regular expression like r'/foo/?' in conjunction with using the decorator.

tornado.web.removeslash(method)[源代码]¶

Use this decorator to remove trailing slashes from the request path.

For example, a request to /foo/ would redirect to /foo with this decorator. Your request handler mapping should use a regular expression like r'/foo/*' in conjunction with using the decorator.

tornado.web.stream_request_body(cls)[源代码]¶

Apply to RequestHandler subclasses to enable streaming body support.

This decorator implies the following changes:

• HTTPServerRequest.body is undefined, and body arguments will not be included in RequestHandler.get_argument.
• RequestHandler.prepare is called when the request headers have been read instead of after the entire body has been read.
• The subclass must define a method data_received(self, data):, which will be called zero or more times as data is available. Note that if the request has an empty body, data_received may not be called.
• prepare and data_received may return Futures (such as via @gen.coroutine, in which case the next method will not be called until those futures have completed.
• The regular HTTP method (post, put, etc) will be called after the entire body has been read.

There is a subtle interaction between data_received and asynchronous prepare: The first call to data_received may occur at any point after the call to prepare has returned or yielded.

Everything else¶

exception tornado.web.HTTPError(status_code, log_message=None, *args, **kwargs)[源代码]¶

An exception that will turn into an HTTP error response.

Raising an HTTPError is a convenient alternative to calling RequestHandler.send_error since it automatically ends the current function.

To customize the response sent with an HTTPError, override RequestHandler.write_error.

参数:

status_code (int) – HTTP status code. Must be listed in httplib.responses unless the reason keyword argument is given. log_message (string) – Message to be written to the log for this error (will not be shown to the user unless the Application is in debug mode). May contain %s-style placeholders, which will be filled in with remaining positional parameters. reason (string) – Keyword-only argument. The HTTP “reason” phrase to pass in the status line along with status_code. Normally determined automatically from status_code, but can be used to use a non-standard numeric code.

exception tornado.web.Finish[源代码]¶

An exception that ends the request without producing an error response.

When Finish is raised in a RequestHandler, the request will end (calling RequestHandler.finish if it hasn’t already been called), but the outgoing response will not be modified and the error-handling methods (including RequestHandler.write_error) will not be called.

This can be a more convenient way to implement custom error pages than overriding write_error (especially in library code):

if self.current_user is None:
    self.set_status(401)
    self.set_header('WWW-Authenticate', 'Basic realm="something"')
    raise Finish()

exception tornado.web.MissingArgumentError(arg_name)[源代码]¶

Exception raised by RequestHandler.get_argument.

This is a subclass of HTTPError, so if it is uncaught a 400 response code will be used instead of 500 (and a stack trace will not be logged).

3.1 新版功能.

class tornado.web.UIModule(handler)[源代码]¶

A re-usable, modular UI unit on a page.

UI modules often execute additional queries, and they can include additional CSS and JavaScript that will be included in the output page, which is automatically inserted on page render.

Subclasses of UIModule must override the render method.

render(*args, **kwargs)[源代码]¶

Override in subclasses to return this module’s output.

embedded_javascript()[源代码]¶

Override to return a JavaScript string to be embedded in the page.

javascript_files()[源代码]¶

Override to return a list of JavaScript files needed by this module.

If the return values are relative paths, they will be passed to RequestHandler.static_url; otherwise they will be used as-is.

embedded_css()[源代码]¶

Override to return a CSS string that will be embedded in the page.

css_files()[源代码]¶

Override to returns a list of CSS files required by this module.

If the return values are relative paths, they will be passed to RequestHandler.static_url; otherwise they will be used as-is.

html_head()[源代码]¶

Override to return an HTML string that will be put in the <head/> element.

html_body()[源代码]¶

Override to return an HTML string that will be put at the end of the <body/> element.

render_string(path, **kwargs)[源代码]¶

Renders a template and returns it as a string.

class tornado.web.ErrorHandler(application, request, **kwargs)[源代码]¶

Generates an error response with status_code for all requests.

class tornado.web.FallbackHandler(application, request, **kwargs)[源代码]¶

A RequestHandler that wraps another HTTP server callback.

The fallback is a callable object that accepts an HTTPServerRequest, such as an Application or tornado.wsgi.WSGIContainer. This is most useful to use both Tornado RequestHandlers and WSGI in the same server. Typical usage:

wsgi_app = tornado.wsgi.WSGIContainer(
    django.core.handlers.wsgi.WSGIHandler())
application = tornado.web.Application([
    (r"/foo", FooHandler),
    (r".*", FallbackHandler, dict(fallback=wsgi_app),
])

class tornado.web.RedirectHandler(application, request, **kwargs)[源代码]¶

Redirects the client to the given URL for all GET requests.

You should provide the keyword argument url to the handler, e.g.:

application = web.Application([
    (r"/oldpath", web.RedirectHandler, {"url": "/newpath"}),
])

class tornado.web.StaticFileHandler(application, request, **kwargs)[源代码]¶

A simple handler that can serve static content from a directory.

A StaticFileHandler is configured automatically if you pass the static_path keyword argument to Application. This handler can be customized with the static_url_prefix, static_handler_class, and static_handler_args settings.

To map an additional path to this handler for a static data directory you would add a line to your application like:

application = web.Application([
    (r"/content/(.*)", web.StaticFileHandler, {"path": "/var/www"}),
])

The handler constructor requires a path argument, which specifies the local root directory of the content to be served.

Note that a capture group in the regex is required to parse the value for the path argument to the get() method (different than the constructor argument above); see URLSpec for details.

To maximize the effectiveness of browser caching, this class supports versioned urls (by default using the argument ?v=). If a version is given, we instruct the browser to cache this file indefinitely. make_static_url (also available as RequestHandler.static_url) can be used to construct a versioned url.

This handler is intended primarily for use in development and light-duty file serving; for heavy traffic it will be more efficient to use a dedicated static file server (such as nginx or Apache). We support the HTTP Accept-Ranges mechanism to return partial content (because some browsers require this functionality to be present to seek in HTML5 audio or video), but this handler should not be used with files that are too large to fit comfortably in memory.

Subclassing notes

This class is designed to be extensible by subclassing, but because of the way static urls are generated with class methods rather than instance methods, the inheritance patterns are somewhat unusual. Be sure to use the @classmethod decorator when overriding a class method. Instance methods may use the attributes self.path self.absolute_path, and self.modified.

Subclasses should only override methods discussed in this section; overriding other methods is error-prone. Overriding StaticFileHandler.get is particularly problematic due to the tight coupling with compute_etag and other methods.

To change the way static urls are generated (e.g. to match the behavior of another server or CDN), override make_static_url, parse_url_path, get_cache_time, and/or get_version.

To replace all interaction with the filesystem (e.g. to serve static content from a database), override get_content, get_content_size, get_modified_time, get_absolute_path, and validate_absolute_path.

在 3.1 版更改: Many of the methods for subclasses were added in Tornado 3.1.

compute_etag()[源代码]¶

Sets the Etag header based on static url version.

This allows efficient If-None-Match checks against cached versions, and sends the correct Etag for a partial response (i.e. the same Etag as the full file).

3.1 新版功能.

set_headers()[源代码]¶

Sets the content and caching headers on the response.

3.1 新版功能.

should_return_304()[源代码]¶

Returns True if the headers indicate that we should return 304.

3.1 新版功能.

classmethod get_absolute_path(root, path)[源代码]¶

Returns the absolute location of path relative to root.

root is the path configured for this StaticFileHandler (in most cases the static_path Application setting).

This class method may be overridden in subclasses. By default it returns a filesystem path, but other strings may be used as long as they are unique and understood by the subclass’s overridden get_content.

3.1 新版功能.

validate_absolute_path(root, absolute_path)[源代码]¶

Validate and return the absolute path.

root is the configured path for the StaticFileHandler, and path is the result of get_absolute_path

This is an instance method called during request processing, so it may raise HTTPError or use methods like RequestHandler.redirect (return None after redirecting to halt further processing). This is where 404 errors for missing files are generated.

This method may modify the path before returning it, but note that any such modifications will not be understood by make_static_url.

In instance methods, this method’s result is available as self.absolute_path.

3.1 新版功能.

classmethod get_content(abspath, start=None, end=None)[源代码]¶

Retrieve the content of the requested resource which is located at the given absolute path.

This class method may be overridden by subclasses. Note that its signature is different from other overridable class methods (no settings argument); this is deliberate to ensure that abspath is able to stand on its own as a cache key.

This method should either return a byte string or an iterator of byte strings. The latter is preferred for large files as it helps reduce memory fragmentation.

3.1 新版功能.

classmethod get_content_version(abspath)[源代码]¶

Returns a version string for the resource at the given path.

This class method may be overridden by subclasses. The default implementation is a hash of the file’s contents.

3.1 新版功能.

get_content_size()[源代码]¶

Retrieve the total size of the resource at the given path.

This method may be overridden by subclasses.

3.1 新版功能.

在 4.0 版更改: This method is now always called, instead of only when partial results are requested.

get_modified_time()[源代码]¶

Returns the time that self.absolute_path was last modified.

May be overridden in subclasses. Should return a datetime object or None.

3.1 新版功能.

get_content_type()[源代码]¶

Returns the Content-Type header to be used for this request.

3.1 新版功能.

set_extra_headers(path)[源代码]¶

For subclass to add extra headers to the response

get_cache_time(path, modified, mime_type)[源代码]¶

Override to customize cache control behavior.

Return a positive number of seconds to make the result cacheable for that amount of time or 0 to mark resource as cacheable for an unspecified amount of time (subject to browser heuristics).

By default returns cache expiry of 10 years for resources requested with v argument.

classmethod make_static_url(settings, path, include_version=True)[源代码]¶

Constructs a versioned url for the given path.

This method may be overridden in subclasses (but note that it is a class method rather than an instance method). Subclasses are only required to implement the signature make_static_url(cls, settings, path); other keyword arguments may be passed through static_url but are not standard.

settings is the Application.settings dictionary. path is the static path being requested. The url returned should be relative to the current host.

include_version determines whether the generated URL should include the query string containing the version hash of the file corresponding to the given path.

parse_url_path(url_path)[源代码]¶

Converts a static URL path into a filesystem path.

url_path is the path component of the URL with static_url_prefix removed. The return value should be filesystem path relative to static_path.

This is the inverse of make_static_url.

classmethod get_version(settings, path)[源代码]¶

Generate the version string to be used in static URLs.

settings is the Application.settings dictionary and path is the relative location of the requested asset on the filesystem. The returned value should be a string, or None if no version could be determined.

在 3.1 版更改: This method was previously recommended for subclasses to override; get_content_version is now preferred as it allows the base class to handle caching of the result.

Syntax Reference¶

Template expressions are surrounded by double curly braces: {{ ... }}. The contents may be any python expression, which will be escaped according to the current autoescape setting and inserted into the output. Other template directives use {% %}. These tags may be escaped as {{! and {%! if you need to include a literal {{ or {% in the output.

To comment out a section so that it is omitted from the output, surround it with {# ... #}.

{% apply *function* %}...{% end %}

Applies a function to the output of all template code between apply and end:

{% apply linkify %}{{name}} said: {{message}}{% end %}

Note that as an implementation detail apply blocks are implemented as nested functions and thus may interact strangely with variables set via {% set %}, or the use of {% break %} or {% continue %} within loops.

{% autoescape *function* %}

Sets the autoescape mode for the current file. This does not affect other files, even those referenced by {% include %}. Note that autoescaping can also be configured globally, at the Application or Loader.:

{% autoescape xhtml_escape %}
{% autoescape None %}

{% block *name* %}...{% end %}

Indicates a named, replaceable block for use with {% extends %}. Blocks in the parent template will be replaced with the contents of the same-named block in a child template.:

<!-- base.html -->
<title>{% block title %}Default title{% end %}</title>

<!-- mypage.html -->
{% extends "base.html" %}
{% block title %}My page title{% end %}

{% comment ... %}

A comment which will be removed from the template output. Note that there is no {% end %} tag; the comment goes from the word comment to the closing %} tag.

{% extends *filename* %}

Inherit from another template. Templates that use extends should contain one or more block tags to replace content from the parent template. Anything in the child template not contained in a block tag will be ignored. For an example, see the {% block %} tag.

{% for *var* in *expr* %}...{% end %}

Same as the python for statement. {% break %} and {% continue %} may be used inside the loop.

{% from *x* import *y* %}

Same as the python import statement.

{% if *condition* %}...{% elif *condition* %}...{% else %}...{% end %}

Conditional statement - outputs the first section whose condition is true. (The elif and else sections are optional)

{% import *module* %}

Same as the python import statement.

{% include *filename* %}

Includes another template file. The included file can see all the local variables as if it were copied directly to the point of the include directive (the {% autoescape %} directive is an exception). Alternately, {% module Template(filename, **kwargs) %} may be used to include another template with an isolated namespace.

{% module *expr* %}

Renders a UIModule. The output of the UIModule is not escaped:

{% module Template("foo.html", arg=42) %}

UIModules are a feature of the tornado.web.RequestHandler class (and specifically its render method) and will not work when the template system is used on its own in other contexts.

{% raw *expr* %}

Outputs the result of the given expression without autoescaping.

{% set *x* = *y* %}

Sets a local variable.

{% try %}...{% except %}...{% else %}...{% finally %}...{% end %}

Same as the python try statement.

{% while *condition* %}... {% end %}

Same as the python while statement. {% break %} and {% continue %} may be used inside the loop.

相关类型¶

class tornado.template.Template(template_string, name="<string>", loader=None, compress_whitespace=None, autoescape="xhtml_escape")[源代码]¶

A compiled template.

We compile into Python from the given template_string. You can generate the template from variables with generate().

generate(**kwargs)[源代码]¶

Generate this template with the given arguments.

class tornado.template.BaseLoader(autoescape='xhtml_escape', namespace=None)[源代码]¶

Base class for template loaders.

You must use a template loader to use template constructs like {% extends %} and {% include %}. The loader caches all templates after they are loaded the first time.

autoescape must be either None or a string naming a function in the template namespace, such as “xhtml_escape”.

load(name, parent_path=None)[源代码]¶

Loads a template.

reset()[源代码]¶

Resets the cache of compiled templates.

resolve_path(name, parent_path=None)[源代码]¶

Converts a possibly-relative path to absolute (used internally).

class tornado.template.Loader(root_directory, **kwargs)[源代码]¶

A template loader that loads from a single root directory.

class tornado.template.DictLoader(dict, **kwargs)[源代码]¶

A template loader that loads from a dictionary.

exception tornado.template.ParseError[源代码]¶

Raised for template syntax errors.

编码函数¶

tornado.escape.xhtml_escape(value)[源代码]¶

Escapes a string so it is valid within HTML or XML.

Escapes the characters <, >, ", ', and &. When used in attribute values the escaped strings must be enclosed in quotes.

在 3.2 版更改: Added the single quote to the list of escaped characters.

tornado.escape.xhtml_unescape(value)[源代码]¶

Un-escapes an XML-escaped string.

tornado.escape.url_escape(value, plus=True)[源代码]¶

Returns a URL-encoded version of the given value.

If plus is true (the default), spaces will be represented as “+” instead of “%20”. This is appropriate for query strings but not for the path component of a URL. Note that this default is the reverse of Python’s urllib module.

3.1 新版功能: The plus argument

tornado.escape.url_unescape(value, encoding='utf-8', plus=True)[源代码]¶

Decodes the given value from a URL.

The argument may be either a byte or unicode string.

If encoding is None, the result will be a byte string. Otherwise, the result is a unicode string in the specified encoding.

If plus is true (the default), plus signs will be interpreted as spaces (literal plus signs must be represented as “%2B”). This is appropriate for query strings and form-encoded values but not for the path component of a URL. Note that this default is the reverse of Python’s urllib module.

3.1 新版功能: The plus argument

tornado.escape.json_encode(value)[源代码]¶

JSON-encodes the given Python object.

tornado.escape.json_decode(value)[源代码]¶

Returns Python objects for the given JSON string.

Byte/unicode 转换¶

这些函数在 Tornado 中广泛使用，但对于绝大多数其它应用来说不可直接使用。 注意：为了同时支持 Python 2 和 3，这些函数写得颇为错综复杂。

tornado.escape.utf8(value)[源代码]¶

Converts a string argument to a byte string.

If the argument is already a byte string or None, it is returned unchanged. Otherwise it must be a unicode string and is encoded as utf8.

tornado.escape.to_unicode(value)[源代码]¶

Converts a string argument to a unicode string.

If the argument is already a unicode string or None, it is returned unchanged. Otherwise it must be a byte string and is decoded as utf8.

tornado.escape.native_str()¶

将 byte 或者 unicode 类型的字符串转换为 str，相当于 Python 2 中的 utf8 和 Python 3 中的 to_unicode。

tornado.escape.to_basestring(value)[源代码]¶

Converts a string argument to a subclass of basestring.

In python2, byte and unicode strings are mostly interchangeable, so functions that deal with a user-supplied argument in combination with ascii string constants can use either and should return the type the user supplied. In python3, the two types are not interchangeable, so this method is needed to convert byte strings to unicode.

tornado.escape.recursive_unicode(obj)[源代码]¶

Walks a simple data structure, converting byte strings to unicode.

Supports lists, tuples, and dictionaries.

其它函数¶

tornado.escape.linkify(text, shorten=False, extra_params='', require_protocol=False, permitted_protocols=['http', 'https'])[源代码]¶

Converts plain text into HTML with links.

For example: linkify("Hello http://tornadoweb.org!") would return Hello <a href="http://tornadoweb.org">http://tornadoweb.org</a>!

Parameters:

• shorten: Long urls will be shortened for display.

• extra_params: Extra text to include in the link tag, or a callable

  taking the link as an argument and returning the extra text e.g. linkify(text, extra_params='rel="nofollow" class="external"'), or:

  def extra_params_cb(url):
      if url.startswith("http://example.com"):
          return 'class="internal"'
      else:
          return 'class="external" rel="nofollow"'
  linkify(text, extra_params=extra_params_cb)
  

• require_protocol: Only linkify urls which include a protocol. If

  this is False, urls such as www.facebook.com will also be linkified.

• permitted_protocols: List (or set) of protocols which should be

  linkified, e.g. linkify(text, permitted_protocols=["http", "ftp", "mailto"]). It is very unsafe to include protocols such as javascript.

tornado.escape.squeeze(value)[源代码]¶

Replace all sequences of whitespace chars with a single space.

Event handlers¶

WebSocketHandler.open(*args, **kwargs)[源代码]¶

Invoked when a new WebSocket is opened.

The arguments to open are extracted from the tornado.web.URLSpec regular expression, just like the arguments to tornado.web.RequestHandler.get.

WebSocketHandler.on_message(message)[源代码]¶

Handle incoming messages on the WebSocket

This method must be overridden.

WebSocketHandler.on_close()[源代码]¶

Invoked when the WebSocket is closed.

If the connection was closed cleanly and a status code or reason phrase was supplied, these values will be available as the attributes self.close_code and self.close_reason.

在 4.0 版更改: Added close_code and close_reason attributes.

WebSocketHandler.select_subprotocol(subprotocols)[源代码]¶

Invoked when a new WebSocket requests specific subprotocols.

subprotocols is a list of strings identifying the subprotocols proposed by the client. This method may be overridden to return one of those strings to select it, or None to not select a subprotocol. Failure to select a subprotocol does not automatically abort the connection, although clients may close the connection if none of their proposed subprotocols was selected.

Output¶

WebSocketHandler.write_message(message, binary=False)[源代码]¶

Sends the given message to the client of this Web Socket.

The message may be either a string or a dict (which will be encoded as json). If the binary argument is false, the message will be sent as utf8; in binary mode any byte string is allowed.

If the connection is already closed, raises WebSocketClosedError.

在 3.2 版更改: WebSocketClosedError was added (previously a closed connection would raise an AttributeError)

WebSocketHandler.close(code=None, reason=None)[源代码]¶

Closes this Web Socket.

Once the close handshake is successful the socket will be closed.

code may be a numeric status code, taken from the values defined in RFC 6455 section 7.4.1. reason may be a textual message about why the connection is closing. These values are made available to the client, but are not otherwise interpreted by the websocket protocol.

在 4.0 版更改: Added the code and reason arguments.

Configuration¶

WebSocketHandler.check_origin(origin)[源代码]¶

Override to enable support for allowing alternate origins.

The origin argument is the value of the Origin HTTP header, the url responsible for initiating this request. This method is not called for clients that do not send this header; such requests are always allowed (because all browsers that implement WebSockets support this header, and non-browser clients do not have the same cross-site security concerns).

Should return True to accept the request or False to reject it. By default, rejects all requests with an origin on a host other than this one.

This is a security protection against cross site scripting attacks on browsers, since WebSockets are allowed to bypass the usual same-origin policies and don’t use CORS headers.

To accept all cross-origin traffic (which was the default prior to Tornado 4.0), simply override this method to always return true:

def check_origin(self, origin):
    return True

To allow connections from any subdomain of your site, you might do something like:

def check_origin(self, origin):
    parsed_origin = urllib.parse.urlparse(origin)
    return parsed_origin.netloc.endswith(".mydomain.com")

4.0 新版功能.

WebSocketHandler.get_compression_options()[源代码]¶

Override to return compression options for the connection.

If this method returns None (the default), compression will be disabled. If it returns a dict (even an empty one), it will be enabled. The contents of the dict may be used to control the memory and CPU usage of the compression, but no such options are currently implemented.

4.1 新版功能.

WebSocketHandler.set_nodelay(value)[源代码]¶

Set the no-delay flag for this stream.

By default, small messages may be delayed and/or combined to minimize the number of packets sent. This can sometimes cause 200-500ms delays due to the interaction between Nagle’s algorithm and TCP delayed ACKs. To reduce this delay (at the expense of possibly increasing bandwidth usage), call self.set_nodelay(True) once the websocket connection is established.

See BaseIOStream.set_nodelay for additional details.

3.1 新版功能.

Other¶

WebSocketHandler.ping(data)[源代码]¶

Send ping frame to the remote end.

WebSocketHandler.on_pong(data)[源代码]¶

Invoked when the response to a ping frame is received.

exception tornado.websocket.WebSocketClosedError[源代码]¶

Raised by operations on a closed connection.

3.2 新版功能.

Client-side support¶

tornado.websocket.websocket_connect(url, io_loop=None, callback=None, connect_timeout=None, on_message_callback=None, compression_options=None)[源代码]¶

Client-side websocket support.

Takes a url and returns a Future whose result is a WebSocketClientConnection.

compression_options is interpreted in the same way as the return value of WebSocketHandler.get_compression_options.

The connection supports two styles of operation. In the coroutine style, the application typically calls read_message in a loop:

conn = yield websocket_connection(loop)
while True:
    msg = yield conn.read_message()
    if msg is None: break
    # Do something with msg

In the callback style, pass an on_message_callback to websocket_connect. In both styles, a message of None indicates that the connection has been closed.

在 3.2 版更改: Also accepts HTTPRequest objects in place of urls.

在 4.1 版更改: Added compression_options and on_message_callback. The io_loop argument is deprecated.

class tornado.websocket.WebSocketClientConnection(io_loop, request, on_message_callback=None, compression_options=None)[源代码]¶

WebSocket client connection.

This class should not be instantiated directly; use the websocket_connect function instead.

close(code=None, reason=None)[源代码]¶

Closes the websocket connection.

code and reason are documented under WebSocketHandler.close.

3.2 新版功能.

在 4.0 版更改: Added the code and reason arguments.

write_message(message, binary=False)[源代码]¶

Sends a message to the WebSocket server.

read_message(callback=None)[源代码]¶

Reads a message from the WebSocket server.

If on_message_callback was specified at WebSocket initialization, this function will never return messages

Returns a future whose result is the message, or None if the connection is closed. If a callback argument is given it will be called with the future when it is ready.