web框架-RequestHandler和Application 類--備忘

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。

PS:本節最好直接在https://tornado-zh.readthedocs.org或者http://tornado.moelove.info/閱讀，以得到更好的閱讀體驗(格式支持)。原諒我沒排好版QAQ

http://tornado-zh.readthedocs.io/zh/latest/web.html

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

Request handlers

class tornado.web.RequestHandler(application, request, **kwargs)

HTTP請求處理的基類.

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

Entry points

RequestHandler.initialize()

子類初始化(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)),
    ])

RequestHandler.prepare()

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

經過複寫這個方法, 能夠執行共同的初始化, 而不用考慮每一個請求方法.

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

3.1 新版功能: 異步支持.

RequestHandler.on_finish()

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

複寫這個方法來執行清理, 日誌記錄等. 這個方法和 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

RequestHandler.get(*args, **kwargs)

RequestHandler.head(*args, **kwargs)

RequestHandler.post(*args, **kwargs)

RequestHandler.delete(*args, **kwargs)

RequestHandler.patch(*args, **kwargs)

RequestHandler.put(*args, **kwargs)

RequestHandler.options(*args, **kwargs)

Input

RequestHandler.get_argument(name, default=[], strip=True)

返回指定的name參數的值.

若是沒有提供默認值, 那麼這個參數將被視爲是必須的, 而且當 找不到這個參數的時候咱們會拋出一個 MissingArgumentError.

若是一個參數在url上出現屢次, 咱們返回最後一個值.

返回值永遠是unicode.

RequestHandler.get_arguments(name, strip=True)

返回指定name的參數列表.

若是參數不存在, 返回一個空列表.

返回值永遠是unicode.

RequestHandler.get_query_argument(name, default=[], strip=True)

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

若是沒有提供默認值, 這個參數將被視爲必須的, 而且當找不到這個 參數的時候咱們會拋出一個 MissingArgumentError 異常.

若是這個參數在url中屢次出現, 咱們將返回最後一次的值.

返回值永遠是unicode.

3.2 新版功能.

RequestHandler.get_query_arguments(name, strip=True)

返回指定name的參數列表.

若是參數不存在, 將返回空列表.

返回值永遠是unicode.

3.2 新版功能.

RequestHandler.get_body_argument(name, default=[], strip=True)

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

若是沒有提供默認值, 那麼這個參數將被視爲是必須的, 而且當 找不到這個參數的時候咱們會拋出一個 MissingArgumentError.

若是一個參數在url上出現屢次, 咱們返回最後一個值.

返回值永遠是unicode.

3.2 新版功能.

RequestHandler.get_body_arguments(name, strip=True)

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

若是參數不存在, 返回一個空列表.

返回值永遠是unicode.

3.2 新版功能.

RequestHandler.decode_argument(value, name=None)

從請求中解碼一個參數.

這個參數已經被解碼如今是一個字節字符串(byte string). 默認狀況下, 這個方法會把參數解碼成utf-8而且返回一個unicode字符串, 可是它能夠 被子類複寫.

這個方法既能夠在 get_argument() 中被用做過濾器, 也能夠用來從url 中提取值並傳遞給 get()/post()/等.

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

RequestHandler.request

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

RequestHandler.path_args

RequestHandler.path_kwargs

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

Output

RequestHandler.set_status(status_code, reason=None)

設置響應的狀態碼.

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

若是給定了一個datetime, 咱們會根據HTTP規範自動的對它格式化. 若是值不是一個字符串, 咱們會把它轉換成字符串. 以後全部頭部的值 都將用UTF-8 編碼.

RequestHandler.add_header(name, value)

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

不像是 set_header, add_header 能夠被屢次調用來爲相同的頭 返回多個值.

RequestHandler.clear_header(name)

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

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

RequestHandler.set_default_headers()

複寫這個方法能夠在請求開始的時候設置HTTP頭.

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

RequestHandler.write(chunk)

把給定塊寫到輸出buffer.

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

若是給定的塊是一個字典, 咱們會把它做爲JSON來寫同時會把響應頭 設置爲 application/json. (若是你寫JSON可是設置不一樣的 Content-Type, 能夠調用set_header 在調用write()以後 ).

注意列表不能轉換爲JSON 由於一個潛在的跨域安全漏洞. 全部的JSON 輸出應該包在一個字典中. 更多細節參考 http://haacked.com/archive/2009/06/25/json-hijacking.aspx/ 和 https://github.com/facebook/tornado/issues/1009

RequestHandler.flush(include_footers=False, callback=None)

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

callback 參數, 若是給定則可用於流控制: 它會在全部數據被寫到 socket後執行. 注意同一時間只能有一個flush callback停留; 若是另 一個flush在前一個flush的callback運行以前發生, 那麼前一個callback 將會被丟棄.

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

RequestHandler.finish(chunk=None)

完成響應, 結束HTTP 請求.

RequestHandler.render(template_name, **kwargs)

使用給定參數渲染模板並做爲響應.

RequestHandler.render_string(template_name, **kwargs)

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

咱們返回生成的字節字符串(以utf8). 爲了生成並寫一個模板 做爲響應, 使用上面的render().

RequestHandler.get_template_namespace()

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

能夠被子類複寫來添加或修改值.

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

RequestHandler.redirect(url, permanent=False, status=None)

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

若是指定了 status 參數, 這個值將做爲HTTP狀態碼; 不然 將經過 permanent 參數選擇301 (永久) 或者 302 (臨時). 默認是 302 (臨時重定向).

RequestHandler.send_error(status_code=500, **kwargs)

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

若是 flush() 已經被調用, 它是不可能發送錯誤的, 因此這個方法將終止 響應. 若是輸出已經被寫但還沒有flush, 它將被丟棄並被錯誤頁代替.

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

RequestHandler.write_error(status_code, **kwargs)

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

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

若是錯誤是由未捕獲的異常形成的(包括HTTPError), 三個一組的 exc_info 將變成可用的經過 kwargs["exc_info"]. 注意這個異常可能不是」當前(current)」 目的或方法的異常就像 sys.exc_info() 或 traceback.format_exc.

RequestHandler.clear()

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

RequestHandler.data_received(chunk)

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

須要 stream_request_body 裝飾器.

Cookies

RequestHandler.cookies

self.request.cookies 的別名.

RequestHandler.get_cookie(name, default=None)

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

RequestHandler.set_cookie(name, value, domain=None, expires=None, path='/', expires_days=None, **kwargs)

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

另外的關鍵字參數在Cookie.Morsel直接設置. 參見 http://docs.python.org/library/cookie.html#morsel-objects 查看可用的屬性.

RequestHandler.clear_cookie(name, path='/', domain=None)

刪除給定名稱的cookie.

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

RequestHandler.clear_all_cookies(path='/', domain=None)

刪除用戶在本次請求中全部攜帶的cookie.

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

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

RequestHandler.get_secure_cookie(name, value=None, max_age_days=31, min_version=None)

若是給定的簽名過的cookie是有效的,則返回，不然返回None.

解碼後的cookie值做爲字節字符串返回(不像 get_cookie ).

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

RequestHandler.get_secure_cookie_key_version(name, value=None)

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

返回的版本號是int型的.

RequestHandler.set_secure_cookie(name, value, expires_days=30, version=None, **kwargs)

給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 並將它做爲默認設置.

RequestHandler.create_signed_value(name, value, version=None)

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

通常經過set_secure_cookie 使用, 但對於無cookie使用來講就 做爲獨立的方法來提供. 爲了解碼不做爲cookie存儲的值, 能夠 在 get_secure_cookie 使用可選的value參數.

在 3.2.1 版更改: 添加 version 參數. 提出cookie version 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 新版功能.

Other

RequestHandler.application

爲請求提供服務的 Application 對象

RequestHandler.check_etag_header()

針對請求的 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).

RequestHandler.check_xsrf_cookie()

確認 _xsrf cookie匹配 _xsrf 參數.

爲了預防cross-site請求僞造, 咱們設置一個 _xsrf cookie和包含相同值的一個non-cookie字段在全部 POST 請求中. 若是這兩個不匹配, 咱們拒絕這個 表單提交做爲一個潛在的僞造請求.

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

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

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

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

RequestHandler.compute_etag()

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

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

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

RequestHandler.create_template_loader(template_path)

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

能夠被子類複寫. 默認返回一個在給定路徑上基於目錄的裝載器, 使用應用程序的 autoescape 和 template_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() 可能不是, 因此若是加載用戶須要異步操做後面的形式是必要的.

用戶對象能夠是application選擇的任意類型.

RequestHandler.get_browser_locale(default='en_US')

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

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

RequestHandler.get_current_user()

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

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

RequestHandler.get_login_url()

複寫這個方法自定義基於請求的登錄URL.

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

RequestHandler.get_status()

返回響應的狀態碼.

RequestHandler.get_template_path()

能夠複寫爲每一個handler指定自定義模板路徑.

默認狀況下, 咱們使用應用設置中的 template_path . 若是返回None則使用調用文件的相對路徑加載模板.

RequestHandler.get_user_locale()

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

若是返回了None , 咱們退回選擇 get_browser_locale().

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

RequestHandler.locale

返回當前session的位置.

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

RequestHandler.log_exception(typ, value, tb)

複寫來自定義未捕獲異常的日誌.

默認狀況下 HTTPError 的日誌實例做爲警告(warning)沒有堆棧追蹤(在 tornado.general logger), 其餘做爲錯誤(error)的異常帶有堆棧 追蹤(在 tornado.application logger).

3.1 新版功能.

RequestHandler.on_connection_close()

在異步處理中, 若是客戶端關閉了鏈接將會被調用.

複寫這個方法來清除與長鏈接相關的資源. 注意這個方法只有當在異步處理 鏈接被關閉纔會被調用; 若是你須要在每一個請求以後作清理, 請複寫 on_finish 方法來代替.

在客戶端離開後, 代理可能會保持鏈接一段時間 (也多是無限期), 因此這個方法在終端用戶關閉他們的鏈接時可能不會被當即執行.

RequestHandler.require_setting(name, feature='this feature')

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

RequestHandler.reverse_url(name, *args)

Application.reverse_url 的別名.

RequestHandler.set_etag_header()

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

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

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

RequestHandler.settings

self.application.settings 的別名.

RequestHandler.static_url(path, include_host=None, **kwargs)

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

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

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

默認狀況下這個方法返回當前host的相對URL, 可是若是 include_host 爲true則返回的將是絕對路徑的URL. 若是這個處理函數有一個 include_host 屬性, 該值將被全部的 static_url 調用默認使用, 而不須要傳遞 include_host 做爲一個關鍵字參數.

RequestHandler.xsrf_form_html()

一個將被包含在全部POST表單中的HTML <input/> 標籤.

它定義了咱們在全部POST請求中爲了預防僞造跨站請求所檢查的 _xsrf 的輸入值. 若是你設置了 xsrf_cookies application設置, 你必須包含這個HTML 在你全部的HTML表單.

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

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

RequestHandler.xsrf_token

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

爲了防止僞造跨站請求, 咱們設置一個 ‘_xsrf’ cookie 並在全部POST 請求中包含相同的 ‘_xsrf’ 值做爲一個參數. 若是這兩個不匹配, 咱們會把這個提交看成潛在的僞造請求而拒絕掉.

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

在 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

傳遞給構造器的附加關鍵字參數保存在 settings 字典中, 並常常在文檔中被稱爲」application settings」. Settings被用於 自定義Tornado的不少方面(雖然在一些狀況下, 更豐富的定製可能 是經過在 RequestHandler 的子類中複寫方法). 一些應用程序 也喜歡使用 settings 字典做爲使一些處理程序可使用應用 程序的特定設置的方法, 而無需使用全局變量. Tornado中使用的 Setting描述以下.

通常設置(General settings):

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 對象.

add_handlers(host_pattern, host_handlers)

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

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

reverse_url(name, *args)

返回名爲 name 的handler的URL路徑

處理程序必須做爲 URLSpec 添加到應用程序.

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

log_request(handler)

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

默認狀況下會寫到python 根(root)logger. 要改變這種行爲 不管是子類應用和複寫這個方法, 或者傳遞一個函數到應用的 設置字典中做爲 log_function.

class tornado.web.URLSpec(pattern, handler, kwargs=None, name=None)

指定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 裝飾的方法是錯誤的. 這樣的返回值以前是默認忽略的.

tornado.web.authenticated(method)

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

若是用戶未登錄, 他們將被重定向到已經配置的 login url.

若是你配置login url帶有查詢參數, Tornado將假設你知道你正在 作什麼並使用它. 若是不是, 它將添加一個 next 參數這樣登錄 頁就會知道一旦你登錄後將把你送到哪裏.

tornado.web.addslash(method)

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

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

tornado.web.removeslash(method)

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

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

tornado.web.stream_request_body(cls)

適用於 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.

其餘(Everything else)

exception tornado.web.HTTPError(status_code=500, log_message=None, *args, **kwargs)

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

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

爲了自定義 HTTPError 的響應, 複寫 RequestHandler.write_error.

參數:
status_code (int) – HTTP狀態碼. 必須列在 httplib.responses 之中除非給定了 reason 關鍵字參數.
log_message (string) – 這個錯誤將會被寫入日誌的信息(除非該 Application 是debug模式不然不會展現給用戶). 可能含有 %s-風格的佔位符, 它將填補剩餘的位置參數.
reason (string) – 惟一的關鍵字參數. HTTP 「reason」 短語 將隨着 status_code 傳遞給狀態行. 一般從 status_code, 自動肯定但可使用一個非標準的數字代碼.

exception tornado.web.Finish

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

當一個 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.

exception tornado.web.MissingArgumentError(arg_name)

由 RequestHandler.get_argument 拋出的異常.

這是 HTTPError 的一個子類, 因此若是是未捕獲的400響應碼將被 用來代替500(而且棧追蹤不會被記錄到日誌).

3.1 新版功能.

class tornado.web.UIModule(handler)

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

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

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

render(*args, **kwargs)

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

embedded_javascript()

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

javascript_files()

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

若是返回值是相對路徑, 它們將被傳遞給 RequestHandler.static_url; 不然會被原樣使用.

embedded_css()

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

css_files()

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

若是返回值是相對路徑, 它們將被傳遞給 RequestHandler.static_url; 不然會被原樣使用.

html_head()

複寫以返回一個將被放入<head/>標籤的HTML字符串.

html_body()

複寫以返回一個將被放入<body/>標籤最後的HTML字符串.

render_string(path, **kwargs)

渲染一個模板而且將它做爲一個字符串返回.

class tornado.web.ErrorHandler(application, request, **kwargs)

爲全部請求生成一個帶有 status_code 的錯誤響應.

class tornado.web.FallbackHandler(application, request, **kwargs)

包裝其餘HTTP 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),
])

class tornado.web.RedirectHandler(application, request, **kwargs)

將全部GET請求重定向到給定的URL.

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

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

class tornado.web.StaticFileHandler(application, request, **kwargs)

能夠爲一個目錄提供靜態內容服務的簡單處理程序.

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 被添加.

compute_etag()

設置 Etag 頭基於static url版本.

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

3.1 新版功能.

set_headers()

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

3.1 新版功能.

should_return_304()

若是頭部代表咱們應該返回304則返回True.

3.1 新版功能.

classmethod get_absolute_path(root, path)

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

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

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

3.1 新版功能.

validate_absolute_path(root, absolute_path)

驗證並返回絕對路徑.

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

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

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

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

3.1 新版功能.

classmethod get_content(abspath, start=None, end=None)

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

這個類方法能夠被子類複寫. 注意它的特徵不一樣於其餘可複寫 的類方法(沒有 settings 參數); 這是通過深思熟慮的以 確保 abspath 能依靠本身做爲緩存鍵(cache key) .

這個方法返回一個字節串或一個可迭代的字節串. 對於大文件 後者是更優的選擇由於它有助於減小內存碎片.

3.1 新版功能.

classmethod get_content_version(abspath)

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

這個類方法能夠被子類複寫. 默認的實現是對文件內容的hash.

3.1 新版功能.

get_content_size()

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

這個方法能夠被子類複寫.

3.1 新版功能.

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

get_modified_time()

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

能夠被子類複寫. 應當返回一個 datetime 對象或None.

3.1 新版功能.

get_content_type()

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

3.1 新版功能.

set_extra_headers(path)

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

get_cache_time(path, modified, mime_type)

複寫來自定義緩存控制行爲.

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

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

classmethod make_static_url(settings, path, include_version=True)

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

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

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

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

parse_url_path(url_path)

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

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

這是逆 make_static_url .

classmethod get_version(settings, path)

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

settings 是 Application.settings 字典而且 path 是請求資源在文件系統中的相對位置. 返回值應該是一個字符串 或 None 若是沒有版本能夠被肯定.

在 3.1 版更改: 這個方法以前建議在子類中複寫; get_content_version 如今是首選由於它容許基類來處理結果的緩存.

做者：TaoBeier連接：http://www.jianshu.com/p/61ae342efac6來源：簡書著做權歸做者全部。商業轉載請聯繫做者得到受權，非商業轉載請註明出處。