阻塞¶

一个函数通常在它等待返回值的时候被 阻塞 .一个函数被阻塞可能由于很多原因: 网络I/O,磁盘I/O,互斥锁等等.事实上, 每一个 函数都会被阻塞,只是时间会比较短而已, 当一个函数运行时并且占用CPU(举一个极端的例子来说明为什么CPU阻塞的时间必须考虑在内, 考虑以下密码散列函数像 bcrypt, 这个函数需要占据几百毫秒的CPU时间, 远远超过了通常对于网络和磁盘请求的时间).

一个函数可以在某些方面阻塞而在其他方面不阻塞.举例来说, tornado.httpclient 在默认设置下将阻塞与DNS解析,但是在其它网络请求时不会阻塞 (为了减轻这种影响,可以用 ThreadedResolver 或通过正确配置 libcurl 使用 tornado.curl_httpclient ). 在Tornado的上下文中我们通常讨论网络I/O上下文阻塞,虽然各种阻塞已经被最小化了.

异步¶

一个 异步 函数在它结束前就已经返回了,而且通常会在程序中触发一些动作然后在后台执行一些任务. (和正常的 同步 函数相比, 同步函数在返回之前做完了所有的事). 这里有几种类型的异步接口:

• 回调函数
• 返回一个占位符 (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

这时同样的函数但是被通过回调参数方式的异步方法重写了:

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 版本十分复杂, 但是 Futures 是 Tornado 中推荐使用的一种做法, 因为它有两个主要的优势. 错误处理时通过 Future.result 函数可以简单的抛出一个异常 (不同于某些传统的基于回调方式接口的 一对一的错误处理方式), 而且 Futures 对于携程兼容的很好. 协程将会在本篇的下一节 详细讨论. 这里有一个协程版本的实力函数, 这与传统的同步版本十分相似.

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 中是人为设定的, 因为生成器不允许又返回值. 为了克服这个问题, Tornado 协程抛出了一个叫做 Return 的特殊异常. 协程将会像返回一个值一样处理这个异常.在 Python 3.3+ 中, return response.body 将会达到同样的效果.

Python 3.5: async 和 await¶

Python 3.5 引入了 async 和 await 关键字 (使用了这些关键字的函数通常被叫做 “native coroutines” ). 从 Tornado 4.3 开始, 在协程基础上你可以使用这些来代替 yield. 简单的通过使用 async def foo() 来代替 @gen.coroutine 装饰器, 用 await 来代替 yield. 文档的剩余部分还是使用 yield 来兼容旧版本的 Python, 但是 async 和 await 在可用时将会运行的更快:

async def fetch_coroutine(url):
    http_client = AsyncHTTPClient()
    response = await http_client.fetch(url)
    return response.body

await 关键字并不像 yield 更加通用. 例如, 在一个基于 yield 的协程中你可以生成一个列表的 Futures, 但是在原生的协程中你必须给列表报装 tornado.gen.multi. 你也可以使用 tornado.gen.convert_yielded 将使用 yield 的任何东西转换成用 await 工作的形式.

虽然原生的协程不依赖于某种特定的框架 (例如. 它并没有使用像 tornado.gen.coroutine 或者 asyncio.coroutine 装饰器), 不是所有的协程都和其它程序兼容.这里有一个 协程运行器 在第一个协程被调用时进行选择, 然后被所有直接调用 await 的协程库共享. Tornado 协程运行器设计时就时多用途且可以接受任何框架的 awaitable 对象. 其它协程运行器可能会有更多的限制(例如, asyncio 协程运行器不能接收其它框架的协程). 由于这个原因, 我们推荐你使用 Tornado 的协程运行器来兼容任何框架的协程. 在 Tornado 协程运行器中调用一个已经用了asyncio协程运行器的协程,只需要用 tornado.platform.asyncio.to_asyncio_future 适配器.

他是如何工作的¶

一个含有 yield 的函数时一个 生成器 . 所有生成器都是异步的; 调用它时将会返回一个对象而不是将函数运行完成. @gen.coroutine 修饰器通过 yield 表达式通过产生一个 Future 对象和生成器进行通信.

这是一个协程装饰器内部循环的额简单版本:

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

装饰器从生成器接收一个 Future 对象, 等待 (非阻塞的) Future 完成, 然后 “解开” Future 将结果像 yield 语句一样返回给生成器. 大多数异步代码从不直接接触到 Future 类, 除非 Future 立即通过异步函数返回给 yield 表达式.

怎样调用协程¶

协程在一般情况下不抛出异常: 在 Future 被生成时将会把异常报装进来. 这意味着正确的调用协程十分的重要, 否则你可能忽略很多错误:

@gen.coroutine
def divide(x, y):
    return x / y

def bad_call():
    # This should raise a ZeroDivisionError, but it won't because
    # the coroutine is called incorrectly.
    divide(1, 0)

近乎所有情况中, 任何一个调用协程自身的函数必须时协程, 通过利用关键字 yield 来调用. 当你在覆盖了父类中的方法, 请查阅文档来判断协程是否被支持 ( 文档中应该写到那个方法 “可能是一个协程” 或者 “可能返回一个 Future”):

@gen.coroutine
def good_call():
    # yield will unwrap the Future returned by divide() and raise
    # the exception.
    yield divide(1, 0)

有时你并不想等待一个协程的返回值. 在这种情况下我们推荐你使用 IOLoop.spawn_callback, 这意味着 IOLoop 负责调用. 如果它失败了, IOLoop 会在日志中记录调用栈:

# The IOLoop will catch the exception and print a stack trace in
# the logs. Note that this doesn't look like a normal call, since
# we pass the function object to be called by the IOLoop.
IOLoop.current().spawn_callback(divide, 1, 0)

最后, 在程序的最顶层, 如果 `.IOLoop` 没有正在运行, 你可以启动 IOLoop, 运行协程, 然后通过

IOLoop.run_sync 方法来停止 IOLoop. 这通常被用来启动面向批处理程序的 main 函数:

# run_sync() doesn't take arguments, so we must wrap the
# call in a lambda.
IOLoop.current().run_sync(lambda: divide(1, 0))

协程模式¶

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

@gen.coroutine
def minute_loop():
    while True:
        yield do_something()
        yield gen.sleep(60)

# Coroutines that loop forever are generally started with
# spawn_callback().
IOLoop.current().spawn_callback(minute_loop)

@gen.coroutine
def minute_loop2():
    while True:
        nxt = gen.sleep(60)   # Start the clock.
        yield do_something()  # Run while the clock is ticking.
        yield nxt             # Wait for the timer to run out.

Application 对象¶

Application 对象用来负责全局的设置, 包括用来转发请求到控制器的路由表.

路由表是一系列 URLSpec 对象 (或元组), 其中的每一个包含 (至少) 一个正则表达式和一个控制器类. 是顺序相关的; 将会路由到第一个被匹配的规则. 如果正则表达式中有捕获组, 这些组会被当作 路径参数 而且会被传递到 控制器的 HTTP 方法中. 如果一个字典当作 URLSpec 被传递到第三个参数中时, 它将作为 初始参数 传递给 RequestHandler.initialize. 最后, URLSpec 可能会有一个名字 这样允许和 RequestHandler.reverse_url 一起使用.

例如, 根 URL / 被映射到 MainHandler 而且 /story/ 形式的后面跟着数字的 URLs 被映射到 StoryHandler. 这个数字 (作为一个字符串) 将会传递到 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")
    ])

Application 的构造方法可以通过关键字设定来开启一些可选的功能 ; 详见 Application.settings .

RequestHandler 子类¶

大多数 Tornado web 应用程序的工作都是在 RequestHandler 子类中完成的. 对于一个控制器子类来说主入口点被 get() 和 post() 等等这样的 HTTP 方法来控制着. 每一个控制器可能会定义一个或多个 HTTP 方法. 如上所述, 这些方法将会被匹配到相应 的路由组中并进行参数调用.

在控制器中, 像调用 RequestHandler.render 或者 RequestHandler.write 将会产生一个相应. render() 通过名字作为参数加载一个 Template . write() 将产生一个不使用模版的纯输出; 它接收字符串, 字节序列和字典 (dicts 将会转换成 JSON).

许多在 RequestHandler 中的方法被设计成为能够在子类中覆盖的方法以在整个应用程序中使用. 通常是定义一个 BaseHandler 类来覆盖像 write_error 和 get_current_user 然后继承时使用你的 BaseHandler 而不是 RequestHandler.

处理输入请求¶

处理输入请求时可以勇 self.request 来代表当前处理的请求. 详情请查看 HTTPServerRequest 的定义.

通过 HTML 表单形式的数据可以利用 get_query_argument 和 get_body_argument 等方法来转换成你需要的格式.

class MyFormHandler(tornado.web.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"))

由于 HTML 表单的编码不能区分参数是一个值还是一个列表, RequestHandler 可以明确的声明想要的是一个值还是一个列表. 对于列表来说, 使用 get_query_arguments 和 get_body_arguments 而不是它们的单数形式.

通过 self.request.files 可以实现文件上传, 它会映射名字 ( HTML 标签的名字 <input type="file"> 元素) 到每一个文件中. 每一个文件将会生成一个字典 {"filename":..., "content_type":..., "body":...}. files 对象只有再被某些属性报装后才是有效的 (例如. 一个 multipart/form-data 的 Content-Type); 如果没有使用这种方法 原始的文件上传数据将会在 self.request.body 中. 默认上传的文件是缓存在内存当中的; 如果你上传的文件很大, 不适合缓存在内存当中, 详见 stream_request_body 类修饰符.

由于 HTML 的编码形式十分古怪 (例如. 不区分单一参数还是列表参数), Tornado 不会试图去统一这些参数. 特别的, 我们不会解析 JSON 请求的请求体. 应用程序希望使用 JSON 在编码上代替 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 通常只保存成员变量传递的参数; 它将不会产生任何输出或者调用像 send_error 一样的方法.
3. prepare() 被调用. 这时基类在与子类共享中最有用的一个方法, 不论是否使用了 HTTP 方法 prepare 都将会被调用. prepare 可能会产生输出; 如果她调用了 finish (或者 redirect, 等等), 处理会在这终止.
4. HTTP方法将会被调用: get(), post(), put(), 等等. 如果 URL 正则表达式中包含匹配组, 它们将被传递当这些方法的参数中.
5. 当这些请求结束以后, 会调用 on_finish() . 对于同步处理来说调用会在 get() (等) 返回后立即执行; 对于异步处理来说这将会发生在调用 finish() 之后.

所有像这样可以被覆盖的方法都记录在 RequestHandler 的文档中. 其中一些最常用的覆盖方法有:

• write_error - 输出一个HTML的出错信息
• on_connection_close - 当与客户端断开时会被调用; 应用程序将会检查这种情况并且停止后续的处理. 要注意这里无法保证客户端断开时可以立刻被检测到.
• get_current_user - 详见 用户认证
• get_user_locale - 给当前用户返回一个 Locale 对象
• set_default_headers - 可以用来设置 在回应时的附加首部 (例如可以定制 Server 首部)

错误处理¶

如果一个控制器抛出了异常, Tornado 将会调用 RequestHandler.write_error 来生成一个错误页. tornado.web.HTTPError 可以用来生成一个指定的错误状态码; 其它异常时将会返回 500 .

在 debug 模式中默认的错误页中包含栈调用记录和一行的错误描述信息

(例如. “500: Internal Server Error”). 要生成一个个人定制的错误页, 覆盖

RequestHandler.write_error (可以声明在父类中用来修改所有的控制器).这种方式可以正常的通过像 write 和 render 一样的方法来处理输出. 如果错误时由于异常引起的, exc_info 将作为关键字参数传递到错误信息中 (注意: 这里无法确保发生的异常就是当时在 sys.exc_info 中的异常, 所以 write_error 必须使用例如像 traceback.format_exception 来代替 traceback.format_exc).

使用通常的处理方式来代替调用 write_error 也是可以的. 利用 set_status, 写入一个应答, 然后返回. 特殊异常 tornado.web.Finish 在简单的返回不可用的情况下可能在抛出时不会调用 write_error 函数.

对于 404 错误, 利用 default_handler_class Application设置. 处理器将会被覆盖 prepare 方法而不是某个具体的例如 get() HTTP 方法. 它将会产生一个用于描述信息的错误页: 抛出一个 HTTPError(404) 和覆盖 write_error, 或者调用 self.set_status(404) 在 prepare() 中直接生成.

重定向¶

在 Tornado 中重定向有两种重要的方式: RequestHandler.redirect 和利用 RedirectHandler.

你可以在 RequestHandler 中使用 self.redirect() 把用户重定向到其它地方. 可选参数 permanent 可以定义这个跳转是否时永久的. permanent 的默认值是 False, 它会产生一个 302 Found HTTP 状态码,适合用户在 POST 请求成功后的重定向. 如果 permanent 为真, 301 Moved Permanently HTTP 状态码将会被使用, 这将对于那些像跳转到正规 URL 页或者 SEO友好型的网页.

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 定义的一个持久跳转链接, 在 RedirectHandler 初始化参数中添加 permanent=False .

异步处理¶

Tornado 处理程序默认是同步的: 当 get()/post() 方法返回时, 结果将会被作为应答发送. 当运行的处理程序中所有请求都被阻塞时 , 任何需要长时间运行的处理程序应该被设计成异步的这样它们可以非阻塞的处理这一段程序.详情见 异步和非阻塞 I/O; 这部分主要针对 RequestHandler 子类中的异步技术.

使用异步处理程序的最简单方式是使用 coroutine 修饰符. 这将会允许你通过关键字 yield 生成一个 非阻塞 I/O, 当协程没有相应之前不会有信息被发出. 查看 协程 获取更多信息.

在某些时候, 协程可能不如一些基于回调的方式更方便, 在这些情况下 tornado.web.asynchronous 修饰符可以被取代. 这个修饰符通常不会自动发送应答; 相反请求将会被保持直到有些回调函数调用 RequestHandler.finish. 这取决于应用程序来保证方法是会被掉用的, 否则用户的请求将会被简单的挂起.

这是一个利用 Tornado 的内建 AsyncHTTPClient 来通过 FriendFeed API 发起调用的示例:

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

当 get() 返回时, 请求没有终止. 当 HTTP 客户端最终调用 on_response() 时, 请求依然是打开的, 当最终调用 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")

更高级的异步示例, 请查看 chat example application, 使用 长轮询(long polling). 实现的 AJAX 聊天室.用户如果想使用长轮询需要覆盖 on_connection_close() 来 在客户端结束后关闭链接 (注意查看方法文档中的警告).

设置模版¶

默认情况下, Tornado 会寻找在当前 .py 文件相同目录下的所关联的模版文件. 如果要将模版文件放到另外一个目录中, 使用 template_path 应用程序设置 (或者覆盖 RequestHandler.get_template_path 如果你在不同的处理程序中有不同的模版).

如果要从非文件系统路径加载模版, 在子类 tornado.template.BaseLoader 中配置设置 template_loader .

被编译过的模版默认时被缓存的; 要关闭缓存使得每次每次对于文件的改变都是可见的, 使用应用程序设置 compiled_template_cache=False 或者 debug=True.

模版语法¶

Tornado 模本文件仅仅是一个 HTML (或者其他基于文本的文件格式) 附加 Python 控制语句和内建的表达式:

<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"]
        self.render("template.html", title="My title", items=items)

Tornado 模版支持 控制语句 (control statements) 和 表达式 (expressions) . 控制语句被 {% and %} 包裹着, 例如., {% if len(items) > 2 %}. 表达式被 {{ 和 }} 围绕, 再例如., {{ items[0] }}.

模版中的控制语句多多少少与 Python 中的控制语句相映射. 我们支持 if, for, while, 和 try, 所有这些都包含在 {%  %} 之中. 我们也支持 模板继承 使用 extends 和 block 语句, 详见 tornado.template.

表达式可以时任何的 Python 表达式, 包括函数调用. 模版代码可以在以下对象和函数的命名空间中被执行. (注意这个列表可用在 RequestHandler.render 和 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.template 部分 (某些特性, 包括 UIModules 在 tornado.web 模块中描述)

在引擎下, Tornado 模版被直街翻译成 Python. 在你模版文件中的表达式将会被翻译成 Python 函数来代表原来的模版; 我们不在模版语言中阻止任何东西; 我们创造它的目的时为了提供更灵活的特性, 而不是有严格限制的模版系统. 因此, 如果你在你的模版文件中随意写入了表达式, 你再执行时将会得到相依随机的错误.

默认情况下, 所有模版文件的输出将会被 tornado.escape.xhtml_escape 方法转义. 这个设置可以通过给 Application 传递全局参数 autoescape=None 或者使用 tornado.template.Loader 构造器进行修改, 或者在模版文件中检测到 {% autoescape None %} , 或者简单的将 {{ ... }} 替换成 {% raw ...%} 的表达式. 此外, 可以在设置这些地方的转义函数为 None 已达到相同的效果.

注意, 尽管 Tornado’s 的自动转义在防止 XSS 漏洞上是有帮助的, 但是不能适用于所有的情况. 出现在适当位置的表达式, 例如 Javascript 或者 CSS, 可能需要额外的转义. 此外, 必须要额外注意使用在 HTML 中使用双括号和 xhtml_escape 中包含一些不可信的内容, 或者在属性中使用单独的转义函数 (查看示例. http://wonko.com/post/html-escaping)

国际化¶

目前用户的位置 (不论用户是否登陆) 在请求处理程序中的 self.locale 和 模版中的 locale 都是可用的. 位置的名字 (例如, en_US) 在 locale.name 中是可用的, 你也可以通过 Locale.translate 方法来翻译字符串. 模版中也有一个全局函数叫做 _() 用来翻译字符串. 翻译函数有两种形式:

_("翻译这段文字")

这将会根据用户的位置直接翻译, 还有:

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

可以根据第三个参数的数量来决定单复数形式. 在以上的例子中, 第一个翻译将会在 len(people) 是 1 时被激活, 在其它情况下会激活第二个翻译.

大多是翻译时利用 Python 中的变量占位符 ( 前面例子中的 %(num)d ) 占位符在翻译时可以被替换.

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

<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 来确定语言. 当我们不能找到默认的语言时我们使用 en_US 作为 Accept-Language 的值. 如果你希望用户自己设定自己的位置, 你可以通过修改默认选项 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 头部来确定.

tornado.locale 模块支持两种格式的翻译: 一种使用 getttext 和有关工具的 .mo 格式, 另一种时简单的 .csv 格式. 应用程序将会在启动时调用 tornado.locale.load_translations 或者 tornado.locale.load_gettext_translations; 查看这些支持格式方法来获取更详细的信息.

你可以通过调用方法 tornado.locale.get_supported_locales() 来查看支持的地理位置. 用户的位置将会基于它所在的最近位置. 例如, 用户的位置是 es_GT , es 是支持的, self.locale 对那个请求将会设置为 es . 但如果勋章寻找失败 en_US 将会作为默认设置.

UI 模版¶

Tornado 支持 UI 模版 为了更加简单的支持标准, 在你的程序中重用 UI 组件. UI 模块就像特殊的方法调用一样用来显示页面上的组件, 它们也可以被报装在 CSS 和 JavaScript 中.

例如, 如果你正在实现一个博客, 你想把博客的入口同时放置在主页和每一页的入口, 你可以定义一个 Entry 模块来实现它们. 首先, 创建一个 Python 模块当作一个 UI 模块, 例如 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)

在 ui_modules 设置中告诉 Tornado 使用 uimodules.py

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)

在一个模版中, 你可以利用 {% module %} 语句来调用一个模版. 例如, 你可以在 home.html 中调用 Entry 模块:

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

还有 entry.html 中:

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

模块可以通过覆盖包含定制的 CSS 和 JavaScript 方法 embedded_css, embedded_javascript, javascript_files , 或者 css_files 方法:

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)

CSS 和 JavaScript 模块只会被载入一次不论多少模块在页面中使用了它. CSS 总是被包含在页面的 <head> 标签中, 而且 JavaScript 也总是在页面底部的 </body> 之前.

当附加的 Python 代码不需要的时候, 模版文件自己可以是一个模块. 例如, 上面的例子可以在下面的 module-entry.html 中被重写:

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

这个被修改过的模块可以这样调用

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

set_resources 方法仅在模版通过 {% module Template(...) %} 调用有效. 不像 {% include ... %} 指令, 模版模块在模版容器中有一个不同的命名空间 - 它们只能看到全局模版的命名空间和自己的关键字参数.

Cookies 和 secure cookies¶

你可以使用 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!")

Cookies 是不安全的而且很容易被客户端修改. 如果你通过设置 cookies 来 识别当前登陆的用户, 你需要利用签名来防止 cookies 被伪造. Tornado 利用 set_secure_cookie 和 get_secure_cookie 方法来对 cookies签名. 为了使用这些方法, 你需要在创建应用程序时指定一个叫做 cookie_secret 的密匙. 你可以在应用程序的设置中通过传递参数来注册密匙:

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

对 cookies 签名后就有确定的编码后的值, 还有时间戳和一个 HMAC . 如果 cookes 过期或者签名不匹配, 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 的 secure cookies 保证完整性但不保证保密性. 就是说, cookie 将不会被修改, 但是它会让用户看到. cookie_secret 是一个对称密钥, 所以它必须被保护起来 – 任何一个人得到密钥的值就将会制造一个签名的 cookie.

默认情况下, Tornado 的 secure cookies 将会在 30 天后过期. 如果要修改这个值, 使用 expires_days 关键词参数传递给 set_secure_cookie 和 max_age_days 参数传递给 get_secure_cookie. 这两个值的传递是相互独立的, 你可能会在大多数情况下会使用一个 30 天内合法的密匙, 但是对某些敏感操作 (例如修改账单信息) 你可以使用一个较小的 max_age_days .

Tornado 也支持多个签名的密匙, 这样可以使用密匙轮换. 这样 cookie_secret 必须是一个具有整数作为密匙版本的字典. 当前正在使用的签名密匙版本必须在应用程序中被设置为 key_version 如果一个正确的密匙版本在 cookie 中被设置, 密匙字典中的其它密匙也可以被用来作为 cookie 的签名认证, 为了实现 cookie 的更新, 可以在 get_secure_cookie_key_version 中查询当前的密匙版本.

用户认证¶

当前通过认证的用户在请求处理器的 self.current_user 当中, 而且还存在于模版中的 current_user. 默认情况下, current_user 的值为 None.

为了在你的应用程序中实现用户认证, 你需要覆盖请求控制器中的 get_current_user() 方法 来确认怎样获取当前登陆的用户, 例如, 从 cookie 的值中获取该信息. 下面这个例子展示了通过用户的昵称来确定用户身份, 值被保存在 cookies 中:

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 装饰器 (decorator) tornado.web.authenticated 来获取登陆的用户. 如果你的方法被这个装饰器所修饰, 若是当前的用户没有登陆, 则用户会被重定向到 login_url (在应用程序设置中). 上面的例子也可以这样写:

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() , 而且可能对于非浏览器的登陆者是不适用的.

点击 Tornado Blog example application 来查看一个完整的用户认证程序 (将用户的数据保存在 MySQL 数据库中).

第三方认证¶

tornado.auth 模块既实现了认证, 而且还支持许多知名网站的认证协议, 这其中包括 Google/Gmail, Facebook, Twitter, 和 FriendFeed. 模块内包含了通过这些网站登陆用户的方法, 并在允许的情况下访问该网站的服务. 例如, 下载用户的地址薄或者在允许的情况下发布一条 Twitter 信息.

这里有一个 Google 身份认证的例子, 在 cookie 中保存 Google 的认证信息用来进行后续的操作:

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 模块文档.

跨站请求伪造防护¶

跨站请求伪造(Cross-site request forgery), XSRF, 是一个 web 应用程序要面临的常规问题 . 详见 Wikipedia 文章 查看关于 XSRF 的详细信息.

一个普遍被接受的防护 XSRF 做法是让每一个用户 cookie 都保存不可预测的值, 然后把那个值通过 form 额外的提交到你的站点. 如果 cookie 和 form 中提交的值不匹配, 那么请求很有可能是伪造的.

Tornado 内置有 XSRF 保护. 你需要在应用程序中设置 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)

如果设置了 xsrf_cookies , Tornado web 应用程序将会为每一个用户设置一个 _xsrf cookie 来拒绝所有与 _xsrf 的值不匹配的``POST``, PUT, 和 DELETE 请求. 如果你将此设置打开, 你必须给每个通过 POST 提交表单中添加这个字段. 你可以通过特殊的 UIModule xsrf_form_html() 来实现这些, 在模版中是可用的:

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

如果你提交一个 AJAX POST 请求, 你的每次请求需要在你的 JavaScript 中添加一个 _xsrf 的值. 这是一个我们在 FriendFeed 中用到的一个通过 AJAX POST 方法来自动添加 _xsrf 值的 jQuery 函数:

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 + ")"));
    }});
};

对于 PUT 和 DELETE 请求 (除了不像 POST 请求用到 form 编码参数), XSRF token 会通过 HTTP 首部中的 X-XSRFToken 字段来传输. XSRF cookie 在 xsrf_form_html 被使用时设置, 但是在一个非通常形式的 纯 JavaScript 应用程序中, 你可能需要手动设置 self.xsrf_token (仅通过读取这个属性就足以有效设置 cookie 了).

如果你需要对每一个基本的控制器自定义 XSRF 行为, 你一个覆盖 RequestHandler.check_xsrf_cookie(). 例如, 如果你有一个不是通过 cookie 来认证的 API, 你可能需要让 check_xsrf_cookie() 不做任何事来禁用 XSRF 的保护功能. 然而, 如果你既支持 cookie 认证又支持 非基于 cookie 的认证, 这样当前请求通过 cookie 认证的 XSRF 保护就会十分的重要.

进程和端口¶

由于 Python GIL (解释器全局锁), 为了更好利用多核 CPU 的性能, 将 Python 运行在多进程模式下就十分的重要. 通常最好是为每一个核心运行一个进程.

Tornado 包含一个内建的多进程模式来一次性启动. 这需要你在 main 函数做一些微小的改变:

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

这是启动多线程模式的最简单方式而且它们会共享同一个端口, 虽然它也有一些限制. 首先, 每一个子进程将会有一个自己的 IOLoop, 所以在 fork 之前你需要确保不能接触 全局的 IOLoop 实例 (甚至是间接的). 第二, 在这种模型中很难做到零宕机更新. 最后, 因为所有的进程都共享一个端口, 想要监控他们变得更难了.

对于更加复杂的部署, 建议启动独立的进程, 让每一个进程都拥有一个不同的端口. supervisord 的 “process groups” 特性是解 决整个问题的好方法之一. 当每一个进程使用不同的端口时需要一个外部的负载均衡器, 例如 HAProxy 或者 nginx, 它们将会把内部的每个端口给外部呈现为同一个地址.

运行在负载均衡器之后¶

当运行在像 nginx 这种负载均衡器后方, 我们建议给 HTTPServer 构造器中 传 xheaders=True 参数. 这将会告诉 Tornado 在头部使用 X-Real-IP 来获取用户的 IP 地址而不是认为所有流量都来自于负载均衡器的 IP 地址.

这时一份原始的 nginx 配置文件, 它和我们 FriendFeed 中用到的在结构上很相似. 假设 nginx 和 Tornado 服务器运行在同一个机器上, 四个 Tornado 服务分别运行在 端口 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;
        }
    }
}

静态文件和文件缓存¶

你可以在你的 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/ 开头).

在以上的设置中, 我们明确的设置了将静态文件 apple-touch-icon.png 在 StaticFileHandler 根目录下, 虽然物理上在静态文件夹中. (在正则 表达式的匹配组中必须告诉 StaticFileHandler 请求的文件名; 调用处理方法时会将匹配组传递过去.) 你可以通过同样的方法从网站的根目录 提供 sitemap.xml 文件. 当然, 你也可以通过使用适当的 HTML <link /> 标签来避免伪造根目录的 apple-touch-icon.png 文件.

为了提高性能, 可以讲一些静态文件缓存起来, 这样浏览器就不会发送一些 可能在渲染页面时阻塞的不必要的 If-Modified-Since 或者 Etag 请求. Tornado 支持使用 静态内容版本(static content versioning) 来解决这些问题.

为了使用这个特性, 在你的模版中使用 static_url 而不是在你的 HTML 文件中输入静态文件的 URL 地址来确定静态文件:

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

static_url() 方法将会把你的相对路径翻译成像 /static/images/logo.png?v=aae54 一样的绝对路径. v 参数时 logo.png 内容的散列, 它的存在使得 Tornado 向浏览器发送一个缓存头部, 这将会使得缓存 被无限期使用.

v 参数的值取决于文件的内容, 如果你更新了文件而且重启了服务器, v 的值将会被更新而且重新发送, 所以用户的浏览器将会自动的获取 新的文件. 如果文件没有改变, 浏览器将会继续使用原来缓存的文件而不 是再一次向服务器请求, 可以显著提高渲染性能.

在生产环境中, 你可能会想使用一些更好的静态文件服务器, 例如 nginx. 你可以在大多数 web 服务器上通过识别版本标签来使用 static_url() . 这里是我们在 FriendFeed 中使用的相关部分的 nginx 配置:

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

Debug 模式 和 自动重新加载¶

如果你在 Application 构造器中传递了 debug=True 参数, 你的应用将会运行在调试/开发模式下. 在这种模式下, 一些为了更方便开发的 特性将会被启用 (其中每一项都可以作为独立的标记使用; 如果两个都被设置了, 独立的标记将具有更高的优先级):

• autoreload=True: 应用程序将会监控源代码文件, 在改变时重新加载 这样减少了在开发过程中手动重启服务器的需要. 然而, 一些确定的错误 (例如, 在 import 时现语法错误) 还是会让服务器停止运行的, 而且这无法恢复.
• compiled_template_cache=False: 模版将不会被缓存.
• static_hash_cache=False: 静态文件散列 (通过使用 static_url 函数) 将不会被缓存
• serve_traceback=True: 当在 RequestHandler 中的异常没有被捕获时, 会产生一个错误页.

自动重新加载模式与 HTTPServer 的多进程模型不能兼容. 你不能在自动重新加载模式下给 HTTPServer.start 1 (或者调用 tornado.process.fork_processes) 以外的参数

调试模式的自动加载特性可以以 tornado.autoreload 运行在一个独立的模块中. 这两个可以结合使用, 在语法错误时可以提供额外的稳定性: 设置 autoreload=True 可以在运行时检测改变, 以 python -m tornado.autoreload myserver.py 启动将会在启动时捕捉语法错误和其它错误.

重新加载将会丢失 Python 解释器的命令行参数 (例如 -u) 因为它通过使用 sys.executable 和 sys.argv 重新运行了一遍 Python 程序. 此外, 改变这些变脸将会使重载错误.

在一些平台 (包括 Windows 和 Mac OSX 10.6 之前), 进程不能在原基础上更新, 所以当代码改变被检测到时, 旧的服务器关闭, 新的服务器开启. 这些操作将会使得某些集成开发环境失效.

WSGI 和 Google App Engine¶

Tornado 在 WSGI 容器以外通常是独立运行的. 然而, 在某些环境中 (像 Google App Engine), 只允许 WSGI, 其它方式将不能在它们的服务器上运行. 这种情况下 Tornado 支持一种被限制的模式, 这种模式下不支持一步操作, 在 WSGI-only 环境下 Tornado 只能使用其功能的一个子集. 这些在 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 应用程序上的所有特性.

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.

class WebDAVHandler(RequestHandler):
    SUPPORTED_METHODS = RequestHandler.SUPPORTED_METHODS + ('PROPFIND',)

    def propfind(self):
        pass

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, 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 模式 和 自动重新加载. 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 模式 和 自动重新加载. 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.
• key_version: Used by requestHandler set_secure_cookie to sign cookies with a specific key when cookie_secret is a key dictionary.
• 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.
• xsrf_cookie_kwargs: May be set to a dictionary of additional arguments to be passed to RequestHandler.set_cookie for the XSRF cookie.
• 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.
• template_whitespace: Controls handling of whitespace in templates; see tornado.template.filter_whitespace for allowed values. New in Tornado 4.3.

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.

Returns the HTTPServer object.

在 4.3 版更改: Now returns the HTTPServer object.

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 capturing groups in the regex will be passed in to the handler’s get/post/etc methods as arguments (by keyword if named, by position if unnamed. Named and unnamed capturing groups may may not be mixed in the same rule).
• 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.

在 4.3 版更改: Returning anything but None or a yieldable object from a method decorated with @asynchronous is an error. Such return values were previously ignored silently.

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=500, 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 error-handling methods (including RequestHandler.write_error) will not be called.

If Finish() was created with no arguments, the pending response will be sent as-is. If Finish() was given an argument, that argument will be passed to RequestHandler.finish().

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

在 4.3 版更改: Arguments passed to Finish() will be passed on to RequestHandler.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 serve a file like index.html automatically when a directory is requested, set static_handler_args=dict(default_filename="index.html") in your application settings, or add default_filename as an initializer argument for your StaticFileHandler.

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

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 {% %}.

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

These tags may be escaped as {{!, {%!, and {#! if you need to include a literal {{, {%, or {# in the output.

{% 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.

{% whitespace *mode* %}

Sets the whitespace mode for the remainder of the current file (or until the next {% whitespace %} directive). See filter_whitespace for available options. New in Tornado 4.3.

Class reference¶

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

A compiled template.

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

Construct a Template.

参数:

template_string (str) – the contents of the template file. name (str) – the filename from which the template was loaded (used for error message). loader (tornado.template.BaseLoader) – the BaseLoader responsible for this template, used to resolve {% include %} and {% extend %} directives. compress_whitespace (bool) – Deprecated since Tornado 4.3. Equivalent to whitespace="single" if true and whitespace="all" if false. autoescape (str) – The name of a function in the template namespace, or None to disable escaping by default. whitespace (str) – A string specifying treatment of whitespace; see filter_whitespace for options.

在 4.3 版更改: Added whitespace parameter; deprecated compress_whitespace.

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

Generate this template with the given arguments.

class tornado.template.BaseLoader(autoescape='xhtml_escape', namespace=None, whitespace=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.

Construct a template loader.

参数:

autoescape (str) – The name of a function in the template namespace, such as “xhtml_escape”, or None to disable autoescaping by default. namespace (dict) – A dictionary to be added to the default template namespace, or None. whitespace (str) – A string specifying default behavior for whitespace in templates; see filter_whitespace for options. Default is “single” for files ending in ”.html” and ”.js” and “all” for other files.

在 4.3 版更改: Added whitespace parameter.

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