tornado.web
--- RequestHandler
和 Application
班¶
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
输入¶
这个 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: str, strip: bool = True) str [源代码]¶
- RequestHandler.get_argument(name: str, default: tornado.web._ArgDefaultMarker = _ARG_DEFAULT, strip: bool = True) str
- RequestHandler.get_argument(name: str, default: None, 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_args
和path_kwargs
属性包含传递给 HTTP verb methods . 这些属性是在调用这些方法之前设置的,因此这些值在prepare
.
产量¶
- 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, int, numbers.Integral, datetime.datetime]) None [源代码]¶
设置给定的响应头名称和值。
所有头值都转换为字符串 (
datetime
对象的格式根据Date
标题)。
- RequestHandler.add_header(name: str, value: Union[bytes, str, int, numbers.Integral, datetime.datetime]) None [源代码]¶
添加给定的响应头和值。
不像
set_header
,add_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
. (如果您想以不同的方式发送JSONContent-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] [源代码]¶
将当前输出缓冲区刷新到网络。
在 4.0 版更改: 现在返回
Future
如果没有回调。在 6.0 版更改: 这个
callback
参数已删除。
- RequestHandler.finish(chunk: Optional[Union[str, bytes, dict]] = None) Future[None] [源代码]¶
完成此响应,结束HTTP请求。
通过A
chunk
到finish()
相当于将该块传递给write()
然后打电话finish()
没有参数。返回A
Future
它可以选择等待跟踪响应发送到客户机。这个Future
解析发送所有响应数据的时间,并在发送所有数据之前关闭连接时引发错误。在 5.1 版更改: 现在返回
Future
而不是None
.
- RequestHandler.render(template_name: str, **kwargs: Any) Future[None] [源代码]¶
以给定参数作为响应呈现模板。
render()
电话finish()
,因此不能在后面调用其他输出方法。返回A
Future
与返回的语义相同finish
. 等待着这个Future
是可选的。在 5.1 版更改: 现在返回
Future
而不是None
.
- RequestHandler.render_string(template_name: str, **kwargs: Any) bytes [源代码]¶
用给定的参数生成给定的模板。
我们返回生成的字节字符串(以utf8格式)。要生成模板并将其编写为响应,请使用上面的render()。
- RequestHandler.get_template_namespace() Dict[str, Any] [源代码]¶
返回要用作默认模板命名空间的字典。
可以被子类重写以添加或修改值。
此方法的结果将与
tornado.template
模块和关键字参数render
或render_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: Any) None [源代码]¶
将给定的HTTP错误代码发送到浏览器。
如果
flush()
已经被调用,无法发送错误,因此此方法只会终止响应。如果输出已写入但尚未刷新,则将丢弃该输出并替换为错误页。重写
write_error()
自定义返回的错误页。其他关键字参数传递给write_error
.
- RequestHandler.write_error(status_code: int, **kwargs: Any) None [源代码]¶
重写以实现自定义错误页。
write_error
可以打电话write
,render
,set_header
等以产生正常的输出。如果此错误是由未捕获的异常(包括httperror)引起的,则
exc_info
三倍于kwargs["exc_info"]
. 请注意,对于以下方法,此异常可能不是“当前”异常sys.exc_info()
或traceback.format_exc
.
- RequestHandler.render_linked_js(js_files: Iterable[str]) str [源代码]¶
用于呈现呈现呈现网页的最终JS链接的默认方法。
在子类控制器中重写此方法以更改输出。
- RequestHandler.render_embed_js(js_embed: Iterable[bytes]) bytes [源代码]¶
用于呈现呈现呈现网页的最终嵌入JS的默认方法。
在子类控制器中重写此方法以更改输出。
其他¶
- 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
)在调用此方法之前。
- RequestHandler.check_xsrf_cookie() None [源代码]¶
验证
_xsrf
cookie匹配_xsrf
参数。为了防止跨站点请求伪造,我们设置了
_xsrf
并包含与非cookie字段相同的值POST
请求。如果两者不匹配,我们将拒绝提交表单,因为这可能是伪造的。这个
_xsrf
值可以设置为名为_xsrf
或在名为X-XSRFToken
或X-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 [源代码]¶
返回给定路径的新模板加载程序。
可以被子类重写。默认情况下,根据给定路径返回基于目录的加载程序,使用
autoescape
和template_whitespace
应用程序设置。如果Atemplate_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_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[types.TracebackType]) 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.set_etag_header() None [源代码]¶
使用设置响应的etag头
self.compute_etag()
.注意:如果
compute_etag()
收益率None
.当请求完成时,将自动调用此方法。
- RequestHandler.settings¶
- RequestHandler.static_url(path: str, include_host: Optional[bool] = None, **kwargs: Any) 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 toset_cookie
). For example,xsrf_cookie_kwargs=dict(httponly=True, secure=True)
will set thesecure
andhttponly
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=True
,compiled_template_cache=False
,static_hash_cache=False
,serve_traceback=True
.default_handler_class
和default_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_modules
和ui_methods
:可以设置为UIModule
或要提供给模板的UI方法。可以设置为模块、字典或模块和/或字典列表。见 用户界面模块 了解更多详细信息。websocket_ping_interval
:如果设置为数字,所有WebSocket将每N秒进行一次ping。这有助于通过关闭空闲连接的某些代理服务器保持连接的活动状态,并且可以检测WebSocket是否在未正确关闭的情况下失败。websocket_ping_timeout
:如果设置了ping间隔,并且服务器在这几秒钟内没有收到“pong”,则它将关闭WebSocket。默认值是ping间隔的三倍,最小值为30秒。如果未设置ping间隔,则忽略。
身份验证和安全设置:
cookie_secret
:用于RequestHandler.get_secure_cookie
和set_secure_cookie
签名 cookies。key_version
:由请求处理程序使用set_secure_cookie
当cookie_secret
是一本关键字典。login_url
: Theauthenticated
decorator will redirect to this url if the user is not logged in. Can be further customized by overridingRequestHandler.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_key
,twitter_consumer_secret
,friendfeed_consumer_key
,friendfeed_consumer_secret
,google_consumer_key
,google_consumer_secret
,facebook_api_key
,facebook_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 overridingRequestHandler.get_template_path
template_loader
:分配给的实例tornado.template.BaseLoader
自定义模板加载。如果使用此设置,template_path
和autoescape
设置被忽略。可以通过重写进一步自定义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_class
,static_handler_args
:可以设置为对静态文件使用不同的处理程序,而不是默认的tornado.web.StaticFileHandler
.static_handler_args
如果设置,则应是要传递给处理程序的关键字参数的字典。initialize
方法。
- Application.listen(port: int, address: str = '', **kwargs: Any) 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方法 (get
,post
或任何其他)。path_kwargs (dict) -- 的关键字参数
target_class
HTTP方法。
- Application.reverse_url(name: str, *args: Any) 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], handler: Any, kwargs: Optional[Dict[str, Any]] = None, name: Optional[str] = None)[源代码]¶
指定URL和处理程序之间的映射。
参数:
pattern
:要匹配的正则表达式。regex中的任何捕获组都将作为参数传入处理程序的get/post/etc方法(如果已命名,则按关键字,如果未命名,则按位置)。命名和未命名的捕获组不能在同一规则中混合)。handler
:RequestHandler
要调用的子类。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._RequestHandlerType]) Type[tornado.web._RequestHandlerType] [源代码]¶
适用于
RequestHandler
子类以启用流正文支持。此装饰器包含以下更改:
HTTPServerRequest.body
未定义,正文参数将不包括在RequestHandler.get_argument
.RequestHandler.prepare
在读取请求头时调用,而不是在读取整个主体之后调用。子类必须定义一个方法
data_received(self, data):
,当数据可用时,将被称为零次或更多次。请注意,如果请求的主体为空,data_received
不能调用。prepare
和data_received
可以退回期货(如VIA@gen.coroutine
在这种情况下,下一个方法将不会被调用,直到这些期货完成。常规HTTP方法 (
post
,put
等)将在读取整个正文后调用。
见 file receiver demo 例如用法。
其他一切¶
- exception tornado.web.HTTPError(status_code: int = 500, log_message: Optional[str] = None, *args: Any, **kwargs: Any)[源代码]¶
将变成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
方法。- javascript_files() Optional[Iterable[str]] [源代码]¶
override返回此模块所需的javascript文件列表。
如果返回值是相对路径,它们将被传递到
RequestHandler.static_url
否则将按原样使用。
- class tornado.web.ErrorHandler(application: tornado.web.Application, request: tornado.httputil.HTTPServerRequest, **kwargs: Any)[源代码]¶
生成错误响应
status_code
所有请求。
- class tornado.web.FallbackHandler(application: tornado.web.Application, request: tornado.httputil.HTTPServerRequest, **kwargs: Any)[源代码]¶
A
RequestHandler
它包装了另一个HTTP服务器回调。回退是接受
HTTPServerRequest
,比如Application
或tornado.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: Any)[源代码]¶
将客户端重定向到所有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: Any)[源代码]¶
一个简单的处理程序,可以为目录中的静态内容提供服务。
A
StaticFileHandler
如果通过static_path
关键字参数Application
. 此处理程序可以用static_url_prefix
,static_handler_class
和static_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_path
和self.modified
.子类应该只重写本节讨论的方法;重写其他方法很容易出错。压倒一切
StaticFileHandler.get
由于与compute_etag
以及其他方法。要更改生成静态URL的方式(例如,为了匹配其他服务器或cdn的行为),请重写
make_static_url
,parse_url_path
,get_cache_time
和/或get_version
.要替换与文件系统的所有交互(例如,为数据库中的静态内容提供服务),请重写
get_content
,get_content_size
,get_modified_time
,get_absolute_path
和validate_absolute_path
.在 3.1 版更改: Tornado3.1中添加了许多子类方法。
- compute_etag() Optional[str] [源代码]¶
设置
Etag
基于静态URL版本的头。这使得效率
If-None-Match
检查缓存版本,并发送正确的Etag
对于部分响应(即相同Etag
作为完整文件)。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 theStaticFileHandler
, andpath
is the result ofget_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 [源代码]¶
返回给定路径下资源的版本字符串。
这个类方法可以被子类重写。默认实现是文件内容的SHA-512散列。
3.1 新版功能.
- get_content_size() int [源代码]¶
在给定路径检索资源的总大小。
此方法可以被子类重写。
3.1 新版功能.
在 4.0 版更改: 现在总是调用此方法,而不是只在请求部分结果时调用。
- get_modified_time() Optional[datetime.datetime] [源代码]¶
返回
self.absolute_path
最后一次修改。可以在子类中重写。应该归还
datetime
对象或无对象。3.1 新版功能.
- 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
但不是标准的。settings
是Application.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中使用的版本字符串。
settings
是Application.settings
字典和path
是所请求资产在文件系统上的相对位置。返回的值应为字符串,或者None
如果无法确定版本。在 3.1 版更改: 该方法以前被推荐用于子类重写;
get_content_version
现在首选,因为它允许基类处理结果的缓存。