tornado.webRequestHandler and Application classes

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

有关其他信息,请参见《 用户指南 》.

Thread-safety notes

通常, RequestHandler和Tornado中其他地方的方法不是线程安全的. 特别是,必须仅从主线程调用诸如write()finish()flush() . 如果使用多个线程,则在完成请求之前,请使用IOLoop.add_callback将控制权转移回主线程,或者将其他线程的使用限制为IOLoop.run_in_executor并确保在执行程序中运行的回调不引用,这一点很重要.到龙卷风对象.

Request handlers

class tornado.web.RequestHandler(...)[source]

HTTP请求处理程序的基类.

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

应用程序不应直接构造RequestHandler对象,子类也不应覆盖__init__ (而应覆盖initialize ).

Entry points

RequestHandler.initialize() → None

钩子类初始化. 要求每个请求.

作为URLSpec的第三个参数传递的字典将作为关键字参数提供给initialize() .

Example:

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]][source]

在请求开始时在get / post / etc之前调用.

重写此方法以执行通用初始化,而不管请求方法如何.

异步支持:使用async def或用gen.coroutine装饰此方法以使其异步. 如果此方法返回了Awaitable则直到Awaitable完成,才会继续执行.

3.1版的新功能: Asynchronous support.

RequestHandler.on_finish() → None[source]

请求结束后调用.

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

实现以下任何方法(统称为HTTP动词方法)以处理相应的HTTP方法. 可以使用async def关键字或gen.coroutine装饰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

Input

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][source]

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

如果未提供default,则认为该参数是必需的,如果缺少该参数,则会引发MissingArgumentError .

如果参数在请求中多次出现,我们将返回最后一个值.

此方法同时搜索查询和主体参数.

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

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

如果不存在该参数,则返回一个空列表.

此方法同时搜索查询和主体参数.

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

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

如果未提供default,则认为该参数是必需的,如果缺少该参数,则会引发MissingArgumentError .

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

New in version 3.2.

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

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

如果不存在该参数,则返回一个空列表.

New in version 3.2.

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

从请求主体返回具有给定名称的参数的值.

如果未提供default,则认为该参数是必需的,如果缺少该参数,则会引发MissingArgumentError .

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

3.2版中的新功能.

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

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

如果不存在该参数,则返回一个空列表.

3.2版中的新功能.

RequestHandler.decode_argument(value: bytes, name: str = None) → str[source]

解码请求中的参数.

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

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

提供参数名称(如果已知),但可以为None(例如,对于url regex中的未命名组).

RequestHandler.request

tornado.httputil.HTTPServerRequest对象包含其他请求参数,例如标头和主体数据.

RequestHandler.path_args
RequestHandler.path_kwargs

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

RequestHandler.data_received(chunk: bytes) → Optional[Awaitable[None]][source]

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

需要stream_request_body装饰器.

可能是用于流量控制的协程.

Output

RequestHandler.set_status(status_code: int, reason: str = None) → None[source]

设置我们的回复状态码.

Parameters
  • status_codeint )–响应状态码.

  • 原因str )–描述状态码的人类可读原因短语. 如果为None ,则将从http.client.responses或"未知"中填写.

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

RequestHandler.set_header(name: str, value: Union[bytes, str, int, numbers.Integral, datetime.datetime]) → None[source]

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

所有标头值都将转换为字符串(根据Date标头的HTTP规范格式化datetime对象).

RequestHandler.add_header(name: str, value: Union[bytes, str, int, numbers.Integral, datetime.datetime]) → None[source]

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

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

RequestHandler.clear_header(name: str) → None[source]

清除传出标头,撤消先前的set_header调用.

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

RequestHandler.set_default_headers() → None[source]

覆盖此设置以在请求开始时设置HTTP标头.

例如,在这里设置自定义Server头. 请注意,在正常的请求处理流程中设置此类标头可能无法执行您想要的操作,因为在错误处理期间可能会重置标头.

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

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

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

如果给定的块是字典,则将其写为JSON并将响应的Content-Type设置为application/json . (如果您想将JSON作为其他Content-Type ,请调用write() 之后调用set_header ).

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

RequestHandler.flush(include_footers: bool = False) → Future[None][source]

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

如果指定了callback参数,则可将其用于流控制:将所有刷新数据写入套接字后,将运行该参数. 请注意,一次只能有一个刷新回调未完成. 如果在运行前一个刷新的回调之前发生了另一个刷新,则前一个回调将被丢弃.

在版本4.0中更改:如果未提供回调,则现在返回Future .

在版本6.0中更改: callback参数已删除.

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

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

chunk传递给finish()等同于将该块传递给write() ,然后不带任何参数调用finish() .

返回一个Future ,可以选择等待它来跟踪响应到客户端的发送. 当发送完所有响应数据后,此Future解析,如果在可以发送所有数据之前关闭了连接,则会引发错误.

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

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

使用给定的参数作为响应渲染模板.

render()调用finish() ,因此之后不能再调用其他输出方法.

返回具有与finish返回的语义相同的语义的Future . 等待这个Future是可选的.

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

RequestHandler.render_string(template_name: str, **kwargs) → bytes[source]

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

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

RequestHandler.get_template_namespace() → Dict[str, Any][source]

返回一个字典,用作默认模板名称空间.

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

该方法的结果将与tornado.template模块中的其他默认值以及用于renderrender_string关键字参数render_string .

RequestHandler.redirect(url: str, permanent: bool = False, status: int = None) → None[source]

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

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

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

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

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

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

RequestHandler.write_error(status_code: int, **kwargs) → None[source]

重写以实现自定义错误页面.

write_error可以调用writerenderset_header等来产生照常输出.

如果此错误是由于未捕获的异常(包括HTTPError)引起的,那么exc_info三元组将作为kwargs["exc_info"] . 请注意,出于类似sys.exc_info()traceback.format_exc类的方法的目的,该异常可能不是"当前"异常.

RequestHandler.clear() → None[source]

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

RequestHandler.render_linked_js(js_files: Iterable[str]) → str[source]

用于呈现所呈现网页的最终js链接的默认方法.

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

RequestHandler.render_embed_js(js_embed: Iterable[bytes]) → bytes[source]

Default method used to render the final embedded js for the rendered webpage.

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

RequestHandler.render_linked_css(css_files: Iterable[str]) → str[source]

用于呈现所渲染网页的最终css链接的默认方法.

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

RequestHandler.render_embed_css(css_embed: Iterable[bytes]) → bytes[source]

用于呈现所渲染网页的最终嵌入式CSS的默认方法.

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

Cookies

RequestHandler.cookies

self.request.cookies的别名.

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

如果命名的cookie不存在,则返回default .

此方法仅返回请求中存在的cookie. 在此处理程序中,它看不到set_cookie设置的传出Cookie.

使用给定的选项设置传出Cookie的名称/值.

通过get_cookie不能立即看到新设置的cookie; 在下一个请求之前,它们不存在.

expires可以是time.time返回的数字时间戳记, time.gmtime返回的时间元组或datetime.datetime对象.

在cookie.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: str = None) → None[source]

删除用户与此请求一起发送的所有cookie.

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

set_cookie相似,此方法的效果要到以下请求时才能看到.

在版本3.2中更改:添加了pathdomain参数.

如果验证,则返回给定的签名cookie,或者返回None.

解码后的cookie值以字节字符串形式返回(不同于get_cookie ).

get_cookie相似,此方法仅返回请求中存在的cookie. 在此处理程序中,看不到set_secure_cookie设置的传出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)

Similar to set_cookie, the effect of this method will not be seen until the following request.

在版本3.2.1中进行了更改:添加了version参数. 引入了cookie版本2并使其成为默认版本.

RequestHandler.create_signed_value(name: str, value: Union[str, bytes], version: int = None) → bytes[source]

对字符串进行签名和时间戳记,以便无法伪造.

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

在版本3.2.1中进行了更改:添加了version参数. 引入了cookie版本2并使其成为默认版本.

tornado.web.MIN_SUPPORTED_SIGNED_VALUE_VERSION = 1

此版本的Tornado支持的最早的有符号值版本.

早于该版本的签名值无法解码.

New in version 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中的新功能.

Other

RequestHandler.application

满足此请求的Application对象

RequestHandler.check_etag_header() → bool[source]

根据请求的If-None-Match检查Etag标头.

如果请求的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参数匹配.

To prevent cross-site request forgery, we set an _xsrf cookie and include the same value as a non-cookie field with all POST requests. If the two do not match, we reject the form submission as a potential forgery.

可以将_xsrf值设置为名为_xsrf的表单字段,也可以将其设置为名为X-XSRFTokenX-CSRFToken的自定义HTTP标头(为了与Django兼容而接受后者).

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

在版本3.2.2中进行了更改:添加了对cookie版本2的支持.同时支持版本1和2.

RequestHandler.compute_etag() → Optional[str][source]

计算用于此请求的etag标头.

默认情况下,使用到目前为止所写内容的哈希值.

May be overridden to provide custom etag implementations, or may return None to disable tornado’s default etag support.

RequestHandler.create_template_loader(template_path: str) → tornado.template.BaseLoader[source]

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

可以被子类覆盖. 默认情况下,使用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.detach() → tornado.iostream.IOStream[source]

控制基础流.

返回基础的IOStream对象,并停止所有进一步的HTTP处理. 旨在实现通过HTTP握手建立隧道的协议(例如,websocket).

仅当使用HTTP / 1.1时才支持此方法.

5.1版中的新功能.

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

通过Accept-Language标头确定用户的语言环境.

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

RequestHandler.get_current_user() → Any[source]

重写以从例如cookie中确定当前用户.

此方法可能不是协程.

RequestHandler.get_login_url() → str[source]

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

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

RequestHandler.get_status() → int[source]

返回我们的响应的状态码.

RequestHandler.get_template_path() → Optional[str][source]

重写以为每个处理程序定制模板路径.

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

RequestHandler.get_user_locale() → Optional[tornado.locale.Locale][source]

重写以从经过身份验证的用户确定语言环境.

如果返回None,则返回到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[source]

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

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

3.1版中的新功能.

RequestHandler.on_connection_close() → None[source]

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

覆盖此内容以清理与长期连接相关的资源. 注意,只有在异步处理过程中关闭了连接时,才调用此方法. 如果您需要在每个请求之后进行清除,请改写on_finish .

客户端离开后,代理可能会保持一段时间(可能无限期)保持打开状态,因此最终用户关闭连接后,可能不会立即调用此方法.

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

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

RequestHandler.reverse_url(name: str, *args) → str[source]

Application.reverse_url别名.

RequestHandler.set_etag_header() → None[source]

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

注意:如果compute_etag()返回None则不会设置任何标头.

请求完成后,将自动调用此方法.

RequestHandler.settings

self.application.settings的别名.

RequestHandler.static_url(path: str, include_host: bool = None, **kwargs) → str[source]

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

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

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

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

RequestHandler.xsrf_form_html() → str[source]

HTML <input/>元素将包含在所有POST表单中.

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

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

有关更多信息,请参见上面的check_xsrf_cookie() .

RequestHandler.xsrf_token

当前用户/会话的XSRF预防令牌.

为了防止跨站点请求伪造,我们设置了" _xsrf" cookie,并在所有POST请求中都包含了相同的" _xsrf"值作为参数. 如果两者不匹配,我们将表单提交视为伪造.

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

此属性的类型为bytes ,但仅包含ASCII字符. 如果需要一个字符串,则不需要对其进行base64编码. 只需将字节字符串解码为UTF-8.

在版本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标志.

Application configuration

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

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

此类的实例是可调用的,可以直接传递给HTTPServer来为应用程序提供服务:

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 Rule objects or tuples of values corresponding to the arguments of Rule constructor: (matcher, target, [target_kwargs], [name]), the values in square brackets being optional. The default matcher is PathMatches, so (regexp, target) tuples can also be used instead of (PathMatches(regexp), target).

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

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

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

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

可以将字典作为元组的第三个元素( target_kwargs )传递,它将用作处理程序的构造函数和initialize方法的关键字参数. 在此示例中,此模式用于StaticFileHandler (请注意,可以使用下面描述的static_path设置自动安装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参数值与主机正则表达式匹配.

Warning

Applications that do not use TLS may be vulnerable to DNS rebinding attacks. This attack is especially relevant to applications that only listen on 127.0.0.1 or other private networks. Appropriate host patterns must be used (instead of the default of r'.*') to prevent this risk. The default_host argument must not be used in applications that may be vulnerable to DNS rebinding.

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

在版本4.5中进行了更改:与新的tornado.routing模块集成.

settings

传递给构造函数的其他关键字参数保存在settings字典中,并且在文档中通常称为"应用程序设置". 设置用于自定义Tornado的各个方面(尽管在某些情况下,可以通过覆盖RequestHandler子类中的方法来进行更丰富的自定义). 一些应用程序还喜欢使用settings字典,以使处理程序可以使用特定于应用程序的设置,而无需使用全局变量. 在龙卷风中使用的设置如下所述.

通用设置:

  • 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 ,则将自动压缩文本格式的响应. 龙卷风4.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模块 .

  • websocket_ping_interval :如果设置为数字,则每隔n秒对所有websocket进行ping操作. 这可以帮助通过关闭空闲连接的某些代理服务器使连接保持活动状态,并且可以检测websocket是否失败而未正确关闭.

  • websocket_ping_timeout :如果设置了ping间隔,并且服务器在此秒内没有收到" pong",它将关闭websocket. 默认值为ping间隔的三倍,最少30秒. 如果未设置ping间隔,则忽略.

身份验证和安全设置:

  • 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 :可以设置为附加参数的字典,以将其传递给XSRF cookie的RequestHandler.set_cookie .

  • twitter_consumer_keytwitter_consumer_secretfriendfeed_consumer_keyfriendfeed_consumer_secretgoogle_consumer_keygoogle_consumer_secretfacebook_api_keyfacebook_secret :在tornado.auth模块中用于对各种API进行身份验证.

模板设置:

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

  • compiled_template_cache :默认为True ; 是否将在每次请求时重新编译False模板. 这个选项是Tornado 3.2中的新增功能; 以前,此功能由debug设置控制.

  • template_path :包含模板文件的目录. 可以通过重写RequestHandler.get_template_path进一步自定义

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

  • template_whitespace :控制template_whitespace中空白的处理; 有关允许的值,请参见tornado.template.filter_whitespace . 龙卷风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[source]

在给定的端口上为此应用程序启动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]])[source]

将给定的处理程序追加到我们的处理程序列表中.

主机模式按其添加顺序进行顺序处理. 将考虑所有匹配模式.

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

返回可以服务于应用程序和RequestHandler子类请求的HTTPMessageDelegate .

Parameters
  • requesthttputil.HTTPServerRequest )–当前的HTTP请求.

  • target_classRequestHandler )–一个RequestHandler类.

  • target_kwargsdict )– target_class构造函数的关键字参数.

  • path_argslist )– target_class HTTP方法的位置参数,将在处理请求( getpost或任何其他请求)时执行.

  • path_kwargsdict )– target_class HTTP方法的关键字参数.

Application.reverse_url(name: str, *args) → str[source]

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

该处理程序必须作为命名URLSpec添加到应用程序中.

Args将代替URLSpec正则表达式中的捕获组. 如有必要,它们将转换为字符串,编码为u​​tf8,并转义为url.

Application.log_request(handler: tornado.web.RequestHandler) → None[source]

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

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

class tornado.web.URLSpec(pattern: Union[str, Pattern], handler: Any, kwargs: Dict[str, Any] = None, name: str = None)[source]

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

Parameters:

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

  • handler :要调用的RequestHandler子类.

  • kwargs (可选):附加参数的字典,该参数将传递给处理程序的构造函数.

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

URLSpec类也可以在tornado.web.url下使用.

Decorators

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

以此装饰方法,要求用户登录.

如果用户未登录,他们将被重定向到配置的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: Callable[[...], Optional[Awaitable[None]]]) → Callable[[...], Optional[Awaitable[None]]][source]

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

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

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

使用此修饰符可以从请求路径中删除斜杠.

例如,对/foo/的请求将使用此装饰器重定向到/foo . 您的请求处理程序映射应与装饰器一起使用正则表达式,例如r'/foo/*' .

tornado.web.stream_request_body(cls: Type[tornado.web.RequestHandler]) → Type[tornado.web.RequestHandler][source]

应用于RequestHandler子类以启用流主体支持.

此装饰器暗含以下更改:

  • HTTPServerRequest.body是未定义的,并且主体参数将不会包含在RequestHandler.get_argument .

  • 在读取请求标头而不是在读取整个正文之后,将调用RequestHandler.prepare .

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

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

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

有关示例用法,请参见文件接收器演示 .

Everything else

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

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

引发HTTPError是调用RequestHandler.send_error一种方便的替代方法,因为它会自动结束当前函数.

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

Parameters
  • status_codeint )– HTTP状态代码. 除非给出了reason关键字参数,否则必须在httplib.responses中列出.

  • log_messagestr )–针对此错误将写入日志的消息(除非Application处于调试模式,否则不会向用户显示). 可能包含%s样式的占位符,将使用剩余的位置参数填充该占位符.

  • 原因str )–仅关键字参数. HTTP"原因"短语与status_code一起传递到状态行. 通常由status_code自动确定,但可用于使用非标准数字代码.

exception tornado.web.Finish[source]

在不产生错误响应的情况下终止请求的异常.

当在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: str)[source]

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: tornado.web.RequestHandler)[source]

页面上的可重用的模块化UI单元.

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.

UIModule的子类必须重写render方法.

render(*args, **kwargs) → str[source]

重写子类以返回此模块的输出.

embedded_javascript() → Optional[str][source]

重写以返回要嵌入在页面中的JavaScript字符串.

javascript_files() → Optional[Iterable[str]][source]

重写以返回此模块所需的JavaScript文件列表.

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

embedded_css() → Optional[str][source]

重写以返回将嵌入在页面中的CSS字符串.

css_files() → Optional[Iterable[str]][source]

重写以返回此模块所需的CSS文件列表.

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

html_head() → Optional[str][source]

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

html_body() → Optional[str][source]

重写以返回将放置在<body />元素末尾的HTML字符串.

render_string(path: str, **kwargs) → bytes[source]

渲染模板并将其作为字符串返回.

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

为所有请求生成一个带有status_code的错误响应.

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

包装另一个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: tornado.web.Application, request: tornado.httputil.HTTPServerRequest, **kwargs)[source]

将所有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"

Use Python’s format string syntax to customize how values are substituted.

在版本4.5中进行了更改: Added support for substitutions into the destination URL.

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

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

一个可以处理目录中静态内容的简单处理程序.

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

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

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 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版中进行了更改: Tornado 3.1中添加了许多子类方法.

compute_etag() → Optional[str][source]

Sets the Etag header based on static url version.

这允许针对缓存版本进行有效的If-None-Match检查,并为部分响应发送正确的Etag (即与完整文件相同的Etag ).

3.1版中的新功能.

set_headers() → None[source]

在响应上设置内容和缓存头.

3.1版中的新功能.

should_return_304() → bool[source]

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

3.1版中的新功能.

classmethod get_absolute_path(root: str, path: str) → str[source]

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

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

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

3.1版中的新功能.

validate_absolute_path(root: str, absolute_path: str) → Optional[str][source]

验证并返回绝对路径.

rootStaticFileHandler的配置路径,而pathget_absolute_path的结果

这是在请求处理期间调用的一个实例方法,因此它可能引发HTTPError或使用诸如RequestHandler.redirect方法(重定向后返回None以暂停进一步的处理). 这是生成缺少文件的404错误的地方.

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

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

3.1版中的新功能.

classmethod get_content(abspath: str, start: int = None, end: int = None) → Generator[bytes, None, None][source]

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

此类可能会被子类覆盖. 注意,它的签名不同于其他可重写的类方法(没有settings参数); 这是有意确保abspath能够独立用作缓存键.

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

3.1版中的新功能.

classmethod get_content_version(abspath: str) → str[source]

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

此类可能会被子类覆盖. 默认实现是文件内容的哈希.

New in version 3.1.

get_content_size() → int[source]

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

子类可以覆盖此方法.

3.1版中的新功能.

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

get_modified_time() → Optional[datetime.datetime][source]

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

可以在子类中覆盖. 应该返回一个datetime对象或None.

3.1版中的新功能.

get_content_type() → str[source]

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

3.1版中的新功能.

set_extra_headers(path: str) → None[source]

为子类在响应中添加额外的标头

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

重写以自定义缓存控制行为.

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

默认情况下,使用v参数请求的资源将返回10年的缓存过期时间.

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

构造给定路径的版本化url.

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

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

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

parse_url_path(url_path: str) → str[source]

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

url_path是除去了static_url_prefix的URL的路径部分. 返回值应该是相对于static_path文件系统路径.

这是make_static_url的反make_static_url .

classmethod get_version(settings: Dict[str, Any], path: str) → Optional[str][source]

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

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

在版本3.1中更改:以前建议子类重写此方法. 现在首选使用get_content_version因为它允许基类处理结果的缓存.