Skip to main content

tornado.webRequestHandlerApplication

tornado.web 提供了一个带有异步特性的简单Web框架,允许它扩展到大量的开放连接,使其成为 长轮询 的理想选择。

这里是一个简单的“Hello,world”示例应用程序:

import tornado.ioloop
import tornado.web

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

if __name__ == "__main__":
    application = tornado.web.Application([
        (r"/", MainHandler),
    ])
    application.listen(8888)
    tornado.ioloop.IOLoop.current().start()

有关更多信息,请参阅 用户手册

线程安全注释

一般来说,RequestHandler 和Tornado其他地方的方法不是线程安全的。特别地,诸如 write()finish()flush() 的方法只能从主线程调用。如果使用多线程,在完成请求之前使用 IOLoop.add_callback 将控制权转移回主线程很重要。

请求处理程序

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

HTTP请求处理程序的基类。

子类必须至少定义下面“入口点”部分中定义的一种方法。

入口点

RequestHandler.initialize()[源代码]

钩子用于子类初始化。每个请求都调用。

作为url规范的第三个参数传递的字典将作为关键字参数提供给initialize()。

例:

class ProfileHandler(RequestHandler):
    def initialize(self, database):
        self.database = database

    def get(self, username):
        ...

app = Application([
    (r'/user/(.*)', ProfileHandler, dict(database=database)),
    ])
RequestHandler.prepare()[源代码]

get/post/etc之前的请求开始时调用。

重写此方法以执行公共初始化,而不管请求方法如何。

异步支持:使用 gen.coroutinereturn_future 装饰此方法,使其成为异步(asynchronous 装饰器不能在 prepare 上使用)。如果此方法返回一个 Future 执行将不会继续,直到 Future 完成。

3.1 新版功能: 异步支持。

RequestHandler.on_finish()[源代码]

在请求结束后调用。

覆盖此方法以执行清除,记录等。此方法是 prepare 的对应方法。 on_finish 可能不会产生任何输出,因为在响应已发送到客户端后调用。

实现以下任何方法(统称为HTTP谓词方法)来处理相应的HTTP方法。这些方法可以与以下装饰器之一异步:gen.coroutinereturn_futureasynchronous

这些方法的参数来自 URLSpec:正则表达式中的任何捕获组都将成为HTTP动词方法的参数(如果组被命名,则为关键字参数,如果未命名,则为位置参数)。

要支持不在此列表上的方法,请覆盖类变量 SUPPORTED_METHODS:

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

    def propfind(self):
        pass
RequestHandler.get(*args, **kwargs)[源代码]
RequestHandler.head(*args, **kwargs)[源代码]
RequestHandler.post(*args, **kwargs)[源代码]
RequestHandler.delete(*args, **kwargs)[源代码]
RequestHandler.patch(*args, **kwargs)[源代码]
RequestHandler.put(*args, **kwargs)[源代码]
RequestHandler.options(*args, **kwargs)[源代码]

输入

RequestHandler.get_argument(name, default=<object object>, strip=True)[源代码]

返回具有给定名称的参数的值。

如果未提供默认值,则该参数被认为是必需的,如果缺少 MissingArgumentError,我们将引发 MissingArgumentError

如果参数多次出现在url中,则返回最后一个值。

返回的值总是unicode。

RequestHandler.get_arguments(name, strip=True)[源代码]

返回具有给定名称的参数的列表。

如果参数不存在,则返回空列表。

返回的值总是unicode。

RequestHandler.get_query_argument(name, default=<object object>, strip=True)[源代码]

返回请求查询字符串中具有给定名称的参数的值。

如果未提供默认值,则该参数被认为是必需的,如果缺少 MissingArgumentError,我们将引发 MissingArgumentError

如果参数多次出现在url中,则返回最后一个值。

返回的值总是unicode。

3.2 新版功能.

RequestHandler.get_query_arguments(name, strip=True)[源代码]

返回具有给定名称的查询参数的列表。

如果参数不存在,则返回空列表。

返回的值总是unicode。

3.2 新版功能.

RequestHandler.get_body_argument(name, default=<object object>, strip=True)[源代码]

从请求正文返回具有给定名称的参数的值。

如果未提供默认值,则该参数被认为是必需的,如果缺少 MissingArgumentError,我们将引发 MissingArgumentError

如果参数多次出现在url中,则返回最后一个值。

返回的值总是unicode。

3.2 新版功能.

RequestHandler.get_body_arguments(name, strip=True)[源代码]

返回具有给定名称的主体参数的列表。

如果参数不存在,则返回空列表。

返回的值总是unicode。

3.2 新版功能.

RequestHandler.decode_argument(value, name=None)[源代码]

解析请求中的参数。

参数已经过百分比解码,现在是字节字符串。默认情况下,此方法将参数解码为utf-8并返回unicode字符串,但这可能会在子类中被覆盖。

此方法用作 get_argument() 和从URL提取并传递给 get()/post()/等的值的过滤器。

如果已知,则提供参数的名称,但可以为None(例如,对于url正则表达式中的未命名组)。

RequestHandler.request

包含附加请求参数的 tornado.httputil.HTTPServerRequest 对象包括例如标题和正文数据。

RequestHandler.path_args
RequestHandler.path_kwargs

path_argspath_kwargs 属性包含传递给 HTTP动词方法 的位置和关键字参数。这些属性在调用这些方法之前设置,因此这些值在 prepare 期间可用。

输出

RequestHandler.set_status(status_code, reason=None)[源代码]

设置响应的状态代码。

参数:
  • status_code (int) – 响应状态代码。如果 reasonNone,它必须存在于 httplib.responses 中。
  • reason (string) – 描述状态代码的人可读的原因短语。如果 None,它将从 httplib.responses 填写。
RequestHandler.set_header(name, value)[源代码]

设置给定的响应头名称和值。

如果给定了datetime,我们将根据HTTP规范自动对其进行格式化。如果值不是字符串,我们将其转换为字符串。所有头值然后编码为UTF-8。

RequestHandler.add_header(name, value)[源代码]

添加给定的响应标头和值。

set_header 不同,add_header 可能被调用多次以返回同一标头的多个值。

RequestHandler.clear_header(name)[源代码]

清除传出标头,撤销先前的 set_header 呼叫。

请注意,此方法不适用于由 add_header 设置的多值标头。

RequestHandler.set_default_headers()[源代码]

覆盖此设置以在请求开头设置HTTP标头。

例如,这是设置自定义 Server 标题的地方。注意,在正常的请求处理流程中设置这样的头部可能不会做你想要的,因为头部可能在错误处理期间被重置。

RequestHandler.write(chunk)[源代码]

将给定的块写入输出缓冲区。

要将输出写入网络,请使用下面的flush()方法。

如果给定的块是字典,我们将其写为JSON,并将响应的Content-Type设置为 application/json。 (如果要将JSON作为不同的 Content-Type 发送,请调用set_header after 调用write())。

请注意,由于潜在的跨站点安全漏洞,列表不会转换为JSON。所有JSON输出应该包装在字典中。更多细节在 http://haacked.com/archive/2009/06/25/json-hijacking.aspx/https://github.com/facebook/tornado/issues/1009

RequestHandler.flush(include_footers=False, callback=None)[源代码]

将当前输出缓冲区刷新到网络。

callback 参数,如果给定,可以用于流控制:它将在所有刷新数据已写入套接字时运行。注意,一次只能有一个flush flush回调;如果在先前的flush的回调运行之前发生另一次冲刷,则先前的回调将被丢弃。

在 4.0 版更改: 现在返回 Future 如果没有回调。

RequestHandler.finish(chunk=None)[源代码]

完成此响应,结束HTTP请求。

RequestHandler.render(template_name, **kwargs)[源代码]

使用给定的参数作为响应呈现模板。

RequestHandler.render_string(template_name, **kwargs)[源代码]

使用给定的参数生成给定的模板。

我们返回生成的字节字符串(在utf8)。要生成和写一个模板作为响应,请使用上面的render()。

RequestHandler.get_template_namespace()[源代码]

返回要用作默认模板命名空间的字典。

可能被子类覆盖以添加或修改值。

此方法的结果将与 tornado.template 模块中的其他默认值以及 renderrender_string 的关键字参数结合使用。

RequestHandler.redirect(url, permanent=False, status=None)[源代码]

向指定(可选相对)网址发送重定向。

如果指定了 status 参数,那么该值将用作HTTP状态代码;否则根据 permanent 参数选择301(永久)或302(临时)。默认值为302(临时)。

RequestHandler.send_error(status_code=500, **kwargs)[源代码]

将给定的HTTP错误代码发送到浏览器。

如果 flush() 已经被调用,则不可能发送错误,因此该方法将简单地终止响应。如果输出已被写入但尚未刷新,则将被丢弃并替换为错误页。

覆盖 write_error() 以自定义返回的错误页面。其他关键字参数传递到 write_error

RequestHandler.write_error(status_code, **kwargs)[源代码]

覆盖以实施自定义错误页面。

write_error 可以调用 writerenderset_header 等来产生输出。

如果此错误是由未捕获异常(包括HTTPError)引起的,则 exc_info 三元组将作为 kwargs["exc_info"] 可用。注意,对于诸如 sys.exc_info()traceback.format_exc 的方法,此异常可能不是“当前”异常。

RequestHandler.clear()[源代码]

重置此响应的所有标题和内容。

RequestHandler.data_received(chunk)[源代码]

实现此方法以处理流传输的请求数据。

需要 stream_request_body 装饰器。

饼干

RequestHandler.cookies

self.request.cookies 的别名。

获取具有给定名称的cookie的值,否则为默认值。

使用给定的选项设置给定的Cookie名称/值。

其他关键字参数直接在Cookie.Morsel上设置。有关可用属性,请参阅 http://docs.python.org/library/cookie.html#morsel-objects

删除具有给定名称的cookie。

由于Cookie协议的限制,您必须传递相同的路径和域来清除Cookie(如果设置了该Cookie)(但没有办法在服务器端找到用于给定Cookie的值) 。

RequestHandler.clear_all_cookies(path='/', domain=None)[源代码]

删除用户使用此请求发送的所有Cookie。

有关路径和域参数的更多信息,请参阅 clear_cookie

在 3.2 版更改: 添加了 pathdomain 参数。

返回给定的签名cookie(如果验证)或None。

解码的Cookie值作为字节字符串返回(与 get_cookie 不同)。

在 3.2.1 版更改: 添加了 min_version 参数。引入cookie版本2;默认情况下接受版本1和2。

返回安全Cookie的签名密钥版本。

版本返回为int。

标记和时间戳一个cookie,所以它不能被伪造。

您必须在应用程序中指定 cookie_secret 设置才能使用此方法。它应该是一个长的,随机的字节序列,用作签名的HMAC密码。

要使用此方法读取cookie集,请使用 get_secure_cookie()

请注意,expires_days 参数设置浏览器中Cookie的生存期,但与 get_secure_cookiemax_age_days 参数无关。

安全cookie可能包含任意字节值,而不仅仅是unicode字符串(不像常规cookie)

在 3.2.1 版更改: 添加了 version 参数。引入cookie版本2并将其设为默认值。

RequestHandler.create_signed_value(name, value, version=None)[源代码]

标记和时间戳字符串,所以它不能被伪造。

通常通过set_secure_cookie使用,但作为非cookie使用的单独方法提供。要解码不存储为cookie的值,请使用get_secure_cookie的可选value参数。

在 3.2.1 版更改: 添加了 version 参数。引入cookie版本2并将其设为默认值。

tornado.web.MIN_SUPPORTED_SIGNED_VALUE_VERSION = 1

这个版本的Tornado支持的最旧的签名值版本。

无法解码比此版本更旧的签名值。

3.2.1 新版功能.

tornado.web.MAX_SUPPORTED_SIGNED_VALUE_VERSION = 2

此版本的Tornado支持的最新签名值版本。

无法解码比此版本更新的签名值。

3.2.1 新版功能.

tornado.web.DEFAULT_SIGNED_VALUE_VERSION = 2

RequestHandler.create_signed_value 生成的有符号值版本。

可以通过传递 version 关键字参数来覆盖。

3.2.1 新版功能.

tornado.web.DEFAULT_SIGNED_VALUE_MIN_VERSION = 1

RequestHandler.get_secure_cookie 接受的最旧的签名值。

可以通过传递 min_version 关键字参数来覆盖。

3.2.1 新版功能.

其他

RequestHandler.application

提供此请求的 Application 对象

RequestHandler.check_etag_header()[源代码]

检查 Etag 头对请求的 If-None-Match

如果请求的Etag匹配并返回304,则返回 True。例如:

self.set_etag_header()
if self.check_etag_header():
    self.set_status(304)
    return

此方法在请求完成时自动调用,但对于覆盖 compute_etag 并且希望在完成请求之前对 If-None-Match 进行早期检查的应用程序可能会被更早调用。在调用此方法之前,应设置 Etag 头(可能使用 set_etag_header)。

验证 _xsrf cookie是否与 _xsrf 参数匹配。

为了防止跨站点请求伪造,我们设置了一个 _xsrf cookie,并将所有 POST 请求的值都作为非cookie字段包含在内。如果两者不匹配,我们将拒绝表单提交作为潜在的伪造。

_xsrf 值可以设置为名为 _xsrf 的表单字段,也可以设置为名为 X-XSRFTokenX-CSRFToken 的自定义HTTP标头(后者用于与Django兼容)。

http://en.wikipedia.org/wiki/Cross-site_request_forgery

在版本1.1.1之前,如果HTTP头部 X-Requested-With: XMLHTTPRequest 存在,则忽略此检查。此异常显示为不安全,已被删除。更多信息,请参阅 http://www.djangoproject.com/weblog/2011/feb/08/security/ http://weblog.rubyonrails.org/2011/2/8/csrf-protection-bypass-in-ruby-on-rails

在 3.2.2 版更改: 添加了对cookie版本2的支持。支持版本1和2。

RequestHandler.compute_etag()[源代码]

计算要用于此请求的etag标头。

默认情况下使用到目前为止写入的内容的哈希值。

可能被覆盖以提供自定义etag实现,或者可能返回None以禁用tornado的默认etag支持。

RequestHandler.create_template_loader(template_path)[源代码]

返回给定路径的新模板加载器。

可能被子类覆盖。默认情况下,使用 autoescapetemplate_whitespace 应用程序设置在给定路径上返回基于目录的加载器。如果提供了 template_loader 应用程序设置,则使用它。

RequestHandler.current_user

此请求的已通过身份验证的用户。

这是通过以下两种方式之一设置的:

  • 子类可以覆盖 get_current_user(),这将在第一次访问 self.current_user 时自动调用。 get_current_user() 只会每个请求被调用一次,并被缓存以供将来访问:

    def get_current_user(self):
        user_cookie = self.get_secure_cookie("user")
        if user_cookie:
            return json.loads(user_cookie)
        return None
    
  • 它可以被设置为正常变量,通常来自被重写的 prepare():

    @gen.coroutine
    def prepare(self):
        user_id_cookie = self.get_secure_cookie("user_id")
        if user_id_cookie:
            self.current_user = yield load_user(user_id_cookie)
    

注意,prepare() 可以是协程,而 get_current_user() 可以不是,因此如果加载用户需要异步操作,则后者形式是必要的。

用户对象可以是任何类型的应用程序选择。

RequestHandler.get_browser_locale(default='en_US')[源代码]

Accept-Language 标题确定用户的区域设置。

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4

RequestHandler.get_current_user()[源代码]

覆盖以从例如cookie确定当前用户。

此方法可能不是协同程序。

RequestHandler.get_login_url()[源代码]

覆盖以根据请求自定义登录URL。

默认情况下,我们使用 login_url 应用程序设置。

RequestHandler.get_status()[源代码]

返回响应的状态代码。

RequestHandler.get_template_path()[源代码]

覆盖以自定义每个处理程序的模板路径。

默认情况下,我们使用 template_path 应用程序设置。返回无相对于调用文件加载模板。

RequestHandler.get_user_locale()[源代码]

覆盖以确定来自已验证用户的语言环境。

如果返回None,我们会回到 get_browser_locale()

这个方法应该返回一个 tornado.locale.Locale 对象,很可能通过像 tornado.locale.get("en") 这样的调用获得

RequestHandler.locale

当前会话的区域设置。

get_user_locale 确定,您可以覆盖它以根据例如存储在数据库中的用户首选项或使用 Accept-Language 头的 get_browser_locale 设置区域设置。

RequestHandler.log_exception(typ, value, tb)[源代码]

覆盖以自定义未捕获异常的日志记录。

默认情况下,将 HTTPError 的实例作为没有堆栈跟踪的警告(在 tornado.general 记录器上),以及所有其他异常作为堆栈跟踪的错误(在 tornado.application 记录器上)。

3.1 新版功能.

RequestHandler.on_connection_close()[源代码]

如果客户端关闭连接,则在异步处理程序中调用。

覆盖此操作以清除与长期连接相关联的资源。请注意,只有在异步处理期间关闭连接时才调用此方法;如果你需要在每次请求之后清理 on_finish

代理可以在客户端离开后保持连接一段时间(可能无限期),因此在最终用户关闭其连接后,可能无法立即调用此方法。

RequestHandler.require_setting(name, feature='this feature')[源代码]

如果未定义给定应用设置,则引发例外。

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

Application.reverse_url 别名。

RequestHandler.set_etag_header()[源代码]

使用 self.compute_etag() 设置响应的Etag头。

注意:如果 compute_etag() 返回 None,则不设置报头。

请求完成后会自动调用此方法。

RequestHandler.settings

self.application.settings 的别名。

RequestHandler.static_url(path, include_host=None, **kwargs)[源代码]

返回给定相对静态文件路径的静态URL。

此方法要求您在应用程序(它指定静态文件的根目录)中设置 static_path 设置。

此方法返回版本化的URL(默认附加 ?v=<signature>),允许静态文件无限缓存。这可以通过传递 include_version=False (在默认实现中禁用;其他静态文件实现不需要支持,但它们可能支持其他选项)。

默认情况下,此方法返回相对于当前主机的URL,但如果 include_host 为true,返回的URL将是绝对的。如果此处理程序具有 include_host 属性,那么该值将用作未通过 include_host 作为关键字参数的所有 static_url 调用的默认值。

RequestHandler.xsrf_form_html()[源代码]

要包含在所有POST表单中的HTML <input/> 元素。

它定义 _xsrf 输入值,我们检查所有POST请求,以防止跨站点请求伪造。如果您已设置 xsrf_cookies 应用程序设置,则必须在所有HTML表单中包含此HTML。

在模板中,应该使用 {% module xsrf_form_html() %} 调用此方法

有关详细信息,请参阅上面的 check_xsrf_cookie()

RequestHandler.xsrf_token

当前用户/会话的XSRF防护令牌。

为了防止跨站点请求伪造,我们设置一个“_xsrf”cookie,并将所有POST请求的参数包含相同的“_xsrf”值。如果两者不匹配,我们将拒绝表单提交作为潜在的伪造。

http://en.wikipedia.org/wiki/Cross-site_request_forgery

在 3.2.2 版更改: xsrf令牌现在将在每个请求中都应用一个随机掩码,这使得在被压缩的页面中包含令牌是安全的。有关此更改所固定的问题的更多信息,请参阅 http://breachattack.com。除非 xsrf_cookie_version Application 设置为1,否则旧版本(版本1)的Cookie将转换为版本2。

在 4.3 版更改: xsrf_cookie_kwargs Application 设置可用于提供其他cookie选项(将直接传递给 set_cookie)。例如,xsrf_cookie_kwargs=dict(httponly=True, secure=True) 将在 _xsrf cookie上设置 securehttponly 标志。

应用程序配置

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

构成Web应用程序的请求处理程序集合。

这个类的实例是可调用的,可以直接传递给HTTPServer来提供应用程序:

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

此类的构造函数接收 URLSpec 对象或(regexp,request_class)元组的列表。当我们收到请求时,我们按顺序遍历列表,并实例化第一个请求类的实例,该请求类的regexp匹配请求路径。请求类可以指定为类对象或(完全限定)名称。

每个元组可以包含其他元素,这些元素对应于 URLSpec 构造函数的参数。 (在Tornado 3.2之前,只允许两个或三个元素的元组)。

字典可以作为元组的第三个元素传递,它将被用作处理程序的构造函数和 initialize 方法的关键字参数。此模式用于本示例中的 StaticFileHandler (请注意,StaticFileHandler 可以使用下面描述的static_path设置自动安装):

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

我们使用 add_handlers 方法支持虚拟主机,它采用主机正则表达式作为第一个参数:

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

您可以通过将 static_path 设置作为关键字参数发送来提供静态文件。我们将从 /static/ URI(这可以使用 static_url_prefix 设置进行配置)提供这些文件,我们将从同一目录中提供 /favicon.ico/robots.txtStaticFileHandler 的自定义子类可以使用 static_handler_class 设置指定。

settings

传递给构造函数的附加关键字参数保存在 settings 字典中,并且在文档中通常称为“应用程序设置”。设置用于自定义Tornado的各个方面(虽然在某些情况下,通过覆盖 RequestHandler 的子类中的方法可以更丰富的自定义)。一些应用程序还喜欢使用 settings 字典作为一种方式,使应用程序特定的设置可用于处理程序,而不使用全局变量。Tornado中使用的设置如下所述。

常规设置:

  • autoreload:如果 True,当任何源文件更改时,服务器进程将重新启动,如 调试模式和自动重新加载 中所述。这个选项在Tornado 3.2中是新的;以前该功能由 debug 设置控制。

  • debug调试模式和自动重新加载 中描述的几种调试模式设置的速记。设置 debug=True 等效于 autoreload=Truecompiled_template_cache=Falsestatic_hash_cache=Falseserve_traceback=True

  • default_handler_classdefault_handler_args:如果没有找到其他匹配,将使用此处理程序;使用它来实现自定义404页面(Tornado 3.2中的新功能)。

  • compress_response:如果 True,文本格式的响应将被自动压缩。新在Tornado4.0。

  • gzip:自Tornado 4.0以来 compress_response 的已弃用别名。

  • log_function:在记录结果的每个请求(使用一个参数,RequestHandler 对象)结束时将调用此函数。默认实现写入 logging 模块的根日志记录器。也可以通过压倒 Application.log_request 定制。

  • serve_traceback:如果为true,则默认错误页面将包括错误的回溯。这个选项在Tornado 3.2中是新的;以前此功能由 debug 设置控制。

  • ui_modulesui_methods:可以设置为对模板可用的 UIModule 或UI方法的映射。可以设置为模块,字典或模块和/或词典的列表。有关详细信息,请参阅 UI模块

身份验证和安全设置:

  • cookie_secret:由 RequestHandler.get_secure_cookieset_secure_cookie 用于对Cookie进行签名。

  • key_version:当 cookie_secret 是键字典时,由requestHandler set_secure_cookie 用于使用特定键来签名cookie。

  • login_url:如果用户未登录,authenticated 装饰器将重定向到此URL。可以通过覆盖 RequestHandler.get_login_url 进一步定制

  • xsrf_cookies:如果为true,将启用 跨站点请求防伪

  • xsrf_cookie_version:控制此服务器生成的新XSRF Cookie的版本。通常应保留默认值(始终是最高支持版本),但在版本转换期间可能会暂时设置为较低值。Tornado 3.2.2的新功能,其中引入XSRF cookie版本2。

  • xsrf_cookie_kwargs:可以设置为传递给 RequestHandler.set_cookie 用于XSRF cookie的其他参数的字典。

  • twitter_consumer_keytwitter_consumer_secretfriendfeed_consumer_keyfriendfeed_consumer_secretgoogle_consumer_keygoogle_consumer_secretfacebook_api_keyfacebook_secret:用于在 tornado.auth 模块中对各种API进行认证。

模板设置:

  • autoescape:控制模板的自动转义。可以设置为 None 以禁用转义,或者设置为所有输出应通过的函数的 name。默认为 "xhtml_escape"。可以使用 {% autoescape %} 指令在每个模板的基础上进行更改。

  • compiled_template_cache:默认为 True;如果 False 模板将在每个请求重新编译。这个选项在Tornado 3.2中是新的;以前该功能由 debug 设置控制。

  • template_path:包含模板文件的目录。可以通过覆盖 RequestHandler.get_template_path 进一步定制

  • template_loader:分配到 tornado.template.BaseLoader 的实例以自定义模板加载。如果使用此设置,则会忽略 template_pathautoescape 设置。可以通过重写 RequestHandler.create_template_loader 进一步定制。

  • template_whitespace:控制模板中空白的处理;有关允许的值,请参阅 tornado.template.filter_whitespace。Tornado 4.3的新功能。

静态文件设置:

  • static_hash_cache:默认为 True;如果 False 静态网址将在每个请求重新计算。这个选项在Tornado 3.2中是新的;以前该功能由 debug 设置控制。

  • static_path:将为其提供静态文件的目录。

  • static_url_prefix:静态文件的Url前缀,默认为 "/static/"

  • static_handler_classstatic_handler_args:可以设置为静态文件使用不同的处理程序,而不是默认的 tornado.web.StaticFileHandlerstatic_handler_args,如果设置,应该是要传递给处理程序的 initialize 方法的关键字参数的字典。

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

在给定端口上为此应用程序启动HTTP服务器。

这是一个方便别名,用于创建 HTTPServer 对象并调用其listen方法。 HTTPServer.listen 不支持的关键字参数被传递给 HTTPServer 构造函数。对于高级用途(例如多进程模式),不要使用此方法;创建 HTTPServer 并直接调用其 TCPServer.bind/TCPServer.start 方法。

请注意,在调用此方法后,您仍然需要调用 IOLoop.current().start() 来启动服务器。

返回 HTTPServer 对象。

在 4.3 版更改: 现在返回 HTTPServer 对象。

add_handlers(host_pattern, host_handlers)[源代码]

将给定的处理程序附加到我们的处理程序列表。

主机模式按照添加顺序顺序处理。将考虑所有匹配模式。

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

返回名为 name 的处理程序的URL路径

处理程序必须作为命名的 URLSpec 添加到应用程序。

Arg将替换 URLSpec 正则表达式中的捕获组。如果需要,它们将被转换为字符串,编码为utf8和url转义。

log_request(handler)[源代码]

将完成的HTTP请求写入日志。

默认写入python根日志记录器。要更改此行为,应用程序子类并覆盖此方法,或者将应用程序设置字典中的函数作为 log_function 传递。

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

指定URL和处理程序之间的映射。

参数:

  • pattern:要匹配的正则表达式。正则表达式中的任何捕获组都将作为参数传递给处理程序的get/post/etc方法(如果命名,则通过关键字,如果未命名,则通过位置传递)命名捕获组和未命名捕获组可能不会在同一规则中混合。

  • handler:要调用的 RequestHandler 子类。

  • kwargs (可选):要传递给处理程序构造函数的其他参数的字典。

  • name (可选):此处理程序的名称。由 Application.reverse_url 使用。

URLSpec 类也可以名称 tornado.web.url 获得。

装饰

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

如果它们是异步的,则封装请求处理程序方法。

这个装饰器用于回调式异步方法;对于协同,使用没有 @asynchronous@gen.coroutine 装饰器。 (由于遗留原因,合法使用两个装饰器,@asynchronous 是第一个,但在这种情况下 @asynchronous 将被忽略)

这个装饰器应该只适用于 HTTP动词方法;其行为未定义任何其他方法。这个装饰器不会使 make 方法异步;它告诉框架方法 is 异步。对于这个装饰器是有用的,该方法必须(至少有时)做异步。

如果给出了此装饰器,则在方法返回时响应不会完成。由请求处理程序调用 self.finish() 来完成HTTP请求。没有这个装饰器,当 get()post() 方法返回时,请求自动完成。例:

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 版更改: 使用没有 @asynchronous@gen.coroutine 的能力。

在 4.3 版更改: 从用 @asynchronous 装饰的方法返回除 None 或可伸缩对象之外的任何东西都是错误。此类返回值以前被静默忽略。

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

使用此方法装饰方法以要求用户登录。

如果用户未登录,他们将被重定向到配置的 login url

如果您使用查询参数配置登录URL,Tornado会假设您知道您在做什么,并按原样使用它。如果没有,它将添加一个 next 参数,以便登录页面知道您登录后在哪里发送给您。

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

使用此装饰器在请求路径中添加缺少的尾部斜杠。

例如,对 /foo 的请求将使用该装饰器重定向到 /foo/。您的请求处理程序映射应使用正则表达式(如 r'/foo/?')结合使用装饰器。

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

使用此装饰器从请求路径中删除尾部斜杠。

例如,对 /foo/ 的请求将使用该装饰器重定向到 /foo。您的请求处理程序映射应使用正则表达式(如 r'/foo/*')结合使用装饰器。

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

应用于 RequestHandler 子类以启用流身体支持。

这个装饰器意味着以下变化:

  • HTTPServerRequest.body 未定义,并且body参数不会包含在 RequestHandler.get_argument 中。

  • 在读取请求头时调用 RequestHandler.prepare,而不是在读取整个主体之后调用。

  • 子类必须定义一个方法 data_received(self, data):,当数据可用时,它将被调用零次或多次。请注意,如果请求具有空主体,则可能不会调用 data_received

  • preparedata_received 可以返回期货(例如通过 @gen.coroutine,在这种情况下,下一个方法将不会被调用,直到那些期货完成。

  • 在读取整个主体之后,将调用常规HTTP方法(postput 等)。

data_received 和异步 prepare 之间存在微妙的交互:对 data_received 的第一次调用可以在对 prepare 的调用返回 或产生 之后的任何点发生。

一切

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

异常,将变成HTTP错误响应。

提高 HTTPError 是调用 RequestHandler.send_error 的一个方便的替代方法,因为它会自动结束当前函数。

要自定义使用 HTTPError 发送的响应,请覆盖 RequestHandler.write_error

参数:
  • status_code (int) – HTTP状态代码。必须在 httplib.responses 中列出,除非提供 reason 关键字参数。
  • log_message (string) – 要写入此错误的日志的消息(除非 Application 处于调试模式,否则不会显示给用户)。可能包含 %s 样式的占位符,将以剩余的位置参数填充。
  • reason (string) – 仅限关键字的参数。与“ status_code ”一起在状态行中传递的HTTP“reason”短语。通常由 status_code 自动确定,但可用于使用非标准数字代码。
exception tornado.web.Finish[源代码]

结束请求但不生成错误响应的异常。

当在 RequestHandler 中引发 Finish 时,请求将结束(如果尚未被调用则调用 RequestHandler.finish),但不会调用错误处理方法(包括 RequestHandler.write_error)。

如果 Finish() 创建时没有参数,则待处理的响应将按原样发送。如果给 Finish() 一个参数,该参数将传递给 RequestHandler.finish()

这可以是实现自定义错误页面比覆盖 write_error 更方便的方法(特别是在库代码中):

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

在 4.3 版更改: 传递给 Finish() 的参数将传递给 RequestHandler.finish

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

RequestHandler.get_argument 提出的异常。

这是 HTTPError 的子类,因此如果未捕获,将使用400响应代码而不是500(并且不会记录堆栈跟踪)。

3.1 新版功能.

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

页面上的可重复使用的模块化UI单元。

UI模块通常执行其他查询,并且它们可以包括将包括在输出页面中的其他CSS和JavaScript,这些页面会自动插入到页面呈现中。

UIModule的子类必须覆盖 render 方法。

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

在子类中覆盖以返回此模块的输出。

embedded_javascript()[源代码]

覆盖以返回要嵌入页面的JavaScript字符串。

javascript_files()[源代码]

覆盖以返回此模块所需的JavaScript文件列表。

如果返回值是相对路径,它们将被传递给 RequestHandler.static_url;否则将按原样使用。

embedded_css()[源代码]

覆盖以返回将嵌入页面的CSS字符串。

css_files()[源代码]

覆盖以返回此模块所需的CSS文件列表。

如果返回值是相对路径,它们将被传递给 RequestHandler.static_url;否则将按原样使用。

html_head()[源代码]

覆盖以返回将放在<head/>元素中的HTML字符串。

html_body()[源代码]

覆盖以返回将放在<body/>元素末尾的HTML字符串。

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

呈现模板并将其作为字符串返回。

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

使用 status_code 为所有请求生成错误响应。

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

包含另一个HTTP服务器回调的 RequestHandler

回退是接受 HTTPServerRequest 的可调用对象,例如 Applicationtornado.wsgi.WSGIContainer。这在同一服务器中同时使用Tornado RequestHandlers 和WSGI最有用。典型用法:

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)[源代码]

将客户端重定向到所有GET请求的给定URL。

您应该向处理程序提供关键字参数 url,例如:

application = web.Application([
    (r"/oldpath", web.RedirectHandler, {"url": "/newpath"}),
])
class tornado.web.StaticFileHandler(application, request, **kwargs)[源代码]

一个可以从目录提供静态内容的简单处理程序。

如果将 static_path 关键字参数传递给 Application,则会自动配置 StaticFileHandler。此处理程序可以使用 static_url_prefixstatic_handler_classstatic_handler_args 设置进行定制。

要将静态数据目录的附加路径映射到此处理程序,您可以向应用程序中添加一行:

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

处理程序构造函数需要一个 path 参数,它指定要提供的内容的本地根目录。

注意,正则表达式中的捕获组需要解析get()方法的 path 参数的值(不同于上面的构造函数参数);有关详细信息,请参阅 URLSpec

要在请求目录时自动提供像 index.html 这样的文件,请在应用程序设置中设置 static_handler_args=dict(default_filename="index.html"),或者将 default_filename 添加为 StaticFileHandler 的初始化参数。

为了最大化浏览器缓存的有效性,此类支持版本化的URL(默认情况下使用参数 ?v=)。如果给定版本,我们指示浏览器无限期缓存此文件。 make_static_url (也可用作 RequestHandler.static_url)可以用于构造版本化的URL。

此处理程序主要用于开发和轻型文件服务;对于繁忙的流量,使用专用的静态文件服务器(如nginx或Apache)会更有效率。我们支持HTTP Accept-Ranges 机制返回部分内容(因为一些浏览器需要此功能才能在HTML5音频或视频中搜索)。

子类化注释

这个类被设计为通过子类化是可扩展的,但是因为静态url是用类方法而不是实例方法生成的,所以继承模式有些不寻常。当覆盖类方法时,请务必使用 @classmethod 装饰器。实例方法可以使用属性 self.path self.absolute_pathself.modified

子类应该只覆盖本节中讨论的方法;覆盖其他方法是容易出错的。由于与 compute_etag 和其他方法的紧耦合,覆盖 StaticFileHandler.get 是特别有问题的。

要更改生成静态网址的方式(例如,匹配另一个服务器或CDN的行为),请覆盖 make_static_urlparse_url_pathget_cache_time 和/或 get_version

要替换与文件系统的所有交互(例如,从数据库提供静态内容),请覆盖 get_contentget_content_sizeget_modified_timeget_absolute_pathvalidate_absolute_path

在 3.1 版更改: 在Tornado 3.1中添加了许多子类的方法。

compute_etag()[源代码]

根据静态url版本设置 Etag 头。

这允许对高速缓存版本的有效 If-None-Match 检查,并且发送用于部分响应(即,与完整文件相同的 Etag)的正确 Etag

3.1 新版功能.

set_headers()[源代码]

设置响应中的内容和缓存标头。

3.1 新版功能.

should_return_304()[源代码]

如果标题指示我们应该返回304,则返回True。

3.1 新版功能.

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

返回 path 相对于 root 的绝对位置。

root 是为此 StaticFileHandler 配置的路径(在大多数情况下为 static_path Application 设置)。

这个类方法可以在子类中被覆盖。默认情况下,它返回文件系统路径,但是可以使用其他字符串,只要它们是唯一的并且被子类的被覆盖的 get_content 理解。

3.1 新版功能.

validate_absolute_path(root, absolute_path)[源代码]

验证并返回绝对路径。

rootStaticFileHandler 的配置路径,pathget_absolute_path 的结果

这是在请求处理期间调用的实例方法,因此它可能会引发 HTTPError 或使用像 RequestHandler.redirect 这样的方法(重定向后停止进一步处理,返回None)。这是在那里生成404错误的文件丢失。

此方法可能会在返回之前修改路径,但请注意,任何此类修改都不会被 make_static_url 理解。

在实例方法中,此方法结果可用作 self.absolute_path

3.1 新版功能.

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

检索位于给定绝对路径的请求资源的内容。

这个类方法可能被子类覆盖。注意它的签名不同于其他可覆盖的类方法(没有 settings 参数);这是故意确保 abspath 能够独立地作为缓存键。

此方法应返回字节字符串或字节字符串的迭代器。后者对于大文件是首选,因为它有助于减少内存碎片。

3.1 新版功能.

classmethod get_content_version(abspath)[源代码]

返回给定路径下资源的版本字符串。

这个类方法可能被子类覆盖。默认实现是文件内容的哈希。

3.1 新版功能.

get_content_size()[源代码]

检索给定路径上资源的总大小。

此方法可能被子类覆盖。

3.1 新版功能.

在 4.0 版更改: 现在总是调用此方法,而不是仅在请求部分结果时调用。

get_modified_time()[源代码]

返回 self.absolute_path 上次修改的时间。

可能在子类中被覆盖。应返回 datetime 对象或无。

3.1 新版功能.

get_content_type()[源代码]

返回要用于此请求的 Content-Type 标头。

3.1 新版功能.

set_extra_headers(path)[源代码]

为子类添加额外的头到响应

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

覆盖以自定义缓存控制行为。

返回正值秒数,以使结果可缓存该时间量或0,以将资源标记为可缓存不确定的时间量(取决于浏览器启发式)。

默认情况下,为 v 参数请求的资源返回10年的缓存到期时间。

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

构造给定路径的版本化网址。

这个方法可以在子类中重写(但是注意它是一个类方法,而不是一个实例方法)。子类只需要实现签名 make_static_url(cls, settings, path);其他关键字参数可以通过 static_url 传递,但不是标准的。

settingsApplication.settings 字典。 path 是请求的静态路径。返回的网址应该相对于当前主机。

include_version 确定所生成的URL是否应包括包含与给定 path 对应的文件的版本哈希值的查询字符串。

parse_url_path(url_path)[源代码]

将静态URL路径转换为文件系统路径。

url_path 是已删除 static_url_prefix 的URL的路径组件。返回值应该是相对于 static_path 的文件系统路径。

这是 make_static_url 的逆。

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

生成要在静态URL中使用的版本字符串。

settingsApplication.settings 字典,path 是所请求资产在文件系统上的相对位置。返回的值应该是字符串,如果没有版本可以确定,则为 None

在 3.1 版更改: 此方法之前建议为子类覆盖; get_content_version 现在是首选,因为它允许基类处理结果的缓存。