`tornado.web` — `RequestHandler` 和 `Application` 類別¶

tornado.web 提供一個簡單的 web 框架，具有非同步功能，使其能夠擴展到大量開啟的連線，非常適合長輪詢。

這是一個簡單的「Hello, world」範例應用程式

import asyncio
import tornado

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        self.write("Hello, world")

async def main():
    application = tornado.web.Application([
        (r"/", MainHandler),
    ])
    application.listen(8888)
    await asyncio.Event().wait()

if __name__ == "__main__":
    asyncio.run(main())

請參閱使用者指南以取得更多資訊。

執行緒安全注意事項¶

一般而言，RequestHandler 和 Tornado 中其他地方的方法不是執行緒安全的。特別是，諸如 write()、finish() 和 flush() 之類的方法必須只能從主執行緒呼叫。如果您使用多個執行緒，請務必使用 IOLoop.add_callback 將控制權轉回主執行緒，然後再完成請求，或是將您使用其他執行緒的限制為 IOLoop.run_in_executor，並確保在 executor 中執行的回呼不會參照 Tornado 物件。

請求處理器¶

class tornado.web.RequestHandler(...)[原始碼]¶

HTTP 請求處理器的基底類別。

子類別必須至少定義以下「進入點」章節中定義的方法之一。

應用程式不應直接建構 RequestHandler 物件，並且子類別不應覆寫 __init__ （應覆寫 initialize）。

進入點¶

RequestHandler.initialize() → None¶

用於子類別初始化的 Hook。針對每個請求呼叫。

作為 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/ post/等等之前，於請求開始時呼叫。

覆寫此方法以執行與請求方法無關的通用初始化。

非同步支援：使用 async def 或以 gen.coroutine 修飾此方法，使其成為非同步方法。如果此方法傳回 Awaitable，則在 Awaitable 完成之前，不會繼續執行。

3.1 版本新增: 非同步支援。

RequestHandler.on_finish() → None[原始碼]¶

在請求結束後呼叫。

覆寫此方法以執行清理、記錄等。此方法與 prepare 相對應。on_finish 可能不會產生任何輸出，因為它是在將回應傳送到用戶端之後呼叫的。

實作下列任何方法（統稱為 HTTP 動詞方法）以處理對應的 HTTP 方法。這些方法可以使用 async def 關鍵字或 gen.coroutine 修飾器設為非同步。

這些方法的引數來自 URLSpec：正規表示式中的任何擷取群組都會成為 HTTP 動詞方法的引數（如果群組已命名則為關鍵字引數，如果未命名則為位置引數）。

若要支援此清單中沒有的方法，請覆寫類別變數 SUPPORTED_METHODS

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

    def propfind(self):
        pass

RequestHandler.get(*args: str, **kwargs: str) → None¶

RequestHandler.head(*args: str, **kwargs: str) → None¶

RequestHandler.post(*args: str, **kwargs: str) → None¶

RequestHandler.delete(*args: str, **kwargs: str) → None¶

RequestHandler.patch(*args: str, **kwargs: str) → None¶

RequestHandler.put(*args: str, **kwargs: str) → None¶

RequestHandler.options(*args: str, **kwargs: str) → None¶

輸入¶

argument 方法提供對 HTML 表單樣式參數的支援。這些方法有單數和複數形式，因為 HTML 表單語意不明確，無法區分單個參數和包含一個條目的清單。如果您想使用其他格式的參數（例如 JSON），請自行解析 self.request.body。

def prepare(self):
    if self.request.headers['Content-Type'] == 'application/x-json':
        self.args = json_decode(self.request.body)
    # Access self.args directly instead of using self.get_argument.

RequestHandler.get_argument(name: str, default: str, strip: bool = True) → str[原始碼]¶

RequestHandler.get_argument(name: str, default: _ArgDefaultMarker = _ARG_DEFAULT, strip: bool = True) → str

RequestHandler.get_argument(name: str, default: None, strip: bool = True) → Optional[str]

傳回具有指定名稱的參數值。

如果未提供 default，則該參數被視為必要參數，如果缺少該參數，我們會引發 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][source]¶

從請求查詢字串中，返回具有指定名稱的參數值。

如果未提供 default，則該參數被視為必要參數，如果缺少該參數，我們會引發 MissingArgumentError。

如果該參數在 URL 中出現多次，則返回最後一個值。

3.2 版本新增。

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

返回具有指定名稱的查詢參數列表。

如果參數不存在，則傳回空清單。

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: Optional[str] = None) → str[source]¶

解碼請求中的參數。

該參數已進行百分比解碼，現在是位元組字串。預設情況下，此方法會將參數解碼為 utf-8 並返回一個 unicode 字串，但這可以在子類別中被覆寫。

此方法用作 get_argument() 和從 URL 中提取並傳遞給 get()/post()/等的數值的篩選器。

如果已知參數的名稱，則會提供該名稱，但可能為 None（例如，對於 URL 正則表達式中的未命名群組）。

RequestHandler.request¶: 包含其他請求參數的 tornado.httputil.HTTPServerRequest 物件，包括例如標頭和主體資料。

RequestHandler.path_args¶

RequestHandler.path_kwargs¶: path_args 和 path_kwargs 屬性包含傳遞給HTTP 動詞方法的位置和關鍵字參數。這些屬性會在調用這些方法之前設定，因此這些值在 prepare 期間可用。

RequestHandler.data_received(chunk: bytes) → Optional[Awaitable[None]][原始碼]¶

實作此方法以處理串流的請求資料。

需要使用 stream_request_body 修飾器。

可以是協程 (coroutine) 以進行流程控制。

輸出¶

RequestHandler.set_status(status_code: int, reason: Optional[str] = None) → None[原始碼]¶

設定回應的狀態碼。

參數

status_code (int) – 回應狀態碼。
reason (str) – 描述狀態碼的可讀原因短語。如果為 None，則會從 http.client.responses 或 “Unknown” 中填入。

變更於 5.0 版本: 不再驗證回應碼是否在 http.client.responses 中。

RequestHandler.set_header(name: str, value: Union[bytes, str, int, Integral, datetime]) → None[原始碼]¶

設定指定的回應標頭名稱和值。

所有標頭值都會轉換為字串（datetime 物件會根據 HTTP 規範針對 Date 標頭進行格式化）。

RequestHandler.add_header(name: str, value: Union[bytes, str, int, Integral, 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，並將回應的 Content-Type 設定為 application/json。(如果您想以不同的 Content-Type 傳送 JSON，請在呼叫 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][原始碼]¶: 將目前的輸出緩衝區刷新到網路。

變更於 4.0 版: 如果沒有提供回呼函式，現在會回傳一個 Future。

變更於 6.0 版: 移除了 callback 參數。

RequestHandler.finish(chunk: Optional[Union[str, bytes, dict]] = None) → Future[None][原始碼]¶

結束此回應，並結束 HTTP 請求。

傳遞一個 chunk 給 finish() 等同於將該 chunk 傳遞給 write()，然後呼叫不帶任何參數的 finish()。

回傳一個 Future，該 Future 可以選擇性地等待以追蹤將回應傳送到用戶端的情況。當所有回應資料都已傳送時，此 Future 會解析，如果連線在所有資料可以傳送之前關閉，則會引發錯誤。

變更於 5.1 版: 現在回傳一個 Future 而不是 None。

RequestHandler.render(template_name: str, **kwargs: Any) → Future[None][原始碼]¶

以給定的引數呈現範本作為回應。

render() 會呼叫 finish()，因此在其之後無法呼叫其他輸出方法。

回傳一個 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 引數選擇 301 (永久) 或 302 (暫時)。預設值為 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.clear() → None[原始碼]¶: 重設此回應的所有標頭和內容。

RequestHandler.render_linked_js(js_files: Iterable[str]) → str[原始碼]¶

用於呈現已呈現網頁的最終 js 連結的預設方法。

在子類別化的控制器中覆寫此方法以變更輸出。

RequestHandler.render_embed_js(js_embed: Iterable[bytes]) → bytes[原始碼]¶

用於呈現已呈現網頁的最終嵌入式 js 的預設方法。

在子類別化的控制器中覆寫此方法以變更輸出。

RequestHandler.render_linked_css(css_files: Iterable[str]) → str[原始碼]¶

用於呈現已呈現網頁的最終 css 連結的預設方法。

在子類別化的控制器中覆寫此方法以變更輸出。

RequestHandler.render_embed_css(css_embed: Iterable[bytes]) → bytes[原始碼]¶

用於呈現已呈現網頁的最終嵌入式 css 的預設方法。

在子類別化的控制器中覆寫此方法以變更輸出。

Cookie¶

RequestHandler.cookies¶: 為 self.request.cookies 的別名。

RequestHandler.get_cookie(name: str, default: Optional[str] = None) → Optional[str][原始碼]¶

傳回具有指定名稱的請求 Cookie 的值。

如果指定的 Cookie 不存在，則傳回 default。

此方法只傳回請求中存在的 Cookie。它看不到此處理程式中由 set_cookie 設定的傳出 Cookie。

RequestHandler.set_cookie(name: str, value: Union[str, bytes], domain: Optional[str] = None, expires: Optional[Union[float, Tuple, datetime]] = None, path: str = '/', expires_days: Optional[float] = None, *, max_age: Optional[int] = None, httponly: bool = False, secure: bool = False, samesite: Optional[str] = None, **kwargs: Any) → None[原始碼]¶

使用給定的選項設定一個外送的 Cookie 名稱/值。

新設定的 Cookie 不會立即透過 get_cookie 看到；它們在下一次請求之前不會出現。

大多數參數會直接傳遞給 http.cookies.Morsel。有關更多資訊，請參閱 https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie。

expires 可以是由 time.time 返回的數值時間戳記，由 time.gmtime 返回的時間元組，或 datetime.datetime 物件。expires_days 作為方便設定從今天起算的天數到期時間提供（如果兩者都設定，則使用 expires）。

自 6.3 版起已棄用: 關鍵字參數目前接受不區分大小寫。在 Tornado 7.0 中，這將更改為僅接受小寫參數。

RequestHandler.clear_cookie(name: str, **kwargs: Any) → None[原始碼]¶

刪除具有給定名稱的 Cookie。

此方法接受與 set_cookie 相同的參數，但 expires 和 max_age 除外。清除 Cookie 需要與設定時相同的 domain 和 path 參數。在某些情況下，還需要匹配 samesite 和 secure 參數。其他參數會被忽略。

與 set_cookie 類似，此方法的效果將在下一個請求之前不會看到。

變更於 6.3 版: 現在接受 set_cookie 接受的所有關鍵字參數。最近，清除 samesite="none" Cookie 必須使用 samesite 和 secure 標誌。

RequestHandler.clear_all_cookies(**kwargs: Any) → None[原始碼]¶

嘗試刪除使用者隨此請求傳送的所有 Cookie。

請參閱 clear_cookie 以了解關於關鍵字參數的更多資訊。由於 cookie 協定的限制，伺服器端無法判斷 domain、path、samesite 或 secure 參數所需的確切值。因此，只有在設定 cookie 時始終使用相同的值，此方法才能成功。

與 set_cookie 類似，此方法的效果將在下一個請求之前不會看到。

版本變更自 3.2: 新增了 path 和 domain 參數。

版本變更自 6.3: 現在接受所有 set_cookie 接受的關鍵字參數。

自版本 6.3 起已棄用: 由於 cookie 的規則日益複雜，clear_all_cookies 方法已無法可靠地運作，因為我們只知道 cookie 的名稱。應用程式一般應改為一次使用一個 clear_cookie。

RequestHandler.get_signed_cookie(name: str, value: Optional[str] = None, max_age_days: float = 31, min_version: Optional[int] = None) → Optional[bytes][原始碼]¶

如果驗證成功，則返回給定的簽名 cookie，否則返回 None。

解碼後的 cookie 值將以位元組字串的形式返回（與 get_cookie 不同）。

與 get_cookie 類似，此方法只返回請求中存在的 cookie。它看不到此處理常式中由 set_signed_cookie 設定的傳出 cookie。

版本變更自 3.2.1

新增了 min_version 參數。引入了 cookie 版本 2；預設情況下接受版本 1 和版本 2。

版本變更自 6.3: 為了避免與 cookie 屬性和前綴中「secure」的其他用法混淆，從 get_secure_cookie 重新命名為 get_signed_cookie。舊名稱仍保留為別名。

RequestHandler.get_signed_cookie_key_version(name: str, value: Optional[str] = None) → Optional[int][原始碼]¶

返回安全 cookie 的簽名金鑰版本。

該版本以整數形式返回。

版本變更自 6.3: 為了避免與 cookie 屬性和前綴中「secure」的其他用法混淆，從 get_secure_cookie_key_version 重新命名為 set_signed_cookie_key_version。舊名稱仍保留為別名。

RequestHandler.set_signed_cookie(name: str, value: Union[str, bytes], expires_days: Optional[float] = 30, version: Optional[int] = None, **kwargs: Any) → None[原始碼]¶

對 cookie 進行簽名並加上時間戳記，使其無法被偽造。

您必須在應用程式中指定 cookie_secret 設定，才能使用此方法。它應該是一長串隨機的位元組序列，用作簽名的 HMAC 密碼。

要讀取使用此方法設定的 cookie，請使用 get_signed_cookie()。

請注意，expires_days 參數設定 cookie 在瀏覽器中的存續期，但獨立於 get_signed_cookie 的 max_age_days 參數。值為 None 會將存續期限制為目前的瀏覽器工作階段。

安全 cookie 可能包含任意位元組值，而不僅僅是 Unicode 字串（與一般 cookie 不同）

與 set_cookie 類似，此方法的效果將在下一個請求之前不會看到。

版本變更自 3.2.1: 新增了 version 參數。引入了 cookie 版本 2，並將其設為預設值。

版本變更自 6.3: 為了避免與 cookie 屬性和前綴中「secure」的其他用法混淆，從 set_secure_cookie 重新命名為 set_signed_cookie。舊名稱仍保留為別名。

RequestHandler.get_secure_cookie()¶: get_signed_cookie 的已棄用別名。

自版本 6.3 起已棄用。

RequestHandler.get_secure_cookie_key_version()¶: get_signed_cookie_key_version 的已棄用別名。

自版本 6.3 起已棄用。

RequestHandler.set_secure_cookie()¶: set_signed_cookie 的已棄用別名。

自版本 6.3 起已棄用。

RequestHandler.create_signed_value(name: str, value: Union[str, bytes], version: Optional[int] = None) → bytes[原始碼]¶

簽署並加上時間戳記字串，使其無法被偽造。

通常透過 set_signed_cookie 使用，但為了非 cookie 用途而提供作為獨立方法。要解碼未儲存為 cookie 的值，請使用 get_signed_cookie 的選用值引數。

版本變更自 3.2.1: 新增了 version 參數。引入了 cookie 版本 2，並將其設為預設值。

tornado.web.MIN_SUPPORTED_SIGNED_VALUE_VERSION = 1¶

此 Tornado 版本支援的最舊簽署值版本。

無法解碼早於此版本的簽署值。

3.2.1 版本新增。

tornado.web.MAX_SUPPORTED_SIGNED_VALUE_VERSION = 2¶

此 Tornado 版本支援的最新簽署值版本。

無法解碼晚於此版本的簽署值。

3.2.1 版本新增。

tornado.web.DEFAULT_SIGNED_VALUE_VERSION = 2¶

由 RequestHandler.create_signed_value 產生的簽署值版本。

可以透過傳遞 version 關鍵字引數來覆寫。

3.2.1 版本新增。

tornado.web.DEFAULT_SIGNED_VALUE_MIN_VERSION = 1¶

由 RequestHandler.get_signed_cookie 接受的最舊簽署值。

可以透過傳遞 min_version 關鍵字引數來覆寫。

3.2.1 版本新增。

其他¶

RequestHandler.application¶: 為此請求提供服務的 Application 物件

RequestHandler.check_etag_header() → bool[原始碼]¶

檢查 Etag 標頭是否與請求的 If-None-Match 相符。

如果請求的 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）。

RequestHandler.check_xsrf_cookie() → None[原始碼]¶

驗證 _xsrf cookie 是否與 _xsrf 引數相符。

為了防止跨網站請求偽造，我們設定一個 _xsrf cookie，並在所有 POST 請求中包含相同的值作為非 cookie 欄位。如果兩者不符，我們會拒絕表單提交，因為這可能是潛在的偽造行為。

_xsrf 值可以設定為名為 _xsrf 的表單欄位，或是在名為 X-XSRFToken 或 X-CSRFToken 的自訂 HTTP 標頭中（後者是為了與 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) → BaseLoader[原始碼]¶

傳回指定路徑的新範本載入器。

子類別可以覆寫。預設情況下，會使用應用程式設定中的 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_signed_cookie("user")
    if user_cookie:
        return json.loads(user_cookie)
    return None
```

它可以設定為普通變數，通常來自覆寫的 prepare()

@gen.coroutine
def prepare(self):
    user_id_cookie = self.get_signed_cookie("user_id")
    if user_id_cookie:
        self.current_user = yield load_user(user_id_cookie)

請注意，prepare() 可以是協程，而 get_current_user() 可能不是，因此如果載入使用者需要非同步操作，則必須採用後者形式。

使用者物件可以是應用程式選擇的任何類型。

RequestHandler.detach() → IOStream[原始碼]¶

取得對基礎串流的控制權。

傳回基礎的 IOStream 物件並停止所有進一步的 HTTP 處理。適用於實作透過 HTTP 交握建立通道的協定，例如 websocket。

只有在使用 HTTP/1.1 時才支援此方法。

5.1 版本新增。

RequestHandler.get_browser_locale(default: str = 'en_US') → Locale[原始碼]¶

從 Accept-Language 標頭判斷使用者的語言環境。

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

RequestHandler.get_current_user() → Any[原始碼]¶

覆寫此方法以從 Cookie 等方式判斷目前使用者。

此方法不得為協程。

RequestHandler.get_login_url() → str[原始碼]¶

覆寫此方法以根據請求自訂登入 URL。

預設情況下，我們使用應用程式設定中的 login_url。

RequestHandler.get_status() → int[原始碼]¶: 傳回回應的狀態碼。

RequestHandler.get_template_path() → Optional[str][原始碼]¶

覆寫此方法以自訂每個處理常式的範本路徑。

預設情況下，我們使用應用程式設定中的 template_path。傳回 None 以載入相對於呼叫檔案的範本。

RequestHandler.get_user_locale() → Optional[Locale][原始碼]¶

覆寫此方法以從已驗證的使用者判斷語言環境。

如果傳回 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[TracebackType]) → None[原始碼]¶

覆寫此方法以自訂未捕獲異常的記錄。

預設情況下，會將 HTTPError 的實例記錄為警告，不包含堆疊追蹤（在 tornado.general 記錄器上），而所有其他異常則記錄為錯誤，並包含堆疊追蹤（在 tornado.application 記錄器上）。

3.1 版新增。

RequestHandler.on_connection_close() → None[原始碼]¶

如果用戶端關閉連線，則在非同步處理常式中呼叫。

覆寫此方法以清除與長時間連線相關的資源。請注意，只有在非同步處理期間關閉連線時才會呼叫此方法；如果您需要在每次請求後進行清除，請改為覆寫 on_finish。

在用戶端斷線後，Proxy 可能會將連線保持開啟一段時間（可能無限期），因此此方法可能不會在終端使用者關閉連線後立即呼叫。

RequestHandler.require_setting(name: str, feature: str = 'this feature') → None[原始碼]¶: 如果未定義指定的應用程式設定，則擲回例外。

RequestHandler.reverse_url(name: str, *args: Any) → str[原始碼]¶: 為 Application.reverse_url 的別名。

RequestHandler.set_etag_header() → None[原始碼]¶

使用 self.compute_etag() 設定回應的 Etag 標頭。

注意：如果 compute_etag() 回傳 None，則不會設定任何標頭。

此方法會在請求完成時自動呼叫。

RequestHandler.settings¶: 為 self.application.settings 的別名。

RequestHandler.static_url(path: str, include_host: Optional[bool] = None, **kwargs: Any) → str[原始碼]¶

為給定的相對靜態檔案路徑回傳靜態 URL。

此方法需要您在應用程式中設定 static_path 設定（指定靜態檔案的根目錄）。

此方法回傳版本化的 URL（預設附加 ?v=<簽章>），這允許無限期地快取靜態檔案。這可以透過傳遞 include_version=False 來停用（在預設實作中；其他靜態檔案實作不一定支援此功能，但它們可能支援其他選項）。

預設情況下，此方法會回傳相對於目前主機的 URL，但是如果 include_host 為 true，則回傳的 URL 將會是絕對的。如果此處理器具有 include_host 屬性，則該值將用作所有不將 include_host 作為關鍵字引數傳遞的 static_url 呼叫的預設值。

RequestHandler.xsrf_form_html() → str[原始碼]¶

要包含在所有 POST 表單中的 HTML <input/> 元素。

它定義了 _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。當呼叫此方法時，除非將 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 上設定 secure 和 httponly 旗標。

應用程式組態¶

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)

此類別的建構子會接收一個 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 模組文件）。

當我們收到請求時，我們會依序迭代列表，並實例化第一個正規表示式與請求路徑匹配的請求類別的實例。請求類別可以指定為類別物件或（完整限定的）名稱。

字典可以作為元組的第三個元素（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 參數值與主機正規表示式進行匹配。

警告

未使用 TLS 的應用程式可能容易受到 DNS 重綁定攻擊。此攻擊對於僅監聽 127.0.0.1 或其他私有網路的應用程式尤其相關。必須使用適當的主機模式（而不是預設的 r'.*'）來防止此風險。default_host 參數不得用於可能容易受到 DNS 重綁定的應用程式中。

您可以透過傳送 static_path 設定作為關鍵字參數來提供靜態檔案。我們將從 /static/ URI 提供這些檔案（這可以使用 static_url_prefix 設定進行配置），並且我們將從同一目錄提供 /favicon.ico 和 /robots.txt。可以使用 static_handler_class 設定指定 StaticFileHandler 的自訂子類別。

在 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：自 Tornado 4.0 起，已棄用的 compress_response 別名。
log_function：此函式將在每個請求結束時呼叫以記錄結果（帶有一個參數，RequestHandler 物件）。預設實作會寫入 logging 模組的根記錄器。也可以透過覆寫 Application.log_request 進行自訂。
serve_traceback：如果為 True，則預設錯誤頁面將包含錯誤的回溯。此選項在 Tornado 3.2 中是新的；以前此功能由 debug 設定控制。
ui_modules 和 ui_methods：可以設定為要提供給範本的 UIModule 或 UI 方法的對應。可以設定為模組、字典或模組和/或字典的列表。有關更多詳細資訊，請參閱 UI 模組。
websocket_ping_interval：如果設定為數字，則所有 websocket 將每 n 秒 ping 一次。這有助於透過某些關閉閒置連線的 Proxy 伺服器保持連線作用，並且可以檢測 websocket 是否已失敗而未正確關閉。
websocket_ping_timeout：如果設定了 ping 間隔，並且伺服器在此時間內未收到「pong」，則會關閉 websocket。預設值為 ping 間隔的三倍，最小為 30 秒。如果未設定 ping 間隔，則會忽略此設定。

驗證和安全設定

cookie_secret：由 RequestHandler.get_signed_cookie 和 set_signed_cookie 用於簽署 Cookie。
key_version：由 requestHandler set_signed_cookie 使用，當 cookie_secret 為金鑰字典時，使用特定的金鑰簽署 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：可以設定為一個字典，其中包含要傳遞給 RequestHandler.set_cookie 的額外參數，用於 XSRF Cookie。
xsrf_cookie_name：控制用於 XSRF Cookie 的名稱（預設為 _xsrf）。預期的用途是利用 Cookie 前綴。請注意，Cookie 前綴會與其他 Cookie 標誌互動，因此它們必須與 xsrf_cookie_kwargs 結合使用，例如 {"xsrf_cookie_name": "__Host-xsrf", "xsrf_cookie_kwargs": {"secure": True}}。
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 以停用跳脫，或設定為所有輸出應通過的函式名稱。預設為 "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 方法。

Application.listen(port: int, address: Optional[str] = None, *, family: AddressFamily = AddressFamily.AF_UNSPEC, backlog: int = 128, flags: Optional[int] = None, reuse_port: bool = False, **kwargs: Any) → HTTPServer[原始碼]¶

在給定的端口上為此應用程式啟動 HTTP 伺服器。

這是建立 HTTPServer 物件並呼叫其 listen 方法的便捷別名。HTTPServer.listen 不支援的關鍵字引數會傳遞給 HTTPServer 建構函式。對於進階用法（例如，多程序模式），請勿使用此方法；建立 HTTPServer 並直接呼叫其 TCPServer.bind/TCPServer.start 方法。

請注意，在呼叫此方法後，您仍然需要呼叫 IOLoop.current().start()（或在 asyncio.run 中執行）才能啟動伺服器。

傳回 HTTPServer 物件。

在 4.3 版本中變更：現在傳回 HTTPServer 物件。

在 6.2 版本中變更：新增了對 TCPServer.listen 中新的關鍵字引數的支援，包括 reuse_port。

Application.add_handlers(handlers: List[Union[Rule, Tuple]])[原始碼]¶

將給定的處理常式附加到我們的處理常式清單。

主機模式會按照新增的順序依序處理。所有匹配的模式都會被考慮。

Application.get_handler_delegate(request: HTTPServerRequest, target_class: Type[RequestHandler], target_kwargs: Optional[Dict[str, Any]] = None, path_args: Optional[List[bytes]] = None, path_kwargs: Optional[Dict[str, bytes]] = None) → _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[原始碼]¶

返回名為 name 的處理器的 URL 路徑。

該處理器必須以命名的 URLSpec 加入到應用程式中。

引數將被替換為 URLSpec 正則表示式中的捕獲群組。它們將在必要時轉換為字串，編碼為 utf8，並進行 URL 跳脫。

Application.log_request(handler: RequestHandler) → None[原始碼]¶

將已完成的 HTTP 請求寫入日誌。

預設情況下，寫入 Python 根記錄器。若要變更此行為，請子類化 Application 並覆寫此方法，或在應用程式設定字典中傳入一個函式作為 log_function。

class tornado.web.URLSpec(pattern: Union[str, Pattern], handler: Any, kwargs: Optional[Dict[str, Any]] = None, name: Optional[str] = None)[原始碼]¶

指定 URL 和處理器之間的對應關係。

參數

pattern: 要匹配的正規表示式。正規表示式中的任何捕獲群組都將作為引數傳遞到處理器的 get/post/等方法 (如果是命名群組則按關鍵字傳遞，如果是不命名群組則按位置傳遞。命名和不命名的捕獲群組不能在同一個規則中混合使用)。
handler: 要呼叫的 RequestHandler 子類別。
kwargs (可選): 要傳遞給處理器建構子的其他引數字典。
name (可選): 此處理器的名稱。由 reverse_url 使用。

URLSpec 類別也可透過名稱 tornado.web.url 取得。

裝飾器¶

tornado.web.authenticated(method: Callable[[...], Optional[Awaitable[None]]]) → Callable[[...], Optional[Awaitable[None]]][原始碼]¶

使用此裝飾器裝飾方法，以要求使用者必須登入。

如果使用者未登入，他們將被重新導向至設定的 登入網址。

如果您使用查詢參數設定登入網址，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[_RequestHandlerType]) → Type[_RequestHandlerType][原始碼]¶

套用至 RequestHandler 子類別以啟用串流主體支援。

此裝飾器表示以下變更

HTTPServerRequest.body 未定義，且主體引數將不會包含在 RequestHandler.get_argument 中。
RequestHandler.prepare 會在讀取請求標頭後 (而不是在讀取完整主體後) 呼叫。
子類別必須定義方法 data_received(self, data):，當有資料可用時，此方法將會被呼叫零次或多次。請注意，如果請求具有空的主體，則可能不會呼叫 data_received。
prepare 和 data_received 可能會傳回 Futures（例如透過 @gen.coroutine），在這種情況下，在這些 futures 完成之前，不會呼叫下一個方法。
在讀取完整主體後，將會呼叫一般 HTTP 方法 (post、put 等)。

如需範例用法，請參閱檔案接收器示範。

其他所有內容¶

例外 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) – 僅限關鍵字的引數。要與 status_code 一起傳遞到狀態行的 HTTP「原因」短語。通常從 status_code 自動判斷，但可以用於使用非標準的數值程式碼。

例外 tornado.web.Finish[來源]¶

此例外會結束請求，而不會產生錯誤回應。

當在 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。

例外 tornado.web.MissingArgumentError(arg_name: str)[來源]¶

由 RequestHandler.get_argument 引發的例外。

這是 HTTPError 的子類別，因此如果未捕獲，則會使用 400 回應碼，而不是 500（且不會記錄堆疊追蹤）。

3.1 版新增。

類別 tornado.web.UIModule(handler: RequestHandler)[來源]¶

頁面上可重複使用、模組化的 UI 單元。

UI 模組通常會執行額外的查詢，它們可以包含額外的 CSS 和 JavaScript，這些 CSS 和 JavaScript 將包含在輸出頁面中，並在頁面呈現時自動插入。

UIModule 的子類別必須覆寫 render 方法。

render(*args: Any, **kwargs: Any) → str[來源]¶: 在子類別中覆寫以傳回此模組的輸出。

embedded_javascript() → Optional[str][來源]¶: 覆寫以傳回要嵌入在頁面中的 JavaScript 字串。

javascript_files() → Optional[Iterable[str]][來源]¶

覆寫以傳回此模組所需的 JavaScript 檔案清單。

如果傳回值是相對路徑，則它們將傳遞給 RequestHandler.static_url；否則它們將按原樣使用。

embedded_css() → Optional[str][來源]¶: 覆寫此方法以回傳將嵌入頁面中的 CSS 字串。

css_files() → Optional[Iterable[str]][原始碼]¶

覆寫此方法以回傳此模組所需的 CSS 檔案列表。

如果傳回值是相對路徑，則它們將傳遞給 RequestHandler.static_url；否則它們將按原樣使用。

html_head() → Optional[str][原始碼]¶: 覆寫此方法以回傳將放在 <head/> 元素中的 HTML 字串。

html_body() → Optional[str][原始碼]¶: 覆寫此方法以回傳將放在 <body/> 元素結尾的 HTML 字串。

render_string(path: str, **kwargs: Any) → bytes[原始碼]¶: 渲染範本並將其回傳為字串。

class tornado.web.ErrorHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[原始碼]¶: 針對所有請求，產生一個帶有 status_code 的錯誤回應。

class tornado.web.FallbackHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[原始碼]¶

一個 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: Application, request: 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 的格式字串語法來自訂如何替換值。

在 4.5 版本中變更: 新增了對在目標 URL 中進行替換的支援。

在 5.0 版本中變更: 如果存在任何查詢引數，它們將會複製到目標 URL。

class tornado.web.StaticFileHandler(application: Application, request: HTTPServerRequest, **kwargs: Any)[原始碼]¶

一個簡單的處理常式，可以從目錄提供靜態內容。

如果您將 static_path 關鍵字引數傳遞至 Application，就會自動設定 StaticFileHandler。可以使用 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")，或為您的 StaticFileHandler 加入 default_filename 作為初始化引數。

為了最大化瀏覽器快取的有效性，此類別支援版本化的 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 版本中變更：Tornado 3.1 中新增了許多子類別的方法。

compute_etag() → Optional[str][原始碼]¶

根據靜態 URL 版本設定 Etag 標頭。

這允許針對快取的版本進行有效的 If-None-Match 檢查，並為部分回應傳送正確的 Etag（即與完整檔案相同的 Etag）。

3.1 版新增。

set_headers() → None[原始碼]¶: 在回應上設定內容和快取標頭。

3.1 版新增。

should_return_304() → bool[原始碼]¶: 如果標頭指出我們應傳回 304，則傳回 True。

3.1 版新增。

classmethod get_absolute_path(root: str, path: str) → str[原始碼]¶

傳回相對於 root 的 path 絕對位置。

root 是為此 StaticFileHandler 設定的路徑（在大多數情況下為 static_path Application 設定）。

此類別方法可以在子類別中覆寫。預設情況下，它會傳回檔案系統路徑，但只要它們是唯一的並且子類別的覆寫 get_content 可以理解，就可以使用其他字串。

3.1 版新增。

validate_absolute_path(root: str, absolute_path: str) → Optional[str][原始碼]¶

驗證並傳回絕對路徑。

root 是 StaticFileHandler 的設定路徑，而 path 是 get_absolute_path 的結果

這是在請求處理期間呼叫的實例方法，因此它可能會引發 HTTPError 或使用諸如 RequestHandler.redirect 之類的方法（在重新導向後傳回 None 以停止進一步處理）。這是在這裡產生遺失檔案的 404 錯誤。

此方法可能會在傳回路徑之前修改路徑，但請注意，make_static_url 將無法理解任何此類修改。

在實例方法中，此方法的結果可作為 self.absolute_path 使用。

3.1 版新增。

classmethod get_content(abspath: str, start: Optional[int] = None, end: Optional[int] = None) → Generator[bytes, None, None][原始碼]¶

擷取位於指定絕對路徑的請求資源內容。

此類別方法可由子類別覆寫。請注意，其簽名與其他可覆寫的類別方法不同（沒有 settings 引數）；這是刻意為之，以確保 abspath 可以獨立作為快取鍵。

此方法應傳回位元組字串或位元組字串的迭代器。後者對於大型檔案較佳，因為它有助於減少記憶體片段化。

3.1 版新增。

classmethod get_content_version(abspath: str) → str[原始碼]¶

傳回指定路徑資源的版本字串。

此類別方法可由子類別覆寫。預設實作是檔案內容的 SHA-512 雜湊值。

3.1 版新增。

get_content_size() → int[原始碼]¶

擷取指定路徑資源的總大小。

此方法可由子類別覆寫。

3.1 版新增。

變更於 4.0 版: 此方法現在總是會被呼叫，而不是僅在請求部分結果時才會呼叫。

get_modified_time() → Optional[datetime][原始碼]¶

傳回 self.absolute_path 最後修改的時間。

可在子類別中覆寫。應傳回 datetime 物件或 None。

3.1 版新增。

變更於 6.4 版: 現在傳回的是感知日期時間物件，而不是單純的日期時間物件。覆寫此方法的子類別可以傳回這兩種物件的其中一種。

get_content_type() → str[原始碼]¶: 傳回此請求要使用的 Content-Type 標頭。

3.1 版新增。

set_extra_headers(path: str) → None[原始碼]¶: 供子類別將額外標頭加入至回應中

get_cache_time(path: str, modified: Optional[datetime], mime_type: str) → int[原始碼]¶

覆寫以自訂快取控制行為。

傳回正數表示快取結果的時間長度（以秒為單位），或傳回 0 表示將資源標示為快取一段未指定的時間（取決於瀏覽器啟發式演算法）。

預設會為帶有 v 引數請求的資源傳回 10 年的快取到期時間。

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 是否應包含查詢字串，其中包含與指定 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，因為它允許基底類別處理結果的快取。

tornado.web — RequestHandler 和 Application 類別¶

執行緒安全注意事項¶

請求處理器¶

進入點¶

輸入¶

輸出¶

Cookie¶

其他¶

應用程式組態¶

裝飾器¶

其他所有內容¶

`tornado.web` — `RequestHandler` 和 `Application` 類別¶