¶

阻塞¶

一个函数在return之前，等待其他事情发生（其他代码执行）的过程，称其为 阻塞 状态。一个函数可能会因为很多原因而阻塞：网络I/O, 磁盘I/O, 以及锁等等。事实上，每一个 函数运行中并使用CPU的时候至少都会发生一点点阻塞现象（为了说明相对于其他种类的阻塞，为什么需要将CPU的阻塞进行认真对待，这里举一个极端的例子，如 bcrypt 这样的密码hash函数,会使用几百毫秒的CPU时间，远远超过典型的网络或硬盘访问时延。

一个函数可能在某些方面阻塞，而在其他方面却并不阻塞。比如，tornado.httpclient 类在默认的配置情况下，会在DNS解析上阻塞，而不会再其他的网络访问上阻塞（ 可以使用 ThreadedResolver 或者 基于正确配置的 libcurl 构建环境下的 tornado.curl_httpclient 类来减轻阻塞现象）。在Tornado中，我们通常讨论的是网络I/O上的阻塞，虽然各种情况的阻塞都应该被最小化。

异步¶

一个 异步 的函数会在它执行完成之后就先返回（Return），并且在触发一些即将发生的应用程序中的行为之前，通常会在后台进行一系列的工作（而对于正常的 同步 函数来说，任何工作都是在程序返回之前完成的）。 下面列举了几种不同的异步接口的开发方式：

• 回调参数（Callback argument）
• 返回一个占位符 (Future, Promise, Deferred)
• 传送到队列
• 回调注册表 (比如 POSIX 信号)

无论使用哪种的接口开发方式， 顾名思义 异步函数都需要与调用方有不同的交互；不可能在对调用方透明的情况下使一个同步的函数异步化。（ gevent 系统使用轻量级的线程模式，能够达到一个可以与异步系统媲美的性能，但它们实际上并没有进行任何异步化。）

例子¶

下面是一个同步函数的样例：

from tornado.httpclient import HTTPClient

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

而下面是一个用回调参数模式重写的异步函数的样例：

# 使用了内置的异步HTTP客户端
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)

再下面是使用占位符 Future 方式替代回调方式的样例：

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

原始的 Future 版本更为复杂，但是在Tornado中，使用 Futures 仍然是被推荐的做法，主要因为它有两个很重要的优势：错误处理方式不需要改变，你可以在 Future.result 方法中简单的抛出异常（而回调方式的接口开发需要有特殊的错误处理方式），并且 Futures 可以很方便的和协程配合使用。 协程将会在下一章节中深入讨论。 上述示例使用协程进行配合后，和原生的同步版本的函数看起来十分类似：（不过这里引入了yield迭代）

from tornado import gen

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

raise gen.Return(response.body) 语法在Python 2(以及3.2)版本中是神器，在这些版本中生成器是不允许有返回值的。 为了克服这个问题，Tornado的协程抛出了一个被成为 Return 的特殊种类的异常类。协程捕获这种异常，并且将它以返回值的方式处理。在Python 3.3以及更高版本中，可以直接通过 return response.body 的方式达到同样的效果（Python 3.3以及更高版本中支持在生成器中存在返回值）。

协程是如何工作的？¶

Python中包含关键字 yield 的函数被称为生成器。所有的生成器都是异步的；当调用生成器的时候，会返回一个生成器的对象，而不是一直运行到结束。@gen.coroutine 修饰器通过 yield 表达式与生成器进行交流，而且通过返回一个 Future 与协程的调用方进行交互。

下面是一个协程修饰器内部循环的简单版本示例:

# 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)

修饰器从生成器中接受到一个 Future 对象 ，然后等待（非阻塞的）这个 Future 对象 执行完成，然后“解开”这个 Future 对象并且将结果作为 yield 表达式的结果传回给生成器。 除了直接通过异步函数将这个 Future 对象回传给一个 yield 表达式以外，大多数的异步代码都不会接触到 这个 Future 对象 。

协程模式¶

@gen.coroutine
def call_task():
    # 注意，在some_function后面并没有括号。
    # 下面的语句将被 Task 翻译成 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 是一个与请求顺序相同的HTTPResponses列表

@gen.coroutine
def parallel_fetch_dict(urls):
    responses = yield {url: http_client.fetch(url)
                        for url in urls}
    # responses 是一个key为url，值为HTTPResponse的字典 {url: HTTPResponse}

@gen.coroutine
def get(self):
    # 将fetch_future存储，而不是直接 yield self.fetch_next_chunk()
    fetch_future = self.fetch_next_chunk()
    while True:
        # 在这里再 yield
        chunk = yield fetch_future
        if chunk is None: break
        self.write(chunk)
        fetch_future = self.fetch_next_chunk()
        yield self.flush()

# TODO:这段翻译的可能不准确

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()

Application 对象¶

Application 对象负责全局的配置，包括所有请求到句柄的路由映射表。

路由表是由一些 URLSpec 对象组成的列表（或元组），每个对象（至少）包含一个正则表达式和一个句柄类(RequestHandler类的子类)。按照顺序进行匹配，第一个匹配成功的规则将会被使用。如果某个正则表达式包含捕获组，这些捕获组将会成为 路径参数 并且会被传送给句柄类的HTTP方法。如果一个字典作为某个 URLSpec 对象的第三个元素，它将会作为 初始化参数 传递给 RequestHandler.initialize 方法。最后，URLSpec 对象可以进行命名，并且可以通过 RequestHandler.reverse_url 方法中使用到它。

举个例子：这下面的代码片段中，根地址URL / 被映射到 MainHandler 对象，并且映射 StoryHandler 对象的URL /story/ 中含有一个数字正则。对应的数字会被传给（作为字符串) StoryHandler.get 方法。

class MainHandler(RequestHandler):
    def get(self):
        # 通过查找 `.URLSpec` 对象名称story，找到对应的URL，并且传入参数1
        # 最后的URL为 "/story/1"
        self.write('<a href="%s">link to story 1</a>' %
                   self.reverse_url("story", "1"))


class StoryHandler(RequestHandler):
    # `.URLSpec` 对象 中传入的第三个字典参数直接传递给initialize方法
    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")
    ])

Application 类的构造函数包含了很多的关键字参数，使用这些关键字可以用来定制应用程序的行为以及开启可选功能。点击这里查看 Application.settings 类的完整列表。

RequestHandler 子类¶

一个Tornado的web应用的大部分功能都是在 RequestHandler 子类中完成的。 一个handler子类主要的入口点是一个正在被处理的HTTP方法：get(), post(), 等等。每一个handler可以定义多个方法来处理不同的HTTP行为。如上所述，路由表对应该子类的URL的捕获组（正则表达式）将作为参数传入到这些方法之中。

在一个handler之中，可以调用如 RequestHandler.render 或 RequestHandler.write 方法来生成一个response响应。 render() 方法通过加载一个命名的 Template 对象并通过传入的参数进行渲染。 write() 方法用来作为不使用模板时的基本输出，支持输入字符串、字节流或者字典（字典将会被编码成JSON格式）。

RequestHandler 类中的许多方法被设计成需要在子类中进行重写并贯彻整个应用。定义一个 BaseHandler 类并重写 如 write_error 和 get_current_user 这样的方法，然后使用重写过的``BaseHandler`` 代替 RequestHandler 作为所有自定义handler类的父类。

处理请求的输入¶

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.

# TODO: 这句不是很好理解 可以通过访问 self.request 查看当前对象的请求数据。可以查看 HTTPServerRequest 类的定义，了解完整的属性列表。

使用HTML forms形式的请求数据将会被解析，可以通过使用如 get_query_argument （get方法使用) 和 get_body_argument (post方法使用) 方法获取请求数据。

class MyFormHandler(RequestHandler):
    def get(self):
        # 通过get方法将得到一个html form，填写完成后点击submit将调用post方法
        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):
        # post方法中通过self.get_body_argument("message")来取得上面form中post的数据message
        self.set_header("Content-Type", "text/plain") # 设置header
        self.write("You wrote " + self.get_body_argument("message"))

由于HTML表单的提交的参数可能是一个单一值，也有可能是一个含有多个元素的列表， RequestHandler 对象提供了一个明确的方法来允许应用程序来判断是否使用单一值还是列表。如果是列表，请使用 get_query_arguments 和 get_body_arguments ，否则请使用 get_query_argument 和 get_body_argument 获取单一值。

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.

# TODO: 文件上传之前没有用过，实践之后再确认一些这段的翻译内容 通过表单上传的文件可以通过 self.request.files 进行访问，文件名（ HTML表单中 <input type="file"> 元素的名字） 映射成一个文件列表。每一个文件是一个像 {"filename":..., "content_type":..., "body":...} 这样的表单字典。 文件 对象必须通过包装(即Content-Type使用 multipart/form-data)才有效。如果不适用这种方式包装，原始的上传数据会存在于 self.request.body 。 默认情况下上传的文件在内存中完全进行缓存。如果你需要处理一些很大的文件，且不希望占用过多的系统内存，可以使用 stream_request_body 类修饰器。

由于HTML表单特别的编码方式（既，可能是单值也可能是多指的歧义问题），Tornado 没有尝试统一不同输入形式的表单参数。特别需要注意的是，Tornado并没有解析JSON格式的请求体(JSON request bodies)。使用JSON格式的应用程序（如REST API）可以重写 prepare 方法来解析请求。如下面所示：

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

重写RequestHandler方法¶

除了 get()/``post()``等方法，在 RequestHandler 类中还有其他的方法也允许在子类中进行重写。在每一次请求中，下面的一些列调用都会发生：

1. 在每一次请求中，一个新的 RequestHandler 对象都会被创建。
2. initialize() 会被优先调用，在 Application 里面配置的字典参数会作为该方法的输入参数。initialize 初始化操作通常只是将输入的参数传递该类对象的成员变量保存，而不应该产生任何的输出和方法调用。
3. 之后 prepare() 方法会被调用。 无论哪一个HTTP方法被使用， prepare 都会被调用，它是在所有自定义的子类中共享的最有用的方法。可以使用 prepare 方法产生输入；如果在该方法中调用了 finish （或者 redirect 等）方法，本次处理就会在这停止。
4. 接下来 get(), post(), put() 等HTTP方法将会被调用，如果URL的正则表达式包含了捕获组，将会将其作为参数传给对应的方法。
5. 当请求处理完成时， on_finish() 方法会被调用。对于同步的请求来说，在 get() (等)方法返回后会立刻执行；而对于异步请求，它会在调用 finish() 方法完成后才执行。

就像在 RequestHandler 文档中记录的那样，所有的方法都是被设计在子类重写的。一些最常用的重写方法包括：

• write_error - 用来在错误页面输出HTML代码。
• on_connection_close - 当客户端断开连接的时候会被调用；应用程序可以探测到这种情况并停止之后的处理过程；需要注意的是，一个关闭的连接并不能保证及时的被发现。
• get_current_user - 请查看 用户认证
• get_user_locale - 为当前的用户返回 Locale 对象
• set_default_headers - 可以用来在返回包中加入额外的headers（如用户自定义的 Server header）

错误处理¶

如果处理过程中抛出了一个异常，Tornado将会调用 RequestHandler.write_error 方法来生产一个错误页面。可以使用 tornado.web.HTTPError 方法来生成一个特殊状态码的异常；而所有的其他异常都会返回一个HTTP 500 错误。

默认的错误页在debug模式会包含一个stack trace以及一行错误描述（如，”500: Internal Server Error”）。如果想生成自定义的错误页，需要重写 RequestHandler.write_error 方法（可以写一个基类用于给其他子类共享）。 这个方法通常可以使用 write 和 render 方法产生输出。

# TODO: 这段暂时没理解

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).

# TODO: 这段理解的也不好

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.

也可以通过调用 set_status 设置状态码，写回相应数据，并且返回。用这样的方式来代替 write_error 方法来生成错误页。在简单的返回不方便的情况下，可以抛出 tornado.web.Finish 这个特殊的异常方法终止此次处理过程，而不再调用 write_error。

对于404错误来说，可以在 应用设置 中设置 默认的处理句柄类 - default_handler_class . 这个句柄类必须重写 prepare 方法，而不是像 get() 等更详细的方法，这样它会在所有的HTTP 方法中都生效。 所以，像上面所说的，产生错误页面有两种方式：或者通过抛出一个 HTTPError(404) 异常并且重写 write_error 方法，或者调用 self.set_status(404) 方法并且在 prepare() 方法中直接产生返回数据（使用``self.write``）。

重定向¶

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

在Tornado中有两种主要的方式来进行重定向请求： RequestHandler.redirect 方法和 使用 RedirectHandler.

可以在一个 RequestHandler 方法中使用 self.redirect() 将用户重定向到别处。此外，还有一个可选的参数

`` permanent`` ，你可以用它来表明重定向是永久性的。 permanent 参数的默认值是 False ，生成一个 302 Found 的HTTP响应码，它比较适用于在用户 POST 请求成功后进行重定向之类的需求。如果 permanent 设置成 True ,将会生成 301 Moved Permanently 的HTTP响应码，某些情况下也是很有用的，比如使用搜索引擎友好的方式下将一个页面重定向到权威地址。

RedirectHandler 类允许直接在 Application 路由表中进行重定向配置。下面的例子展示了如何配置一个单向的静态重定向：

app = tornado.web.Application([

url(r”/app”, tornado.web.RedirectHandler,

dict(url=”http://itunes.apple.com/my-app-id”)),

])

RedirectHandler 也支持正则表达式替换。下面的规则将所有 /pictures/ 开头的请求重定向到 /photos/

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

与 RequestHandler.redirect 不同的是， RedirectHandler 默认使用永久重定向。这是因为路由表不会在程序运行时改变，所以认为是永久性的，然而重定向也有可能是请求中其他逻辑改变的结果。 使用 RedirectHandler 时将 permanent=False 加到 RedirectHandler 的初始化参数中就可以产生一个临时的重定向了。

异步请求¶

Tornado的请求默认是同步的：当 get()/post() 方法返回的时候，请求被认为已经结束并且答复已经发出。由于在一个请求运行的时候，所有其他的请求都会被阻塞，因此长时间运行的请求应该异步化，以便于使用非阻塞的方式调用较慢的请求。在 异步非阻塞I/O 中进行了更详细的阐述；这部分是对 RequestHandler 子类中异步技术细节的相关说明。

使一个请求异步化的最简单的方式是使用 coroutine 修饰器，它允许你使用 yield 关键字生成非阻塞I/O，并且在协程返回之前，不会有响应被发送。 查看 协程 文档查看更详细的资料。

在某些场景下，相比于回调为主导的方式，协程可能更不方便，在这种情况下，可以使用 tornado.web.asynchronous 修饰器来替代。当这个修饰器被使用的时候，响应不会自动的发送；相反请求会保持开放状态，直到某些回调函数调用了 RequestHandler.finish 方法。要确认在应用程序中调用了该方法，否则用户的浏览器会被hang住。

下面是一个使用Tornado的内置的异步HTTP客户端 AsyncHTTPClient 调用 FriendFeed API的例子:

class MainHandler(tornado.web.RequestHandler):
    # 使用@tornado.web.asynchronous异步修饰器
    @tornado.web.asynchronous
    def get(self):
        http = tornado.httpclient.AsyncHTTPClient()
        # 使用回调方式，http请求结束后，将结果作为参赛回调callback方法，既self.on_response
        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)
        # Tornado中内置json解码函数，不需要使用json包
        json = tornado.escape.json_decode(response.body)
        self.write("Fetched " + str(len(json["entries"])) + " entries "
                   "from the FriendFeed API")
        self.finish()

当 get() 方法返回的时候，本次请求还没有结束。当HTTP客户端最终调用 on_response() 方法的时候，本次请求仍然处于开放状态，最后调用 self.finish() 方法将响应结果刷到客户端。

为了便于比较，这里是一个使用协程相同的例子(貌似这个看起来还是更简单）:

class MainHandler(tornado.web.RequestHandler):
    # 这里使用协程修饰器
    @tornado.gen.coroutine
    def get(self):
        http = tornado.httpclient.AsyncHTTPClient()
        # 使用yield而不是用回调
        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")

对于更高级的异步例子，可以查看 聊天应用例子 ，它使用 long polling 实现了一个AJAX的聊天室。 长轮询的用户可能需要去重写 on_connection_close() 方法在客户端关闭连接之后后来清理现场。（请注意查看该方法文档中的警告事项）

配置模板¶

默认情况下，Tornado会在当前被引用的 .py 文件所在的相同目录寻找模板文件。可以在 Application setting 中设置 template_path 参数来让Tornado到设定的目录中寻找模板文件（如果你为不同的处理句柄设置不同的模板文件目录的化，可以通过重写 RequestHandler.get_template_path 方法来解决）。

#TODO: 这段需要再理解一下 To load templates from a non-filesystem location, subclass tornado.template.BaseLoader and pass an instance as the template_loader application setting.

如果要在一个非文件系统的位置加载模板，需要写一个 tornado.template.BaseLoader 的子类，并且在应用配置中设置 template_loader 参数的值为该子类的实例。

默认情况下编译完成后的模板将会被缓存；可以通过在应用设置（application settings）中设置参数 compiled_template_cache=False 或 debug=True 来关闭缓存，这样每次模板被更改后都会自动加载。

模板语法¶

一个Tornado的模板其实就是将Python的控制序列和表达式嵌入标记内的HTML文件（或者任何其他基于文本的格式）:

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

如果你将这个模板文件保存为： “template.html” ，并且将其放在你的Python文件的相同目录内，你就可以用下面的方式进行模板渲染了:

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        items = ["Item 1", "Item 2", "Item 3"]
        # title,items分别是上面的template.html模板中的变量。
        self.render("template.html", title="My title", items=items)

Tornado的模板支持 控制语句 和 表达式 。控制语句使用 {% and %} 环绕，例如: {% if len(items) > 2 %} 。表达式使用 {{ 和 }} 来环绕, 比如: {{ items[0] }} 。

控制语句大致与Python语句类似。它支持 if, for, while, 和 try ，并且都必须使用 {% end %} 标志来结束。它也可以使用 extends 和 block 标签来实现 模板继承 ，这些都在 tornado.template 文档中有详细的介绍。

表达式可也是任意的Python表达式，包括函数调用。模板中的代码会被执行在一个包括羡慕的对象和功能的命名空间中（需要注意的是：这些列出用来进行模板渲染的条目适用于在使用 RequestHandler.render 和 RequestHandler render_string 的时候。如果你直接在 RequestHandler 外使用 tornado.template 模块，这些条目很多都是不存在的）。

• escape: tornado.escape.xhtml_escape 的别名
• xhtml_escape: tornado.escape.xhtml_escape 的别名
• url_escape: tornado.escape.url_escape 的别名
• json_encode: tornado.escape.json_encode 的别名
• squeeze: tornado.escape.squeeze 的别名
• linkify: tornado.escape.linkify
• datetime: Python 的 datetime 模块
• handler: 当前的 RequestHandler 对象
• request: handler.request 的别名
• current_user: handler.current_user 的别名
• locale: handler.locale 的别名
• _: handler.locale.translate 的别名
• static_url: handler.static_url 的别名
• xsrf_form_html: handler.xsrf_form_html 的别名
• reverse_url: Application.reverse_url 的别名
• 所有来自`` ui_methods``项和` ` ui_modules`` 的 `` Application``设置
• 所有传给 render 或 render_string 方法的关键字

当你使用Tornado创建一个真正的应用的时候，你会想去使用Tornado模板的全部功能，尤其是模板继承。 可以阅读 tornado.template 章节来了解详细的功能（包括 UIModules 的一些功能是在 tornado.web 模块中实现的）。

在引擎之中，Tornado的模板会被直接翻译成Python代码。在模板中的你所引入的表达式会一字不差的复制成一个Python函数来代替你的模板。在模板语言中，我们不会有任何限制；我们意在创造一个灵活的模板系统，而不是一个有各种限制的模板系统。因此，如果你在模板的表达式中随便写各种代码，当你执行模板的时候就会产生各种各样的错误了。

默认情况下，所有的模板输出的时候都会使用 tornado.escape.xhtml_escape 函数加密。这个行为可以通过传递 autoescape=None 给 Application 设置或者 tornado.template.Loader 的构造函数来关闭，也可以使用 {% autoescape None %} 命令仅在某个模板文件中关闭该功能，或者使用 {% raw ...%} 替换 {{ ... }} 从而在某个单独的表达式中关闭该功能。

#TODO:最后一句理解的不好 需要注意，虽然Tornado自动的模板加密有助于避免 XSS 漏洞，然而并不能解决所有的情况。出现在特定的位置的表达式，可能需要额外的转义，例如在Javascript或CSS里。此外，还有其他几点务必要注意：要一直使用双引号、在HTML属性中的 xhtml_escape 可能包含其他未信任的内容，还有一个单独的escaping 函数必须被attributes 使用。（点击 http://wonko.com/post/html-escaping 查看详细内容）。

国际化¶

当前用户的语言环境（无论用户是否登录）总是可用的，比如在请求handler中使用 self.locale 或在模板中使用 locale 。语言的名字（比如 en_US ）可以使用 locale.name 获取，并且你可以使用 Locale.translate 方法来翻译字符串。 模板中也有全局的函数 _() 用来进行字符串翻译。翻译函数有两种形式:

_("Translate this string")

这种是基于当前的语言环境直接翻译字符串内容，以及:

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

这种翻译字符串内容的方式是基于第三个参数来确定是单数还是复数形式。在上面的例子中，如果 len(people) 的结果是 1 ，就会按照第一个字符串翻译；如果是 len(people) 的值是复数则会按照第二个字符串翻译。

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.

这是一个正确的国际化的模板:

<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>

默认情况下我们会通过用户浏览器发送的 Accept-Language header信息获取用户的语言环境。如果无法获得合适的 Accept-Language 值，会默认使用 en_US 。如果想让用户自己设置偏好的语言环境，你可以通过重写 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"]

如果 get_user_locale 函数返回了 None 值，我们会重新查询 Accept-Language header的值。

#TODO:这段后续再修复一下 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..

#TODO:最后那句是看源码么？ tornado.locale 模板支持两种形式的文件来加载翻译： .mo 模式可以通过 gettext 和相关的工具来使用，以及一个简单的 .csv 格式。通常情况下应用会在启动的时候调用一次 tornado.locale.load_translations 或者 tornado.locale.load_gettext_translations 方法中的一个。 可以查看这些方法以便获取更多支持格式的细节...（see those methods for more details on the supported formats.. ）

你可以在应用中使用 tornado.locale.get_supported_locales() 函数获取所支持的语言环境列表。用户的语言环境会被选择成最接近支持的语言环境中的一个。比如，如果用户的语言环境是 es_GT ，并且 es 这个语言环境是支持的，那么 self.locale 将会使用 es 作为当前语言环境去处理请求。如果没有较接近的语言环境被匹配，则会使用 en_US 作为默认的语言环境。

UI 模块¶

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和安全cookie¶

你可以使用 set_cookie 方法在用户的浏览器中设置cookies:

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!")

Cookie是不安全的，可能很容易被客户端修改。如果你需要去设置cookies，比如认证当前的登陆用户，你需要去签名你的cookies以防止伪造。Tornado支持使用 set_secure_cookie 和 get_secure_cookie 方法签名cookies。使用这些方法，在创建应用的时候，需要指定一个叫做 cookie_secret 的私钥，并将该参数传递给application的配置。

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

被签名的cookies包含cookie的编码值以及一个时间戳和一个 HMAC 签名。如果cookie太旧或者签名不匹配的话， get_secure_cookie 函数将会返回一个 None 值，就像cookie并没有设置一样。安全版本的代码示例如下所示:

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的安全cookies保证了完整性，但无法保证保密性。这是因为，cookie不能被修改但是内容确实可以被用户查看的。私钥 cookie_secret 是一个对称的key，并且必须秘密保存，任何获取了该key值的人都可以伪造出自己的签名cookies。

默认情况下，Tornado的安全cookies在30天后过期。不过可以在 set_secure_cookie 方法中设置 expires_days 参数来改变cookies的过期时间，同时设置 get_secure_cookie 方法的 max_age_days 参数也可以达到类似的效果。这两个参数可以配合使用，比如在大部分需求中使用 expires_days 参数设置过期为30天，但是在一些敏感的行为（例如更改账户信息）中使用 max_age_days 参数得到一个更短的过期时间。

用户认证¶

在每个请求handler中，都可以通过使用 self.current_user 方法获得当前的登录用户，在模板中使用 current_user 变量获取。默认情况下， current_user 值是 None。

在应用中实现用户登录，你需要在请求句柄中重写 get_current_user() 方法来查明用户是否登录，例如使用cookie。下面是一个例子，用户通过输入一个简单的昵称登录，并将其保存在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__")

可以要求用户登录的时候使用 Python 修饰器 tornado.web.authenticated 。如果某个方法使用了这个修饰器，而用户处于未登录状态，将会被重定向到 login_url （另外一个application setting的配置）。上面的例子可以重写成这样:

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)

如果在 post() 方法上使用 authenticated 修饰器，并且用户没有登录的化，服务器会返回一个 403 响应。 @authenticated 修饰器可以简单理解成： if not self.current_user: self.redirect() 并且它并不适合非基于浏览器登录的方案（比如单独作为后端API）。

点击 Tornado Blog example application 来查看一个用户登录的完整示例（并将用户信息存储在MySQL数据库中）。

第三方认证¶

tornado.auth 模块为一些最受欢迎的网站实现了认证和认证协议，包括：Google/Gmail, Facebook, Twitter, 和 FriendFeed。模板包含用于登录这些网站的方法，在哪里适合使用，认证权限的方法，所以你可以做一些事情比如：下载一个用户的地址列表或者代表用户在Twitter上发一条消息。

这是一个使用Google认证的例子，在例子中将Google credentials保存在cookie中以便之后的验证:

class GoogleOAuth2LoginHandler(tornado.web.RequestHandler,
                               tornado.auth.GoogleOAuth2Mixin):
    @tornado.gen.coroutine
    def get(self):
        if self.get_argument('code', False):
            user = yield self.get_authenticated_user(
                redirect_uri='http://your.site.com/auth/google',
                code=self.get_argument('code'))
            # Save the user with e.g. set_secure_cookie
        else:
            yield self.authorize_redirect(
                redirect_uri='http://your.site.com/auth/google',
                client_id=self.settings['google_oauth']['key'],
                scope=['profile', 'email'],
                response_type='code',
                extra_params={'approval_prompt': 'auto'})

查看 tornado.auth 的模板文档，了解更多详细信息。

跨站请求伪造¶

#TODO:这部分之后再翻译 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.

使用负载均衡程序¶

当使用一个负载均衡器的时候（如nginx），建议将 xheaders=True 传给 HTTPServer 的构造函数。这样将会告知Tornado使用如 X-Real-IP 的 HTTP headers来获取真实的用户IP地址，而不是认为所有的流量来源都是负载均衡器的IP地址。

这是一个原始的nginx配置文件的结构是类似的 一个在FriendFeed使用我们

下面的这个原始的nginx的配置文件，结构与我们在FriendFeed使用的一个配置很相似。假定nginx和Tornado servers运行在相同的服务器上，并且运行4个Tornado servers，分别监听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 {
    # 在upstream中列出所有的tornado server,当然如果你要做不同的路由跳转的时候可以定义多个upstream
    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;
        }
    }
}

静态文件和频繁访问文件的缓存¶

在Tornado中你可以通过在应用配置中指定 static_path 来提供静态文件服务:

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)

这种配置将会自动的将所有以 /static/ 开头的请求从设置的静态目录进行提供，例如： http://localhost:8888/static/foo.png 将会从指定的静态目录提供 foo.png 文件。我们也会自动的使用该静态目录提供 /robots.txt 和 /favicon.ico 文件（及时他们并不是 /static/ 为前缀的请求）

上面的配置中，我们已经明确的配置Tornado使用 StaticFileHandler 句柄来提供根目录下的 apple-touch-icon.png 文件，尽管它的物理位置是处于静态文件目录里。（在正则表达式中的捕获组必须要被请求的文件名告知 StaticFileHandler 句柄；记住捕获组是作为方法参数传递给处理句柄的。）你可以按照类似的方式来提供一个根目录下 sitemap.xml 的文件请求。当然，你也可以通过在HTML中使用合适的 <link /> 标签来避免伪造根目录的 apple-touch-icon.png 文件。（就是说可以通过/static/apple-touch-icon.png 路径来访问，而不是用/apple-touch-icon.png 路径）

为了提高性能，让浏览器主动缓存静态资源通常是一个好主意，这样浏览器就不需要再发送不必要的 If-Modified-Since 或者 Etag 请求（可能阻塞住页面渲染）。Tornado通过使用 静态内容版本 来支持这个功能。

使用这个功能，需要在你的模板文件中使用 static_url 方法，而不是直接输入静态文件的URL。

<html>

<head>

<title>FriendFeed - {{ _(“Home”) }}</title>

</head> <body>

<div><img src=”{{ static_url(“images/logo.png”) }}”/></div>

</body>

</html>

static_url() 函数会将相对路径转换成一个URI，例如： /static/images/logo.png?v=aae54 。参数 v 的值是文件 logo.png 内容的hash值，并且它的存在使得Tornado服务器将缓存headers发送到用户的浏览器，浏览器将会永久性的缓存相关内容。

由于参数 v 的值是基于文件内容，如果你更新了文件并且重启了服务器，它将发送一个新的 v 值，这样用户的浏览器将会自动获取新的文件。如果文件的内容没有改变，浏览器将会继续使用本地缓存的副本，而不会检查服务器端的更新，从而显著的提高渲染性能。

在生产过程中，你可能想要使用一个更优化的静态文件服务器提供静态文件服务，比如 nginx 。你可以配置几乎所有的Web服务器使用 static_url() 去识别版本标签，从而设置缓存响应headers。下面是一个我们在FriendFeed中使用的相关nginx配置片段：

location /static/ {

root /var/friendfeed/static; if ($query_string) {

expires max;

}

}

调试模式和自动重载¶

如果将 debug=True 传给 Application 的构造函数，应用将会以 调试/开发 模式运行。在这种模式下，为了方便，一些功能 将会启用（其中的每一个都可作为一个单独的标志；如果两者都指定了，单独的标志优先）:

• autoreload=True: 应用将会观察源代码文件的变化，并且在它被改变的时候进行重载。在开发中将会减少很多手动重启服务器的次数。然后，需要注意如果在调试模式中进行代码更新的时候出现确切的错误（例如在import的时候发现语法错误），服务器将会宕机并且无法自动恢复。
• compiled_template_cache=False: 模板不会被缓存。
• static_hash_cache=False: 静态文件哈希表(使用的 static_url 函数)不会被缓存
• serve_traceback=True: 当一个异常在一个 RequestHandler 句柄中没有被捕获的时候，一个包含堆栈跟踪过程的错误页面将会生成。

#TODO:要了解代码架构后再来翻译这段 autoreload模式在 HTTPServer 使用多进程模式的情况下不兼容。 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.

#TODO:需要了解一下autoreload的原理 调试模式下的自动重载功能在 tornado.autoreload 可作为一个独立的模块使用。这两种方式可以相互配合来实现额外的稳定性来处理出现语法错误情况下的重载。在应用运行的时候，设置 autoreload=True 来探测代码改变，并且使用 python -m tornado.autoreload myserver.py 命令开启服务程序来启动时捕获任何语法或者其他错误。

#TODO:最后一句的理解，以及Python解释器参数的了解 重载过程会丢失所有的Python解释器的命令参数（比如 -u) ,因为它使用 sys.executable 和 sys.argv 来重新执行Python程序。此外，修改这些变量？将引起重载行为异常。 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.

在一些平台上（包括Windows 以及 Mac OSX 10.6之前的版本），程序不能被”原地”更新，所以当代码发生改变的时候，旧进程会停止退出，并启动一个新的进程。这种方式将会使某些IDE产生困惑。

WSGI 和 Google App Engine¶

Tornado通常使用内部的HTTP Server运行，而不是使用一个WSGI容器。然而，在某些环境中（比如Google App Engine),只有WSGI方式是允许的，并且应用不能运行自己的server。在这种情况下，Tornado提供了一个限制模式，这个模式不支持异步操作，但是却允许大部分功能在仅支持WSGI的运行环境中运行。在WSGI模式下不支持的功能有：协程， @asynchronous 修饰器，AsyncHTTPClient 异步客户端， auth 认证模块以及WebSockets。

你可以使用 tornado.wsgi.WSGIAdapter 来将一个 Tornado Application 转换成一个WSGI应用。在下面的例子中说明了如何配置你们的WSGI容器来找到应用 application 对象：

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)

查看 appengine example application 来了解使用Tornado构建一个完整功能的AppEngine应用。

线程安全注意事项¶

通常来说， Tornado中，在 RequestHandler 类里（还有其他位置）方法都不是线程安全的。特别是如： write(), finish(), 和 flush() 这几个方法只能在主线程中调用。如果你使用了多线程模式运行，就必须在请求结束前使用 IOLoop.add_callback 将控制权交给主线程。

处理句柄类¶

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

Subclass this class and define get() or post() to make a handler. 编写该类的子类，并且定义 get() 或 post() 方法来处理请求。

如果你想要支持不在标准的 GET/HEAD/POST 中的更多HTTP方法，你需要在你的 RequestHandler 子类中重写 SUPPORTED_METHODS 变量。

目前 RequestHandler 父类中 SUPPORTED_METHODS 变量支持：”GET”, “HEAD”, “POST”, “DELETE”, “PATCH”, “PUT”, “OPTIONS” 这几个方法。

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 调试模式和自动重载. 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 调试模式和自动重载. 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 模块 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, 跨站请求伪造 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:

class MyRequestHandler(RequestHandler):
    @asynchronous
    def get(self):
       http = httpclient.AsyncHTTPClient()
       http.fetch("http://friendfeed.com/", self._on_download)

    def _on_download(self, response):
       self.write("Downloaded!")
       self.finish()

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 reference¶

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.

Escaping functions¶

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 conversions¶

These functions are used extensively within Tornado itself, but should not be directly needed by most applications. Note that much of the complexity of these functions comes from the fact that Tornado supports both Python 2 and Python 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()¶

Converts a byte or unicode string into type str. Equivalent to utf8 on Python 2 and to_unicode on Python 3.

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.

Miscellaneous functions¶

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.