tornado.web --- RequestHandlerApplication

tornado.web 提供一个具有异步功能的简单Web框架,允许它扩展到大量开放连接,使其非常适合 long polling .

下面是一个简单的 "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 在完成请求之前将控制权转移回主线程,或者将其他线程的使用限制为 IOLoop.run_in_executor 并确保在执行器中运行的回调不会引用Tornado对象。

请求执行程序

class tornado.web.RequestHandler(...)[源代码]

HTTP请求处理程序的基类。

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

应用程序不应构造 RequestHandler objects directly and subclasses should not override ``_ _初始化 initialize 相反)。

入口点

RequestHandler.initialize() → None

用于子类初始化的挂钩。为每个请求调用。

作为 URLSpec 将作为关键字参数提供给 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() → Optional[Awaitable[None]][源代码]

在请求开始时调用 get [邮寄]等。

无论请求方法如何,都要重写此方法以执行公共初始化。

异步支持:使用 async def 或者用装饰这个方法 gen.coroutine 使之成为异步的。如果此方法返回 Awaitable 直到 Awaitable 完成了。

3.1 新版功能: 异步支持。

RequestHandler.on_finish() → None[源代码]

在请求结束后调用。

重写此方法以执行清理、日志记录等。此方法与 prepare . on_finish 可能不会产生任何输出,因为在将响应发送到客户端之后调用它。

实现以下任何方法(统称为HTTP谓词方法)来处理相应的HTTP方法。这些方法可以通过 async def 关键字或 gen.coroutine 装饰者。

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

若要支持不在此列表中的方法,请重写类变量 SUPPORTED_METHODS ::

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

    def propfind(self):
        pass
RequestHandler.get(*args, **kwargs) → None
RequestHandler.head(*args, **kwargs) → None
RequestHandler.post(*args, **kwargs) → None
RequestHandler.delete(*args, **kwargs) → None
RequestHandler.patch(*args, **kwargs) → None
RequestHandler.put(*args, **kwargs) → None
RequestHandler.options(*args, **kwargs) → None

输入

这个 argument 方法提供对HTML表单样式参数的支持。这些方法既可以是单数形式,也可以是复数形式,因为HTML形式不明确,并且不区分单数参数和包含一个条目的列表。如果希望使用其他格式作为参数(例如,JSON),请解析 self.request.body 你自己:

def prepare(self):
    if self.request.headers['Content-Type'] == 'application/x-json':
        self.args = json_decode(self.request.body)
    # Access self.args directly instead of using self.get_argument.
RequestHandler.get_argument(name: str, default: Union[None, str, RAISE] = RAISE, strip: bool = True) → Optional[str][源代码]

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

如果不提供默认值,则认为需要参数,并且我们提出 MissingArgumentError 如果它不见了。

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

此方法同时搜索查询和正文参数。

RequestHandler.get_arguments(name: str, strip: bool = True) → List[str][源代码]

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

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

此方法同时搜索查询和正文参数。

RequestHandler.get_query_argument(name: str, default: Union[None, str, RAISE] = RAISE, strip: bool = True) → Optional[str][源代码]

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

如果不提供默认值,则认为需要参数,并且我们提出 MissingArgumentError 如果它不见了。

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

3.2 新版功能.

RequestHandler.get_query_arguments(name: str, strip: bool = True) → List[str][源代码]

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

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

3.2 新版功能.

RequestHandler.get_body_argument(name: str, default: Union[None, str, RAISE] = RAISE, strip: bool = True) → Optional[str][源代码]

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

如果不提供默认值,则认为需要参数,并且我们提出 MissingArgumentError 如果它不见了。

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

3.2 新版功能.

RequestHandler.get_body_arguments(name: str, strip: bool = True) → List[str][源代码]

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

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

3.2 新版功能.

RequestHandler.decode_argument(value: bytes, name: Optional[str] = None) → str[源代码]

从请求中解码参数。

参数已被百分比解码,现在是一个字节字符串。默认情况下,此方法将参数解码为UTF-8并返回一个Unicode字符串,但这可能在子类中被重写。

此方法用作两者的筛选器 get_argument() 以及从URL中提取并传递给 get() [后()]。

如果已知,则提供参数的名称,但可以为“无”(例如,对于URL regex中的未命名组)。

RequestHandler.request

这个 tornado.httputil.HTTPServerRequest 包含其他请求参数的对象,例如头和正文数据。

RequestHandler.path_args
RequestHandler.path_kwargs

这个 path_argspath_kwargs 属性包含传递给 HTTP verb methods . 这些属性是在调用这些方法之前设置的,因此这些值在 prepare .

RequestHandler.data_received(chunk: bytes) → Optional[Awaitable[None]][源代码]

实现此方法以处理流式请求数据。

需要 stream_request_body 装饰者。

可能是用于流量控制的协同程序。

产量

RequestHandler.set_status(status_code: int, reason: Optional[str] = None) → None[源代码]

设置响应的状态代码。

参数
  • status_code (int) -- 响应状态代码。

  • reason (str) -- 描述状态代码的人类可读原因短语。如果 None ,将从填写 http.client.responses 或“未知”。

在 5.0 版更改: 不再验证响应代码是否在 http.client.responses .

RequestHandler.set_header(name: str, value: Union[bytes, str, numbers.Integral, datetime.datetime]) → None[源代码]

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

所有头值都转换为字符串 (datetime 对象的格式根据 Date 标题)。

RequestHandler.add_header(name: str, value: Union[bytes, str, numbers.Integral, datetime.datetime]) → None[源代码]

添加给定的响应头和值。

不像 set_headeradd_header 可以多次调用以返回同一头的多个值。

RequestHandler.clear_header(name: str) → None[源代码]

清除传出头,撤消上一个 set_header 打电话。

请注意,此方法不适用于由 add_header .

RequestHandler.set_default_headers() → None[源代码]

重写此项以在请求开始时设置HTTP头。

例如,这是设置自定义 Server 标题。请注意,在正常的请求处理流中设置这样的头可能不会满足您的需要,因为在错误处理期间头可能会被重置。

RequestHandler.write(chunk: Union[str, bytes, dict]) → None[源代码]

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

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

如果给定的块是一个字典,我们将其编写为JSON,并将响应的内容类型设置为 application/json . (如果您想以不同的方式发送JSON Content-Type ,呼叫 set_header 之后 打电话 write()

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

RequestHandler.flush(include_footers: bool = False) → Future[None][源代码]

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

这个 callback 参数(如果给定)可用于流控制:当所有刷新的数据都已写入套接字时,将运行该参数。请注意,一次只能有一个刷新回调未完成;如果在运行上一个刷新的回调之前发生了另一个刷新,则将放弃上一个回调。

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

在 6.0 版更改: 这个 callback 参数已删除。

RequestHandler.finish(chunk: Union[str, bytes, dict, None] = None) → Future[None][源代码]

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

通过A chunkfinish() 相当于将该块传递给 write() 然后打电话 finish() 没有参数。

返回A Future 它可以选择等待跟踪响应发送到客户机。这个 Future 解析发送所有响应数据的时间,并在发送所有数据之前关闭连接时引发错误。

在 5.1 版更改: 现在返回 Future 而不是 None .

RequestHandler.render(template_name: str, **kwargs) → Future[None][源代码]

以给定参数作为响应呈现模板。

render() 电话 finish() ,因此不能在后面调用其他输出方法。

返回A Future 与返回的语义相同 finish . 等待着这个 Future 是可选的。

在 5.1 版更改: 现在返回 Future 而不是 None .

RequestHandler.render_string(template_name: str, **kwargs) → bytes[源代码]

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

我们返回生成的字节字符串(以utf8格式)。要生成模板并将其编写为响应,请使用上面的render()。

RequestHandler.get_template_namespace() → Dict[str, Any][源代码]

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

可以被子类重写以添加或修改值。

此方法的结果将与 tornado.template 模块和关键字参数 renderrender_string .

RequestHandler.redirect(url: str, permanent: bool = False, status: Optional[int] = None) → None[源代码]

向给定的(可选的相对)URL发送重定向。

如果 status 参数已指定,该值将用作HTTP状态代码;否则,将根据 permanent 争论。默认值为302(临时)。

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

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

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

重写 write_error() 自定义返回的错误页。其他关键字参数传递给 write_error .

RequestHandler.write_error(status_code: int, **kwargs) → None[源代码]

重写以实现自定义错误页。

write_error 可以打电话 writerenderset_header 等以产生正常的输出。

如果此错误是由未捕获的异常(包括httperror)引起的,则 exc_info 三倍于 kwargs["exc_info"] . 请注意,对于以下方法,此异常可能不是“当前”异常 sys.exc_info()traceback.format_exc .

RequestHandler.clear() → None[源代码]

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

RequestHandler.render_linked_js(js_files: Iterable[str]) → str[源代码]

用于呈现呈现呈现网页的最终JS链接的默认方法。

在子类控制器中重写此方法以更改输出。

RequestHandler.render_embed_js(js_embed: Iterable[bytes]) → bytes[源代码]

用于呈现呈现呈现网页的最终嵌入JS的默认方法。

在子类控制器中重写此方法以更改输出。

RequestHandler.render_linked_css(css_files: Iterable[str]) → str[源代码]

用于呈现呈现呈现网页的最终CSS链接的默认方法。

在子类控制器中重写此方法以更改输出。

RequestHandler.render_embed_css(css_embed: Iterable[bytes]) → bytes[源代码]

用于呈现呈现呈现网页的最终嵌入CSS的默认方法。

在子类控制器中重写此方法以更改输出。

Cookies

RequestHandler.cookies

的别名 self.request.cookies .

返回具有给定名称的请求cookie的值。

如果指定的cookie不存在,则返回 default .

此方法只返回请求中存在的cookie。它看不到由设置的传出cookie set_cookie 在这个处理程序中。

使用给定选项设置传出cookie名称/值。

新设置的cookie不能立即通过 get_cookie 在下一次请求之前,它们不会出现。

Expires可以是由返回的数字时间戳 time.time ,返回的时间元组 time.gmtime ,或者 datetime.datetime 对象。

在cookies.morsel上直接设置其他关键字参数。有关可用属性,请参阅https://docs.python.org/3/library/http.cookies.html http.cookies.morsel。

删除具有给定名称的cookie。

由于cookie协议的限制,您必须传递相同的路径和域以清除设置cookie时使用的cookie(但无法在服务器端找到用于给定cookie的值)。

类似 set_cookie ,只有在以下请求之后才能看到此方法的效果。

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

删除用户随此请求发送的所有cookie。

clear_cookie 有关路径和域参数的详细信息。

类似 set_cookie ,只有在以下请求之后才能看到此方法的效果。

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

如果给定的签名cookie有效,则返回该cookie,或者不返回。

解码后的cookie值作为字节字符串返回(与 get_cookie

类似 get_cookie ,此方法只返回请求中存在的cookie。它看不到由设置的传出cookie set_secure_cookie 在这个处理程序中。

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

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

版本返回为int。

标记和时间戳一个cookie,这样它就不能被伪造。

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

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

请注意 expires_days 参数设置浏览器中cookie的生存期,但与 max_age_days 参数到 get_secure_cookie . 值“无”限制当前浏览器会话的生存期。

安全cookie可以包含任意字节值,而不仅仅是Unicode字符串(与常规cookie不同)

类似 set_cookie ,只有在以下请求之后才能看到此方法的效果。

在 3.2.1 版更改: 增加了 version 争论。引入了cookie版本2并将其设为默认版本。

RequestHandler.create_signed_value(name: str, value: Union[str, bytes], version: Optional[int] = None) → bytes[源代码]

符号和时间戳是一个字符串,因此它不能被伪造。

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

在 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() → bool[源代码]

检查 Etag 请求的标题 If-None-Match .

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

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 请求。如果两者不匹配,我们将拒绝提交表单,因为这可能是伪造的。

这个 _xsrf 值可以设置为名为 _xsrf 或在名为 X-XSRFTokenX-CSRFToken (后者与Django兼容)。

参见http://en.wikipedia.org/wiki/cross-site_request_forgery

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

RequestHandler.compute_etag() → Optional[str][源代码]

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

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

可以重写以提供自定义ETag实现,也可以返回none以禁用Tornado的默认ETag支持。

RequestHandler.create_template_loader(template_path: str) → tornado.template.BaseLoader[源代码]

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

可以被子类重写。默认情况下,根据给定路径返回基于目录的加载程序,使用 autoescapetemplate_whitespace 应用程序设置。如果A 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.detach() → tornado.iostream.IOStream[源代码]

控制底层流。

返回基础 IOStream 对象并停止所有进一步的HTTP处理。用于实现类似WebSockets的协议,通过HTTP握手进行隧道传输。

只有在使用HTTP/1.1时才支持此方法。

5.1 新版功能.

RequestHandler.get_browser_locale(default: str = 'en_US') → tornado.locale.Locale[源代码]

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

参见http://www.w3.org/protocols/rfc2616/rfc2616-sec14.html sec14.4

RequestHandler.get_current_user() → Any[源代码]

重写以确定当前用户,例如cookie。

此方法可能不是协程。

RequestHandler.get_login_url() → str[源代码]

重写以根据请求自定义登录URL。

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

RequestHandler.get_status() → int[源代码]

返回响应的状态代码。

RequestHandler.get_template_path() → Optional[str][源代码]

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

默认情况下,我们使用 template_path 应用程序设置。返回none以加载与调用文件相关的模板。

RequestHandler.get_user_locale() → Optional[tornado.locale.Locale][源代码]

重写以从经过身份验证的用户确定区域设置。

如果没有回报,我们就回到 get_browser_locale() .

此方法应返回 tornado.locale.Locale 对象,很可能是通过类似 tornado.locale.get("en")

RequestHandler.locale

当前会话的区域设置。

由以下两者之一决定 get_user_locale ,您可以重写它来设置基于的区域设置,例如,存储在数据库中的用户首选项,或者 get_browser_locale ,它使用 Accept-Language 标题。

RequestHandler.log_exception(typ: Optional[Type[BaseException]], value: Optional[BaseException], tb: Optional[traceback]) → None[源代码]

重写以自定义未捕获异常的日志记录。

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

3.1 新版功能.

RequestHandler.on_connection_close() → None[源代码]

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

重写此项以清除与长寿连接关联的资源。请注意,只有在异步处理期间连接关闭时才调用此方法;如果在每次请求重写后需要进行清理 on_finish 相反。

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

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

如果未定义给定的应用程序设置,则引发异常。

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

Alias Application.reverse_url .

RequestHandler.set_etag_header() → None[源代码]

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

注意:如果 compute_etag() 收益率 None .

当请求完成时,将自动调用此方法。

RequestHandler.settings

的别名 self.application.settings .

RequestHandler.static_url(path: str, include_host: Optional[bool] = None, **kwargs) → str[源代码]

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

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

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

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

RequestHandler.xsrf_form_html() → str[源代码]

一个HTML <input/> 元素将包含在所有post表单中。

它定义了 _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

此属性的类型为 bytes ,但它只包含ASCII字符。如果需要字符串,则无需base64编码;只需将字节字符串解码为utf-8。

在 3.2.2 版更改: XSRF令牌现在将在每个请求中应用一个随机屏蔽,这样可以安全地将令牌包含在压缩的页面中。有关此更改修复的问题的详细信息,请参阅http://breachattack.com。调用此方法时,旧的(版本1)cookie将转换为版本2,除非 xsrf_cookie_version Application 设置设置为1。

在 4.3 版更改: 这个 xsrf_cookie_kwargs Application setting may be used to supply additional cookie options (which will be passed directly to set_cookie). For example, xsrf_cookie_kwargs=dict(httponly=True, secure=True) will set the secure and httponly flags on the ``_ “饼干”。

应用程序配置

class tornado.web.Application(handlers: Optional[List[Union[Rule, Tuple]]] = None, default_host: Optional[str] = None, transforms: Optional[List[Type[OutputTransform]]] = None, **settings)[源代码]

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

此类的实例是可调用的,可以直接传递给httpserver以服务应用程序:

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

此类的构造函数接受 Rule 对象或值的元组对应于 Rule 构造函数: (matcher, target, [target_kwargs], [name]) ,方括号中的值是可选的。默认匹配器是 PathMatches 如此 (regexp, target) 也可以使用元组代替 (PathMatches(regexp), target) .

常见的路由目标是 RequestHandler 子类,但也可以使用规则列表作为目标,这将创建嵌套的路由配置::

application = web.Application([
    (HostMatches("example.com"), [
        (r"/", MainPageHandler),
        (r"/feed", FeedHandler),
    ]),
])

除此之外,还可以使用嵌套 Router 实例, HTTPMessageDelegate 作为路由目标的子类和可调用文件(请参见 routing 模块文档了解更多信息)。

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

字典可以作为第三个元素传递 (target_kwargs )将用作处理程序的构造函数和 initialize 方法。此模式用于 StaticFileHandler 在本例中(注意 StaticFileHandler 可以使用下面描述的静态路径设置自动安装)::

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

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

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

如果当前请求的主机不匹配,则 default_host 参数值与主机正则表达式匹配。

警告

不使用TLS的应用程序可能容易受到 DNS rebinding 攻击。这种攻击与只监听的应用程序尤其相关 127.0.0.1 或其他专用网络。必须使用适当的主机模式(而不是默认的 r'.*' )以防止这种风险。这个 default_host 参数不能用于易受DNS重新绑定攻击的应用程序。

您可以通过发送 static_path 设置为关键字参数。我们将从 /static/ URI(可通过 static_url_prefix 设置),我们将提供 /favicon.ico/robots.txt 来自同一目录。的自定义子类 StaticFileHandler 可以用指定 static_handler_class 设置。

在 4.5 版更改: 与新的 tornado.routing 模块。

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 ,将自动压缩文本格式的响应。 Tornado 4.0中的新功能。

  • gzip :的别名已弃用 compress_response 从 Tornado 4.0开始。

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

  • serve_traceback 如果 True ,默认错误页将包括错误的回溯。此选项在Tornado 3.2中是新的;以前此功能由 debug 设置。

  • ui_modulesui_methods :可以设置为 UIModule 或要提供给模板的UI方法。可以设置为模块、字典或模块和/或字典列表。见 用户界面模块 了解更多详细信息。

  • websocket_ping_interval :如果设置为数字,所有WebSocket将每N秒进行一次ping。这有助于通过关闭空闲连接的某些代理服务器保持连接的活动状态,并且可以检测WebSocket是否在未正确关闭的情况下失败。

  • websocket_ping_timeout :如果设置了ping间隔,并且服务器在这几秒钟内没有收到“pong”,则它将关闭WebSocket。默认值是ping间隔的三倍,最小值为30秒。如果未设置ping间隔,则忽略。

身份验证和安全设置:

  • cookie_secret :用于 RequestHandler.get_secure_cookieset_secure_cookie 签名 cookies。

  • key_version :由请求处理程序使用 set_secure_cookiecookie_secret 是一本关键字典。

  • 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 如果 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: Directory containing template files. Can be further customized by overriding 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 静态URL将在每个请求上重新计算。此选项在Tornado 3.2中是新的;以前此功能由 debug 设置。

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

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

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

Application.listen(port: int, address: str = '', **kwargs) → tornado.httpserver.HTTPServer[源代码]

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

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

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

返回 HTTPServer 对象。

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

Application.add_handlers(handlers: List[Union[Rule, Tuple]])[源代码]

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

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

Application.get_handler_delegate(request: tornado.httputil.HTTPServerRequest, target_class: Type[tornado.web.RequestHandler], target_kwargs: Optional[Dict[str, Any]] = None, path_args: Optional[List[bytes]] = None, path_kwargs: Optional[Dict[str, bytes]] = None) → tornado.web._HandlerDelegate[源代码]

返回 HTTPMessageDelegate 可以满足申请的请求,以及 RequestHandler 子类。

参数
  • request (httputil.HTTPServerRequest) -- 当前HTTP请求。

  • target_class (RequestHandler) -- 一 RequestHandler 班级。

  • target_kwargs (dict) -- 的关键字参数 target_class 建造师。

  • path_args (list) -- 的位置参数 target_class 处理请求时将执行的HTTP方法 (getpost 或任何其他)。

  • path_kwargs (dict) -- 的关键字参数 target_class HTTP方法。

Application.reverse_url(name: str, *args) → str[源代码]

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

必须将处理程序作为命名的 URLSpec .

args将被替换为捕获 URLSpec 正则表达式如果需要,它们将被转换为字符串,编码为utf8,并对url进行转义。

Application.log_request(handler: tornado.web.RequestHandler) → None[源代码]

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

默认情况下,写入python根记录器。若要更改此行为,请子类应用程序并重写此方法,或者将应用程序设置字典中的函数作为 log_function .

class tornado.web.URLSpec(pattern: Union[str, Pattern[~AnyStr]], handler: Any, kwargs: Optional[Dict[str, Any]] = None, name: Optional[str] = None)[源代码]

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

参数:

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

  • handlerRequestHandler 要调用的子类。

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

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

这个 URLSpec 类也可以在名称下使用 tornado.web.url .

装饰者

tornado.web.authenticated(method: Callable[..., Optional[Awaitable[None]]]) → Callable[..., Optional[Awaitable[None]]][源代码]

用这个修饰方法要求用户登录。

如果用户未登录,则会将其重定向到配置的 login url .

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

tornado.web.addslash(method: Callable[..., Optional[Awaitable[None]]]) → Callable[..., Optional[Awaitable[None]]][源代码]

使用此修饰符向请求路径添加缺少的尾随斜杠。

例如,请求 /foo 将重定向到 /foo/ 有了这个装饰。请求处理程序映射应使用类似 r'/foo/?' 配合使用装饰。

tornado.web.removeslash(method: Callable[..., Optional[Awaitable[None]]]) → Callable[..., Optional[Awaitable[None]]][源代码]

使用此修饰符从请求路径中删除尾随斜杠。

例如,请求 /foo/ 将重定向到 /foo 有了这个装饰。请求处理程序映射应使用类似 r'/foo/*' 配合使用装饰。

tornado.web.stream_request_body(cls: Type[tornado.web.RequestHandler]) → Type[tornado.web.RequestHandler][源代码]

适用于 RequestHandler 子类以启用流正文支持。

此装饰器包含以下更改:

  • HTTPServerRequest.body 未定义,正文参数将不包括在 RequestHandler.get_argument .

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

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

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

  • 常规HTTP方法 (postput 等)将在读取整个正文后调用。

file receiver demo 例如用法。

其他一切

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

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

饲养一个 HTTPError 是打电话的方便选择 RequestHandler.send_error 因为它会自动结束当前函数。

自定义发送的响应 HTTPError 重写 RequestHandler.write_error .

参数
  • status_code (int) -- HTTP状态代码。必须列在 httplib.responses 除非 reason 给出了关键字参数。

  • log_message (str) -- 要写入此错误日志的消息(除非 Application 处于调试模式)。可能含有 %s -样式占位符,将用剩余的位置参数填充。

  • reason (str) -- 仅关键字参数。要在状态行中传递的HTTP“reason”短语 status_code . 通常自动确定 status_code ,但可以使用非标准数字代码。

exception tornado.web.Finish[源代码]

结束请求而不产生错误响应的异常。

什么时候? Finish 在A中升起 RequestHandler ,请求将结束(调用 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: str)[源代码]

引发的异常 RequestHandler.get_argument .

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

3.1 新版功能.

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

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

UI模块通常执行附加查询,它们可以包含附加的CSS和javascript,这些CSS和javascript将包含在输出页中,输出页将自动插入到页面呈现中。

uimodule的子类必须重写 render 方法。

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

在子类中重写以返回此模块的输出。

embedded_javascript() → Optional[str][源代码]

重写以返回要嵌入到页面中的javascript字符串。

javascript_files() → Optional[Iterable[str]][源代码]

override返回此模块所需的javascript文件列表。

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

embedded_css() → Optional[str][源代码]

重写以返回将嵌入到页中的CSS字符串。

css_files() → Optional[Iterable[str]][源代码]

override返回此模块所需的CSS文件列表。

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

html_head() → Optional[str][源代码]

override返回将放入<head/>元素中的HTML字符串。

html_body() → Optional[str][源代码]

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

render_string(path: str, **kwargs) → bytes[源代码]

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

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

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

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

A RequestHandler 它包装了另一个HTTP服务器回调。

回退是接受 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: tornado.web.Application, request: tornado.httputil.HTTPServerRequest, **kwargs)[源代码]

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

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

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

RedirectHandler 支持正则表达式替换。例如,交换路径的第一部分和第二部分,同时保留其余部分:

application = web.Application([
    (r"/(.*?)/(.*?)/(.*)", web.RedirectHandler, {"url": "/{1}/{0}/{2}"}),
])

最终的URL格式为 str.format 以及与捕获组匹配的子字符串。在上面的示例中,“A/B/C”请求的格式如下:

str.format("/{1}/{0}/{2}", "a", "b", "c")  # -> "/b/a/c"

使用Python format string syntax 自定义值的替换方式。

在 4.5 版更改: 添加了对目标URL替换的支持。

在 5.0 版更改: 如果存在任何查询参数,它们将被复制到目标URL。

class tornado.web.StaticFileHandler(application: tornado.web.Application, request: tornado.httputil.HTTPServerRequest, **kwargs)[源代码]

一个简单的处理程序,可以为目录中的静态内容提供服务。

A StaticFileHandler 如果通过 static_path 关键字参数 Application . 此处理程序可以用 static_url_prefixstatic_handler_classstatic_handler_args 设置。

要将静态数据目录的其他路径映射到此处理程序,您需要向应用程序添加一行,如下所示:

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

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

请注意,需要regex中的捕获组来分析 path get()方法的参数(与上面的构造函数参数不同);请参见 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 .

子类应该只重写本节讨论的方法;重写其他方法很容易出错。压倒一切 StaticFileHandler.get 由于与 compute_etag 以及其他方法。

要更改生成静态URL的方式(例如,为了匹配其他服务器或cdn的行为),请重写 make_static_urlparse_url_pathget_cache_time 和/或 get_version .

要替换与文件系统的所有交互(例如,为数据库中的静态内容提供服务),请重写 get_contentget_content_sizeget_modified_timeget_absolute_pathvalidate_absolute_path .

在 3.1 版更改: Tornado3.1中添加了许多子类方法。

compute_etag() → Optional[str][源代码]

设置 Etag 基于静态URL版本的头。

这使得效率 If-None-Match 检查缓存版本,并发送正确的 Etag 对于部分响应(即相同 Etag 作为完整文件)。

3.1 新版功能.

set_headers() → None[源代码]

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

3.1 新版功能.

should_return_304() → bool[源代码]

如果标题指示应返回304,则返回true。

3.1 新版功能.

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

返回的绝对位置 path 相对 root .

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

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

3.1 新版功能.

validate_absolute_path(root: str, absolute_path: str) → Optional[str][源代码]

验证并返回绝对路径。

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

这是在请求处理期间调用的实例方法,因此它可能引发 HTTPError 或者使用类似的方法 RequestHandler.redirect (重定向后返回none以停止进一步处理)。这就是为丢失的文件生成404个错误的地方。

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

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

3.1 新版功能.

classmethod get_content(abspath: str, start: Optional[int] = None, end: Optional[int] = None) → Generator[[bytes, None], None][源代码]

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

这个类方法可以被子类重写。请注意,它的签名不同于其他可重写的类方法(否 settings 辩论);这是为了确保 abspath 能够独立作为缓存密钥。

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

3.1 新版功能.

classmethod get_content_version(abspath: str) → str[源代码]

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

这个类方法可以被子类重写。默认实现是文件内容的散列。

3.1 新版功能.

get_content_size() → int[源代码]

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

此方法可以被子类重写。

3.1 新版功能.

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

get_modified_time() → Optional[datetime.datetime][源代码]

返回 self.absolute_path 最后一次修改。

可以在子类中重写。应该归还 datetime 对象或无对象。

3.1 新版功能.

get_content_type() → str[源代码]

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

3.1 新版功能.

set_extra_headers(path: str) → None[源代码]

以便子类向响应添加额外的头

get_cache_time(path: str, modified: Optional[datetime.datetime], mime_type: str) → int[源代码]

重写以自定义缓存控件行为。

返回正数秒以使结果在该时间段内可缓存,或0以将资源标记为在未指定时间段内可缓存(取决于浏览器启发)。

默认情况下,对于使用 v 争论。

classmethod make_static_url(settings: Dict[str, Any], path: str, include_version: bool = True) → str[源代码]

为给定路径构造版本化的URL。

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

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

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

parse_url_path(url_path: str) → str[源代码]

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

url_path 是URL的路径组件 static_url_prefix 远离的。返回值应该是相对于 static_path .

这与 make_static_url .

classmethod get_version(settings: Dict[str, Any], path: str) → Optional[str][源代码]

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

settingsApplication.settings 字典和 path 是所请求资产在文件系统上的相对位置。返回的值应为字符串,或者 None 如果无法确定版本。

在 3.1 版更改: 该方法以前被推荐用于子类重写; get_content_version 现在首选,因为它允许基类处理结果的缓存。