摘要：譯者說于年月日發布，該版本正式支持的關鍵字，并且用舊版本編譯同樣可以使用這兩個關鍵字，這無疑是一種進步。其次，這是最后一個支持和的版本了，在后續的版本了會移除對它們的兼容。本節最好直接在或者閱讀，以獲得更好的閱讀體驗格式支持。

Tornado 4.3于2015年11月6日發布，該版本正式支持Python3.5的async/await關鍵字，并且用舊版本CPython編譯Tornado同樣可以使用這兩個關鍵字，這無疑是一種進步。其次，這是最后一個支持Python2.6和Python3.2的版本了，在后續的版本了會移除對它們的兼容。現在網絡上還沒有Tornado4.3的中文文檔，所以為了讓更多的朋友能接觸并學習到它，我開始了這個翻譯項目，希望感興趣的小伙伴可以一起參與翻譯，項目地址是tornado-zh on Github，翻譯好的文檔在Read the Docs上直接可以看到。歡迎Issues or PR。

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 來把控制權傳送回主線程是很重要的.

HTTP請求處理的基類.

子類至少應該定義以下”Entry points” 部分中被定義的方法其中之一.

子類初始化(Hook).

作為url spec的第三個參數傳遞的字典, 將作為關鍵字參數提供給 initialize().

例子:

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

    def get(self, username):
        ...

app = Application([
    (r"/user/(.*)", ProfileHandler, dict(database=database)),
    ])

在每個請求的最開始被調用, 在 get/post/等方法之前.

通過復寫這個方法, 可以執行共同的初始化, 而不用考慮每個請求方法.

異步支持: 這個方法使用 gen.coroutine 或 return_future 裝飾器來使它異步( asynchronous 裝飾器不能被用在 prepare). 如果這個方法返回一個 Future 對象, 執行將不再進行, 直到 Future 對象完成.

3.1 新版功能: 異步支持.

在一個請求結束后被調用.

復寫這個方法來執行清理, 日志記錄等. 這個方法和 prepare 是相 對應的. on_finish 可能不產生任何輸出, 因為它是在響應被送 到客戶端后才被調用.

執行后面任何的方法 (統稱為HTTP 動詞(verb) 方法) 來處理相應的HTTP方法. 這些方法可以通過使用下面的裝飾器: gen.coroutine, return_future, 或 asynchronous 變成異步.

為了支持不再列表中的方法, 可以復寫類變量 SUPPORTED_METHODS:

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

    def propfind(self):
        pass

返回指定的name參數的值.

如果沒有提供默認值, 那么這個參數將被視為是必須的, 并且當 找不到這個參數的時候我們會拋出一個 MissingArgumentError.

如果一個參數在url上出現多次, 我們返回最后一個值.

返回值永遠是unicode.

返回指定name的參數列表.

如果參數不存在, 返回一個空列表.

返回值永遠是unicode.

從請求的query string返回給定name的參數的值.

如果沒有提供默認值, 這個參數將被視為必須的, 并且當找不到這個 參數的時候我們會拋出一個 MissingArgumentError 異常.

如果這個參數在url中多次出現, 我們將返回最后一次的值.

返回值永遠是unicode.

3.2 新版功能.

返回指定name的參數列表.

如果參數不存在, 將返回空列表.

返回值永遠是unicode.

3.2 新版功能.

返回請求體中指定name的參數的值.

如果沒有提供默認值, 那么這個參數將被視為是必須的, 并且當 找不到這個參數的時候我們會拋出一個 MissingArgumentError.

如果一個參數在url上出現多次, 我們返回最后一個值.

返回值永遠是unicode.

3.2 新版功能.

返回由指定請求體中指定name的參數的列表.

如果參數不存在, 返回一個空列表.

返回值永遠是unicode.

3.2 新版功能.

從請求中解碼一個參數.

這個參數已經被解碼現在是一個字節字符串(byte string). 默認情況下, 這個方法會把參數解碼成utf-8并且返回一個unicode字符串, 但是它可以 被子類復寫.

這個方法既可以在 get_argument() 中被用作過濾器, 也可以用來從url 中提取值并傳遞給 get()/post()/等.

如果知道的話參數的name會被提供, 但也可能為None (e.g. 在url正則表達式中未命名的組).

tornado.httputil.HTTPServerRequest 對象包含附加的 請求參數包括e.g. 頭部和body數據.

path_args 和 path_kwargs 屬性包含傳遞給 HTTP verb methods 的位置和關鍵字參數. 這些屬性被設置, 在這些方法被調用之前, 所以這些值 在 prepare 之間是可用的.

設置響應的狀態碼.

參數:
status_code (int) – 響應狀態碼. 如果 reason 是 None, 它必須存在于 httplib.responses.
reason (string) – 用人類可讀的原因短語來描述狀態碼. 如果是 None, 它會由來自 httplib.responses 的reason填滿.
RequestHandler.set_header(name, value)
給響應設置指定的頭部和對應的值.

如果給定了一個datetime, 我們會根據HTTP規范自動的對它格式化. 如果值不是一個字符串, 我們會把它轉換成字符串. 之后所有頭部的值 都將用UTF-8 編碼.

添加指定的響應頭和對應的值.

不像是 set_header, add_header 可以被多次調用來為相同的頭 返回多個值.

清除輸出頭, 取消之前的 set_header 調用.

注意這個方法不適用于被 add_header 設置了多個值的頭.

復寫這個方法可以在請求開始的時候設置HTTP頭.

例如, 在這里可以設置一個自定義 Server 頭. 注意在一般的 請求過程流里可能不會實現你預期的效果, 因為頭部可能在錯誤處 理(error handling)中被重置.

把給定塊寫到輸出buffer.

為了把輸出寫到網絡, 使用下面的flush()方法.

如果給定的塊是一個字典, 我們會把它作為JSON來寫同時會把響應頭 設置為 application/json. (如果你寫JSON但是設置不同的 Content-Type, 可以調用set_header 在調用write()之后 ).

注意列表不能轉換為JSON 因為一個潛在的跨域安全漏洞. 所有的JSON 輸出應該包在一個字典中. 更多細節參考 http://haacked.com/archive/20... 和 https://github.com/facebook/t...

將當前輸出緩沖區寫到網絡.

callback 參數, 如果給定則可用于流控制: 它會在所有數據被寫到 socket后執行. 注意同一時間只能有一個flush callback停留; 如果另 一個flush在前一個flush的callback運行之前發生, 那么前一個callback 將會被丟棄.

在 4.0 版更改: 現在如果沒有給定callback, 會返回一個 Future 對象.

完成響應, 結束HTTP 請求.

使用給定參數渲染模板并作為響應.

使用給定的參數生成指定模板.

我們返回生成的字節字符串(以utf8). 為了生成并寫一個模板 作為響應, 使用上面的render().

返回一個字典被用做默認的模板命名空間.

可以被子類復寫來添加或修改值.

這個方法的結果將與 tornado.template 模塊中其他的默認值 還有 render 或 render_string 的關鍵字參數相結合.

重定向到給定的URL(可以選擇相對路徑).

如果指定了 status 參數, 這個值將作為HTTP狀態碼; 否則 將通過 permanent 參數選擇301 (永久) 或者 302 (臨時). 默認是 302 (臨時重定向).

給瀏覽器發送給定的HTTP 錯誤碼.

如果 flush() 已經被調用, 它是不可能發送錯誤的, 所以這個方法將終止 響應. 如果輸出已經被寫但尚未flush, 它將被丟棄并被錯誤頁代替.

復寫 write_error() 來自定義它返回的錯誤頁. 額外的關鍵字參數將 被傳遞給 write_error.

復寫這個方法來實現自定義錯誤頁.

write_error 可能調用 write, render, set_header,等 來產生一般的輸出.

如果錯誤是由未捕獲的異常造成的(包括HTTPError), 三個一組的 exc_info 將變成可用的通過 kwargs["exc_info"]. 注意這個異?？赡懿皇恰碑斍?current)” 目的或方法的異常就像 sys.exc_info() 或 traceback.format_exc.

重置這個響應的所有頭部和內容.

實現這個方法來處理請求數據流.

需要 stream_request_body 裝飾器.

self.request.cookies 的別名.

獲取給定name的cookie值, 如果未獲取到則返回默認值.

設置給定的cookie 名稱/值還有其他給定的選項.

另外的關鍵字參數在Cookie.Morsel直接設置. 參見 https://docs.python.org/2/lib... 查看可用的屬性.

刪除給定名稱的cookie.

受cookie協議的限制, 必須傳遞和設置該名稱cookie時候相同的path 和domain來清除這個cookie(但是這里沒有方法來找出在服務端所使 用的該cookie的值).

刪除用戶在本次請求中所有攜帶的cookie.

查看 clear_cookie 方法來獲取關于path和domain參數的更多信息.

在 3.2 版更改: 添加 path 和 domain 參數.

如果給定的簽名過的cookie是有效的,則返回，否則返回None.

解碼后的cookie值作為字節字符串返回(不像 get_cookie ).

在 3.2.1 版更改: 添加 min_version 參數. 引進cookie version 2; 默認版本 1 和 2 都可以接受.

返回安全cookie(secure cookie)的簽名key版本.

返回的版本號是int型的.

給cookie簽名和時間戳以防被偽造.

你必須在你的Application設置中指定 cookie_secret 來使用這個方法. 它應該是一個長的, 隨機的字節序列作為HMAC密鑰來做簽名.

使用 get_secure_cookie() 方法來閱讀通過這個方法設置的cookie.

注意 expires_days 參數設置cookie在瀏覽器中的有效期, 并且它是 獨立于 get_secure_cookie 的 max_age_days 參數的.

安全cookie(Secure cookies)可以包含任意字節的值, 而不只是unicode 字符串(不像是普通cookie)

在 3.2.1 版更改: 添加 version 參數. 提出cookie version 2 并將它作為默認設置.

產生用時間戳簽名的字符串, 防止被偽造.

一般通過set_secure_cookie 使用, 但對于無cookie使用來說就 作為獨立的方法來提供. 為了解碼不作為cookie存儲的值, 可以 在 get_secure_cookie 使用可選的value參數.

在 3.2.1 版更改: 添加 version 參數. 提出cookie version 2 并將它作為默認設置.

這個Tornado版本所支持的最舊的簽名值版本.

比這個簽名值更舊的版本將不能被解碼.

3.2.1 新版功能.

這個Tornado版本所支持的最新的簽名值版本.

比這個簽名值更新的版本將不能被解碼.

3.2.1 新版功能.

簽名值版本通過 RequestHandler.create_signed_value 產生.

可通過傳遞一個 version 關鍵字參數復寫.

3.2.1 新版功能.

可以被 RequestHandler.get_secure_cookie 接受的最舊的簽名值.

可通過傳遞一個 min_version 關鍵字參數復寫.

3.2.1 新版功能.

為請求提供服務的 Application 對象

針對請求的 If-None-Match 頭檢查 Etag 頭.

如果請求的ETag 匹配則返回 True 并將返回一個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 參數.

為了預防cross-site請求偽造, 我們設置一個 _xsrf cookie和包含相同值的一個non-cookie字段在所有 POST 請求中. 如果這兩個不匹配, 我們拒絕這個 表單提交作為一個潛在的偽造請求.

_xsrf 的值可以被設置為一個名為 _xsrf 的表單字段或 在一個名為 X-XSRFToken 或 X-CSRFToken 的自定義 HTTP頭部(后者被接受為了兼容Django).

查看 http://en.wikipedia.org/wiki/...

發布1.1.1 之前, 這個檢查會被忽略如果當前的HTTP頭部是 X-Requested-With: XMLHTTPRequest . 這個異常已被證明是 不安全的并且已經被移除. 更多信息請查看 http://www.djangoproject.com/... http://weblog.rubyonrails.org/2011/2/8/csrf-protection-bypass-in-ruby-on-rails

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

計算被用于這個請求的etag頭.

到目前為止默認使用輸出內容的hash值.

可以被復寫來提供自定義的etag實現, 或者可以返回None來禁止 tornado 默認的etag支持.

返回給定路徑的新模板裝載器.

可以被子類復寫. 默認返回一個在給定路徑上基于目錄的裝載器, 使用應用程序的 autoescape 和 template_whitespace 設置. 如果應用設置中提供了一個 template_loader , 則使用它來替代.

返回請求中被認證的用戶.

可以使用以下兩者之一的方式來設置:

子類可以復寫 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() 可能不是, 所以如果加載用戶需要異步操作后面的形式是必要的.

用戶對象可以是application選擇的任意類型.

從 Accept-Language 頭決定用戶的位置.

參考 http://www.w3.org/Protocols/r...

復寫來實現獲取當前用戶, e.g., 從cookie得到.

這個方法可能不是一個協程.

復寫這個方法自定義基于請求的登陸URL.

默認情況下, 我們使用application設置中的 login_url 值.

返回響應的狀態碼.

可以復寫為每個handler指定自定義模板路徑.

默認情況下, 我們使用應用設置中的 template_path . 如果返回None則使用調用文件的相對路徑加載模板.

復寫這個方法確定認證過的用戶所在位置.

如果返回了None , 我們退回選擇 get_browser_locale().

這個方法應該返回一個 tornado.locale.Locale 對象, 就像調用 tornado.locale.get("en") 得到的那樣

返回當前session的位置.

通過 get_user_locale 來確定, 你可以復寫這個方法設置 獲取locale的條件, e.g., 記錄在數據庫中的用戶偏好, 或 get_browser_locale, 使用 Accept-Language 頭部.

復寫來自定義未捕獲異常的日志.

默認情況下 HTTPError 的日志實例作為警告(warning)沒有堆棧追蹤(在 tornado.general logger), 其他作為錯誤(error)的異常帶有堆棧 追蹤(在 tornado.application logger).

3.1 新版功能.

在異步處理中, 如果客戶端關閉了連接將會被調用.

復寫這個方法來清除與長連接相關的資源. 注意這個方法只有當在異步處理 連接被關閉才會被調用; 如果你需要在每個請求之后做清理, 請復寫 on_finish 方法來代替.

在客戶端離開后, 代理可能會保持連接一段時間 (也可能是無限期), 所以這個方法在終端用戶關閉他們的連接時可能不會被立即執行.

如果給定的app設置未定義則拋出一個異常.

Application.reverse_url 的別名.

設置響應的Etag頭使用 self.compute_etag() 計算.

注意: 如果 compute_etag() 返回 None 將不會設置頭.

這個方法在請求結束的時候自動調用.

self.application.settings 的別名.

為給定的相對路徑的靜態文件返回一個靜態URL.

這個方法需要你在你的應用中設置 static_path (既你 靜態文件的根目錄).

這個方法返回一個帶有版本的url (默認情況下會添加 ?v=), 這會允許靜態文件被無限期緩存. 這可以被 禁用通過傳遞 include_version=False (默認已經實現; 其他靜態文件的實現不需要支持這一點, 但它們可能支持其他選項).

默認情況下這個方法返回當前host的相對URL, 但是如果 include_host 為true則返回的將是絕對路徑的URL. 如果這個處理函數有一個 include_host 屬性, 該值將被所有的 static_url 調用默認使用, 而不需要傳遞 include_host 作為一個關鍵字參數.

一個將被包含在所有POST表單中的HTML 標簽.

它定義了我們在所有POST請求中為了預防偽造跨站請求所檢查的 _xsrf 的輸入值. 如果你設置了 xsrf_cookies application設置, 你必須包含這個HTML 在你所有的HTML表單.

在一個模板中, 這個方法應該使用 {% module xsrf_form_html() %} 這種方式調用

查看上面的 check_xsrf_cookie() 了解更多信息.

當前用戶/會話的XSRF-prevention token.

為了防止偽造跨站請求, 我們設置一個 ‘_xsrf’ cookie 并在所有POST 請求中包含相同的 ‘_xsrf’ 值作為一個參數. 如果這兩個不匹配, 我們會把這個提交當作潛在的偽造請求而拒絕掉.

查看 http://en.wikipedia.org/wiki/...

在 3.2.2 版更改: 該xsrf token現在已經在每個請求都有一個隨機mask這使得它 可以簡潔的把token包含在頁面中是安全的. 查看 http://breachattack.com 瀏覽更多信息關于這個更改修復的 問題. 舊(版本1)cookies 將被轉換到版本2 當這個方法被調用 除非 xsrf_cookie_version Application 被設置為1.

在 4.3 版更改: 該 xsrf_cookie_kwargs Application 設置可能被用來 補充額外的cookie 選項(將會直接傳遞給 set_cookie). 例如, xsrf_cookie_kwargs=dict(httponly=True, secure=True) 將設置 secure 和 httponly 標志在 _xsrf cookie.

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 對象或 (正則表達式, 請求類)元組. 當我們接收到請求, 我們按順序迭代該列表 并且實例化和請求路徑相匹配的正則表達式所對應的第一個請求類. 請求類可以被指定為一個類對象或一個(完全有資格的)名字.

每個元組可以包含另外的部分, 只要符合 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.txt 從相同目錄下. 一個 StaticFileHandler 的 自定義子類可以被指定, 通過 static_handler_class 設置.

傳遞給構造器的附加關鍵字參數保存在 settings 字典中, 并經常在文檔中被稱為”application settings”. Settings被用于 自定義Tornado的很多方面(雖然在一些情況下, 更豐富的定制可能 是通過在 RequestHandler 的子類中復寫方法). 一些應用程序 也喜歡使用 settings 字典作為使一些處理程序可以使用應用 程序的特定設置的方法, 而無需使用全局變量. Tornado中使用的 Setting描述如下.

autoreload: 如果為 True, 服務進程將會在任意資源文件 改變的時候重啟, 正如 Debug模式和自動重載 中描述的那樣. 這個選項是Tornado 3.2中新增的; 在這之前這個功能是由 debug 設置控制的.
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 模塊的根logger. 也可以通過復寫 Application.log_request 自定義.
serve_traceback: 如果為true, 默認的錯誤頁將包含錯誤信息 的回溯. 這個選項是在Tornado 3.2中新增的; 在此之前這個功能 由 debug 設置控制.
ui_modules 和 ui_methods: 可以被設置為 UIModule 或UI methods 的映射提供給模板. 可以被設置為一個模塊, 字典, 或一個模塊的列表和/或字典. 參見 UI 模塊 了解更多 細節.
認證和安全設置(Authentication and security settings):

cookie_secret: 被 RequestHandler.get_secure_cookie 使用, set_secure_cookie 用來給cookies簽名.
key_version: 被requestHandler set_secure_cookie 使用一個特殊的key給cookie簽名當 cookie_secret 是一個 key字典.
login_url: authenticated 裝飾器將會重定向到這個url 如果該用戶沒有登陸. 更多自定義特性可以通過復寫 RequestHandler.get_login_url 實現
xsrf_cookies: 如果true, 跨站請求偽造(防護) 將被開啟.
xsrf_cookie_version: 控制由該server產生的新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 模塊中使用來驗證各種APIs.
模板設置:

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_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 方法.
listen(port, address="", **kwargs)
為應用程序在給定端口上啟動一個HTTP server.

這是一個方便的別名用來創建一個 HTTPServer 對象并調用它 的listen方法. HTTPServer.listen 不支持傳遞關鍵字參數給 HTTPServer 構造器. 對于高級用途 (e.g. 多進程模式), 不要使用這個方法; 創建一個 HTTPServer 并直接調用它的 TCPServer.bind/TCPServer.start 方法.

注意在調用這個方法之后你仍然需要調用 IOLoop.current().start() 來啟動該服務.

返回 HTTPServer 對象.

在 4.3 版更改: 現在返回 HTTPServer 對象.

添加給定的handler到我們的handler表.

Host 模式將按照它們的添加順序進行處理. 所有匹配模式將被考慮.

返回名為 name 的handler的URL路徑

處理程序必須作為 URLSpec 添加到應用程序.

捕獲組的參數將在 URLSpec 的正則表達式被替換. 如有必要它們將被轉換成string, 編碼成utf8,及 網址轉義(url-escaped).

寫一個完成的HTTP 請求到日志中.

默認情況下會寫到python 根(root)logger. 要改變這種行為 無論是子類應用和復寫這個方法, 或者傳遞一個函數到應用的 設置字典中作為 log_function.

指定URL和處理程序之間的映射.

Parameters:

pattern: 被匹配的正則表達式. 任何在正則表達式的group 都將作為參數傳遞給處理程序的get/post/等方法.
handler: 被調用的 RequestHandler 子類.
kwargs (optional): 將被傳遞給處理程序構造器的額外 參數組成的字典.
name (optional): 該處理程序的名稱. 被 Application.reverse_url 使用.
URLSpec 類在 tornado.web.url 名稱下也是可用的.

裝飾器(Decorators)
tornado.web.asynchronous(method)
用這個包裝請求處理方法如果它們是異步的.

這個裝飾器適用于回調式異步方法; 對于協程, 使用 @gen.coroutine 裝飾器而沒有 @asynchronous. (這是合理的, 因為遺留原因使用兩個 裝飾器一起來提供 @asynchronous 在第一個, 但是在這種情況下 @asynchronous 將被忽略)

這個裝飾器應僅適用于 HTTP verb methods; 它的行為是未定義的對于任何其他方法. 這個裝飾器不會 使 一個方法異步; 它告訴框架該方法 是 異步(執行)的. 對于這個裝飾器, 該方法必須(至少有時)異步的做一 些事情這是有用的.

如果給定了這個裝飾器, 當方法返回的時候響應并沒有結束. 它是由請求處理程序調用 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 版更改: 可以使用 @gen.coroutine 而不需 @asynchronous.

在 4.3 版更改: 可以返回任何東西但 None 或者一個 可yield的對象來自于被 @asynchronous 裝飾的方法是錯誤的. 這樣的返回值之前是默認忽略的.

使用這個裝飾的方法要求用戶必須登陸.

如果用戶未登陸, 他們將被重定向到已經配置的 login url.

如果你配置login url帶有查詢參數, Tornado將假設你知道你正在 做什么并使用它. 如果不是, 它將添加一個 next 參數這樣登陸 頁就會知道一旦你登陸后將把你送到哪里.

使用這個裝飾器給請求路徑中添加丟失的slash.

例如, 使用了這個裝飾器請求 /foo 將被重定向到 /foo/ . 你的請求處理映射應該使用正則表達式類似 r"/foo/?" 和使用裝飾器相結合.

使用這個裝飾器移除請求路徑尾部的斜杠(slashes).

例如, 使用了這個裝飾器請求 /foo/ 將被重定向到 /foo . 你的請求處理映射應該使用正則表達式類似 r"/foo/*" 和使用裝飾器相結合.

適用于 RequestHandler 子類以開啟流式body支持.

這個裝飾器意味著以下變化:

HTTPServerRequest.body 變成了未定義, 并且body參數將不再被 RequestHandler.get_argument 所包含.
RequestHandler.prepare 被調用當讀到請求頭而不是在整個請求體 都被讀到之后.
子類必須定義一個方法 data_received(self, data):, 這將被調 用0次或多次當數據是可用狀態時. 注意如果該請求的body是空的, data_received 可能不會被調用.
prepare 和 data_received 可能返回Futures對象(就像通過 @gen.coroutine, 在這種情況下下一個方法將不會被調用直到這些 futures完成.
常規的HTTP方法 (post, put, 等)將在整個body被讀取后被 調用.
在 data_received 和asynchronous之間有一個微妙的互動 prepare: data_received 的第一次調用可能出現在任何地方 在調用 prepare 已經返回 或 yielded.

一個將會成為HTTP錯誤響應的異常.

拋出一個 HTTPError 是一個更方便的選擇比起調用 RequestHandler.send_error 因為它自動結束當前的函數.

為了自定義 HTTPError 的響應, 復寫 RequestHandler.write_error.

參數:
status_code (int) – HTTP狀態碼. 必須列在 httplib.responses 之中除非給定了 reason 關鍵字參數.
log_message (string) – 這個錯誤將會被寫入日志的信息(除非該 Application 是debug模式否則不會展示給用戶). 可能含有 %s-風格的占位符, 它將填補剩余的位置參數.
reason (string) – 唯一的關鍵字參數. HTTP “reason” 短語 將隨著 status_code 傳遞給狀態行. 通常從 status_code, 自動確定但可以使用一個非標準的數字代碼.

一個會結束請求但不會產生錯誤響應的異常.

當一個 RequestHandler 拋出 Finish , 該請求將會結束(調用 RequestHandler.finish 如果該方法尚未被調用), 但是錯誤處理方法 (包括 RequestHandler.write_error)將不會被調用.

如果 Finish() 創建的時候沒有攜帶參數, 則會發送一個pending響應. 如果 Finish() 給定了參數, 則參數將會傳遞給 RequestHandler.finish().

這是比復寫 write_error 更加便利的方式用來實現自定義錯誤頁 (尤其是在library代碼中):

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.

由 RequestHandler.get_argument 拋出的異常.

這是 HTTPError 的一個子類, 所以如果是未捕獲的400響應碼將被 用來代替500(并且棧追蹤不會被記錄到日志).

3.1 新版功能.

一個在頁面上可復用, 模塊化的UI單元.

UI模塊經常執行附加的查詢, 它們也可以包含額外的CSS和 JavaScript, 這些將包含在輸出頁面上, 在頁面渲染的時候自動插入.

UIModule的子類必須復寫 render 方法.

在子類中復寫以返回這個模塊的輸出.

復寫以返回一個被嵌入頁面的JavaScript字符串.

復寫以返回這個模塊需要的JavaScript文件列表.

如果返回值是相對路徑, 它們將被傳遞給 RequestHandler.static_url; 否則會被原樣使用.

復寫以返回一個將被嵌入頁面的CSS字符串.

復寫以返回這個模塊需要的CSS文件列表.

如果返回值是相對路徑, 它們將被傳遞給 RequestHandler.static_url; 否則會被原樣使用.

復寫以返回一個將被放入標簽的HTML字符串.

復寫以返回一個將被放入標簽最后的HTML字符串.

渲染一個模板并且將它作為一個字符串返回.

為所有請求生成一個帶有 status_code 的錯誤響應.

包裝其他HTTP server回調的 RequestHandler .

fallback是一個可調用的對象, 它接收一個 HTTPServerRequest, 諸如一個 Application 或 tornado.wsgi.WSGIContainer. 這對于在相同server中同時使用 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),
])

將所有GET請求重定向到給定的URL.

你需要為處理程序提供 url 關鍵字參數, e.g.:

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

可以為一個目錄提供靜態內容服務的簡單處理程序.

StaticFileHandler 是自動配置的如果你傳遞了 static_path 關鍵字參數給 Application. 這個處理程序可以被自定義通過 static_url_prefix, static_handler_class, 和 static_handler_args 配置.

為了將靜態數據目錄映射一個額外的路徑給這個處理程序你可以在你應用程序中 添加一行例如:

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

處理程序構造器需要一個 path 參數, 該參數指定了將被服務內容的本地根 目錄.

注意在正則表達式的捕獲組需要解析 path 參數的值給get()方法(不同于 上面的構造器的參數); 參見 URLSpec 了解細節.

為了自動的提供一個文件例如 index.html 當一個目錄被請求的時候, 設置 static_handler_args=dict(default_filename="index.html") 在你的應用程序設置中(application settings), 或添加 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生成的方式(e.g. 匹配其他服務或CDN), 復寫 make_static_url, parse_url_path, get_cache_time, 和/或 get_version.

為了代替所有與文件系統的相互作用(e.g. 從數據庫提供靜態內容服務), 復寫 get_content, get_content_size, get_modified_time, get_absolute_path, 和 validate_absolute_path.

在 3.1 版更改: 一些為子類設計的方法在Tornado 3.1 被添加.

設置 Etag 頭基于static url版本.

這允許高效的針對緩存版本的 If-None-Match 檢查, 并發送正確的 Etag 給局部的響應(i.e. 相同的 Etag 為完整的文件).

3.1 新版功能.

設置響應的內容和緩存頭.

3.1 新版功能.

如果頭部表明我們應該返回304則返回True.

3.1 新版功能.

返回 path 相對于 root 的絕對路徑.

root 是這個 StaticFileHandler 配置的路徑(在大多數情 況下是 Application 的 static_path 設置).

這個類方法可能在子類中被復寫. 默認情況下它返回一個文件系統 路徑, 但其他字符串可以被使用, 只要它們是獨特的并且被 子類復寫的 get_content 理解.

3.1 新版功能.

驗證并返回絕對路徑.

root 是 StaticFileHandler 配置的路徑,并且 path 是 get_absolute_path 的結果.

這是一個實例方法在請求過程中被調用, 所以它可能拋出 HTTPError 或者使用類似 RequestHandler.redirect (返回None在重定向到停止進一步處理之后) 這種方法. 如果丟失文件將會生成404錯誤.

這個方法可能在返回路徑之前修改它, 但是注意任何這樣的 修改將不會被 make_static_url 理解.

在實例方法, 這個方法的結果對 self.absolute_path 是可用的.

3.1 新版功能.

檢索位于所給定絕對路徑的請求資源的內容.

這個類方法可以被子類復寫. 注意它的特征不同于其他可復寫 的類方法(沒有 settings 參數); 這是經過深思熟慮的以 確保 abspath 能依靠自己作為緩存鍵(cache key) .

這個方法返回一個字節串或一個可迭代的字節串. 對于大文件 后者是更優的選擇因為它有助于減少內存碎片.

3.1 新版功能.

返回給定路徑資源的一個版本字符串.

這個類方法可以被子類復寫. 默認的實現是對文件內容的hash.

3.1 新版功能.

檢索給定路徑中資源的總大小.

這個方法可以被子類復寫.

3.1 新版功能.

在 4.0 版更改: 這個方法總是被調用, 而不是僅在部分結果被請求時.

返回 self.absolute_path 的最后修改時間.

可以被子類復寫. 應當返回一個 datetime 對象或None.

3.1 新版功能.

返回這個請求使用的 Content-Type 頭.

3.1 新版功能.

為了子類給響應添加額外的頭部

復寫來自定義緩存控制行為.

返回一個正的秒數作為結果可緩存的時間的量或者返回0標記資源 可以被緩存一個未指定的時間段(受瀏覽器自身的影響).

默認情況下帶有 v 請求參數的資源返回的緩存過期時間是10年.

為給定路徑構造一個的有版本的url.

這個方法可以在子類中被復寫(但是注意他是一個類方法而不是一個 實例方法). 子類只需實現簽名 make_static_url(cls, settings, path); 其他關鍵字參數可 以通過 static_url 傳遞, 但這不是標準.

settings 是 Application.settings 字典. path 是被請求的靜態路徑. 返回的url應該是相對于當前host的.

include_version 決定生成的URL是否應該包含含有給定 path 相對應文件的hash版本查詢字符串.

將靜態URL路徑轉換成文件系統路徑.

url_path 是由去掉 static_url_prefix 的URL組成. 返回值應該是相對于 static_path 的文件系統路徑.

這是逆 make_static_url .

生成用于靜態URL的版本字符串.

settings 是 Application.settings 字典并且 path 是請求資源在文件系統中的相對位置. 返回值應該是一個字符串 或 None 如果沒有版本可以被確定.

在 3.1 版更改: 這個方法之前建議在子類中復寫; get_content_version 現在是首選因為它允許基類來處理結果的緩存.