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

詳細については、ユーザーズガイドを参照してください。

スレッド安全性に関する注意点

一般的に、Tornado の RequestHandler およびその他の場所にあるメソッドはスレッドセーフではありません。特に、write()、finish()、flush() などのメソッドは、メインスレッドからのみ呼び出す必要があります。複数のスレッドを使用する場合は、リクエストを終了する前に IOLoop.add_callback を使用して制御をメインスレッドに戻すか、他のスレッドの使用を IOLoop.run_in_executor に制限し、Executor で実行されるコールバックが Tornado オブジェクトを参照しないようにすることが重要です。

リクエストハンドラー

class tornado.web.RequestHandler(...)[ソース]

HTTP リクエストハンドラーのベースクラスです。

サブクラスは、以下の「エントリポイント」セクションで定義されているメソッドの少なくとも 1 つを定義する必要があります。

アプリケーションは RequestHandler オブジェクトを直接構築するべきではなく、サブクラスは __init__ をオーバーライドするべきではありません（代わりに initialize をオーバーライドしてください）。

エントリポイント

RequestHandler.initialize() → None

サブクラスの初期化のためのフックです。各リクエストに対して呼び出されます。

URLSpec の 3 番目の引数として渡された辞書は、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フォームがあいまいであり、単一の引数と1つのエントリを含むリストを区別しないためです。引数に他の形式（例えば、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][ソース]

リクエストのクエリ文字列から、指定された名前の引数の値を返します。

default が提供されていない場合、引数は必須とみなされ、欠落している場合は 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][ソース]

リクエストボディから、指定された名前の引数の値を返します。

default が提供されていない場合、引数は必須とみなされ、欠落している場合は 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 としてデコードし、ユニコード文字列を返しますが、これはサブクラスでオーバーライドできます。

このメソッドは、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 デコレータが必要です。

フロー制御のためにコルーチンにすることができます。

出力

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 オブジェクトは Date ヘッダーの HTTP 仕様に従ってフォーマットされます）。

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 に設定します。（JSONを別の Content-Type で送信したい場合は、write() を呼び出した後に set_header を呼び出してください。）

リストはクロスサイトセキュリティの脆弱性の可能性があるため、JSONに変換されないことに注意してください。すべてのJSON出力は辞書でラップする必要があります。詳細については、http://haacked.com/archive/2009/06/25/json-hijacking.aspx/ および https://github.com/facebook/tornado/issues/1009 を参照してください。

RequestHandler.flush(include_footers: bool = False) → Future[None][ソース]

現在の出力バッファをネットワークにフラッシュします。

バージョン 4.0 で変更: コールバックが指定されていない場合、Future を返すようになりました。

バージョン 6.0 で変更: callback 引数が削除されました。

RequestHandler.finish(chunk: Optional[Union[str, bytes, dict]] = None) → Future[None][ソース]

このレスポンスを終了し、HTTPリクエストを終了します。

chunk を finish() に渡すことは、そのチャンクを write() に渡してから、引数なしで finish() を呼び出すことと同じです。

クライアントへのレスポンスの送信を追跡するために、必要に応じて待機できる Future を返します。この Future は、すべてのレスポンスデータが送信されたときに解決され、すべてのデータを送信する前に接続が閉じられた場合はエラーが発生します。

バージョン 5.1 で変更: None の代わりに Future を返すようになりました。

RequestHandler.render(template_name: str, **kwargs: Any) → Future[None][ソース]

与えられた引数を使用してテンプレートをレスポンスとしてレンダリングします。

render() は finish() を呼び出すため、その後は他の出力メソッドを呼び出すことはできません。

finish によって返されるものと同じセマンティクスを持つ Future を返します。この Future の待機はオプションです。

バージョン 5.1 で変更: None の代わりに Future を返すようになりました。

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[ソース]

レンダリングされたWebページ用の最終的なjsリンクをレンダリングするために使用されるデフォルトのメソッド。

出力を変更するには、サブクラス化されたコントローラーでこのメソッドをオーバーライドします。

RequestHandler.render_embed_js(js_embed: Iterable[bytes]) → bytes[ソース]

レンダリングされたWebページ用の最終的な埋め込みjsをレンダリングするために使用されるデフォルトのメソッド。

出力を変更するには、サブクラス化されたコントローラーでこのメソッドをオーバーライドします。

RequestHandler.render_linked_css(css_files: Iterable[str]) → str[ソース]

レンダリングされたWebページ用の最終的なcssリンクをレンダリングするために使用されるデフォルトのメソッド。

出力を変更するには、サブクラス化されたコントローラーでこのメソッドをオーバーライドします。

RequestHandler.render_embed_css(css_embed: Iterable[bytes]) → bytes[ソース]

レンダリングされたWebページ用の最終的な埋め込みcssをレンダリングするために使用されるデフォルトのメソッド。

出力を変更するには、サブクラス化されたコントローラーでこのメソッドをオーバーライドします。

クッキー

RequestHandler.cookies

self.request.cookiesのエイリアスです。

指定された名前のリクエストクッキーの値を返します。

指定された名前のクッキーが存在しない場合、default を返します。

このメソッドは、リクエストに存在したクッキーのみを返します。このハンドラーで set_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 では、小文字の引数のみを受け入れるように変更されます。

指定された名前のクッキーを削除します。

このメソッドは、expires と max_age を除き、set_cookie と同じ引数を受け入れます。クッキーをクリアするには、設定時と同じ domain および path 引数が必要です。場合によっては、samesite および secure 引数も一致している必要があります。その他の引数は無視されます。

set_cookie と同様に、このメソッドの効果は次のリクエストまで確認できません。

バージョン 6.3 で変更: set_cookie が受け入れるすべてのキーワード引数を受け入れるようになりました。samesite="none" クッキーをクリアするには、最近 samesite フラグと secure フラグが必須になりました。

RequestHandler.clear_all_cookies(**kwargs: Any) → None[ソース]

このリクエストでユーザーが送信したすべてのクッキーを削除しようとします。

キーワード引数の詳細については、clear_cookie を参照してください。クッキープロトコルの制限により、サーバー側では、domain、path、samesite、または secure 引数に必要な値を特定することはできません。このメソッドは、クッキーを設定するときにこれらの引数に対して常に同じ値を使用している場合にのみ成功します。

set_cookie と同様に、このメソッドの効果は次のリクエストまで確認できません。

バージョン 3.2 で変更: path パラメーターと domain パラメーターが追加されました。

バージョン 6.3 で変更: set_cookie が受け入れるすべてのキーワード引数を受け入れるようになりました。

バージョン 6.3 で非推奨: クッキーを管理するルールがますます複雑になっているため、clear_all_cookies メソッドは、クッキーの名前しかわからないため、信頼性高く動作することが不可能になりました。アプリケーションは一般的に、代わりに clear_cookie を一度に 1 つずつ使用する必要があります。

与えられた署名付きクッキーが検証されれば、それを返し、そうでなければ None を返します。

デコードされたクッキー値は（get_cookieとは異なり）バイト文字列として返されます。

get_cookieと同様に、このメソッドはリクエストに存在したクッキーのみを返します。このハンドラーでset_signed_cookieによって設定された送信クッキーは認識しません。

バージョン 3.2.1 で変更

min_version 引数が追加されました。クッキーバージョン 2 が導入されました。バージョン 1 とバージョン 2 の両方がデフォルトで受け入れられます。

バージョン 6.3 で変更: クッキーの属性とプレフィックスにおける "secure" の他の用途との混同を避けるため、get_secure_cookie から get_signed_cookie に名前が変更されました。古い名前はエイリアスとして残っています。

セキュア クッキーの署名キーのバージョンを返します。

バージョンは int として返されます。

バージョン 6.3 で変更: クッキーの属性とプレフィックスにおける "secure" の他の用途との混同を避けるため、get_secure_cookie_key_version から set_signed_cookie_key_version に名前が変更されました。古い名前はエイリアスとして残っています。

クッキーが偽造されないように署名とタイムスタンプを付与します。

このメソッドを使用するには、アプリケーションで cookie_secret 設定を指定する必要があります。これは、署名の HMAC シークレットとして使用される、長くランダムなバイト列である必要があります。

このメソッドで設定されたクッキーを読み取るには、get_signed_cookie()を使用します。

expires_days パラメーターはブラウザーでのクッキーの有効期間を設定しますが、get_signed_cookieの max_age_days パラメーターとは独立していることに注意してください。None の値を指定すると、有効期間は現在のブラウザーセッションに制限されます。

セキュア クッキーには（通常のクッキーとは異なり）Unicode 文字列だけでなく、任意のバイト値を含めることができます。

set_cookie と同様に、このメソッドの効果は次のリクエストまで確認できません。

バージョン 3.2.1 で変更: version 引数が追加されました。クッキーバージョン 2 が導入され、デフォルトになりました。

バージョン 6.3 で変更: クッキーの属性とプレフィックスにおける "secure" の他の用途との混同を避けるため、set_secure_cookie から set_signed_cookie に名前が変更されました。古い名前はエイリアスとして残っています。

get_signed_cookie の非推奨エイリアス。

バージョン 6.3 以降非推奨。

get_signed_cookie_key_version の非推奨エイリアス。

バージョン 6.3 以降非推奨。

set_signed_cookie の非推奨エイリアス。

バージョン 6.3 以降非推奨。

RequestHandler.create_signed_value(name: str, value: Union[str, bytes], version: Optional[int] = None) → bytes[ソース]

偽造できないように文字列に署名とタイムスタンプを付与します。

通常は set_signed_cookie を介して使用されますが、クッキー以外での使用のために別のメソッドとして提供されています。クッキーとして保存されていない値をデコードするには、get_signed_cookie のオプションの value 引数を使用します。

バージョン 3.2.1 で変更: 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_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 の早期チェックを実行したいアプリケーションのために、より早く呼び出すこともできます。このメソッドを呼び出す前に、(おそらく set_etag_header を使用して) Etag ヘッダーを設定する必要があります。

_xsrf クッキーが _xsrf 引数と一致することを確認します。

クロスサイトリクエストフォージェリを防ぐために、_xsrf クッキーを設定し、すべての POST リクエストで同じ値を非クッキーフィールドとして含めます。2つが一致しない場合、フォーム送信を潜在的な偽造として拒否します。

_xsrf 値は、_xsrf という名前のフォームフィールド、または X-XSRFToken または X-CSRFToken という名前のカスタム HTTP ヘッダーのいずれかで設定できます（後者は Django との互換性のために受け入れられます）。

http://en.wikipedia.org/wiki/Cross-site_request_forgery を参照してください。

バージョン 3.2.2 で変更: クッキーバージョン 2 のサポートが追加されました。バージョン 1 と 2 の両方がサポートされています。

RequestHandler.compute_etag() → Optional[str][ソース]

このリクエストに使用する etag ヘッダーを計算します。

デフォルトでは、これまでに書き込まれたコンテンツのハッシュを使用します。

カスタム etag 実装を提供するためにオーバーライドできます。または、tornado のデフォルトの etag サポートを無効にするために None を返すことができます。

RequestHandler.create_template_loader(template_path: str) → BaseLoader[ソース]

指定されたパスの新しいテンプレートローダーを返します。

サブクラスでオーバーライドできます。デフォルトでは、指定されたパスにあるディレクトリベースのローダーを返し、autoescape と template_whitespace アプリケーション設定を使用します。template_loader アプリケーション設定が指定されている場合は、代わりにそれを使用します。

RequestHandler.current_user

このリクエストで認証されたユーザー。

これは次の 2 つの方法のいずれかで設定されます。

  • サブクラスは get_current_user() をオーバーライドできます。これは、self.current_user が最初にアクセスされたときに自動的に呼び出されます。get_current_user() はリクエストごとに 1 回のみ呼び出され、今後のアクセスのためにキャッシュされます。

    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、または Accept-Language ヘッダーを使用する get_browser_locale によって決定されます。

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をオーバーライドしてください。

プロキシは、クライアントが接続を閉じた後、一定時間（場合によっては無期限に）接続を開いたままにする可能性があるため、このメソッドは、エンドユーザーが接続を閉じた直後にすぐに呼び出されない場合があります。

RequestHandler.require_setting(name: str, feature: str = 'この機能') → 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=<signature>を追加）を返し、静的ファイルを無期限にキャッシュできます。これは、include_version=Falseを渡すことで無効にできます（デフォルトの実装では。他の静的ファイルの実装はこれをサポートする必要はありませんが、他のオプションをサポートする場合があります）。

デフォルトでは、このメソッドは現在のホストに対する相対 URL を返しますが、include_hostが true の場合、返される URL は絶対 URL になります。このハンドラーにinclude_host属性がある場合、その値はstatic_urlのすべての呼び出しで、include_hostをキーワード引数として渡さない場合のデフォルトとして使用されます。

RequestHandler.xsrf_form_html() → str[ソース]

すべての POST フォームに含める HTML <input/> 要素。

クロスサイトリクエストフォージェリを防止するために、すべての POST リクエストでチェックする_xsrf入力値を定義します。xsrf_cookiesアプリケーション設定を設定している場合は、すべての HTML フォーム内にこの HTML を含める必要があります。

テンプレートでは、このメソッドは{% module xsrf_form_html() %}で呼び出す必要があります

詳細については、上記のcheck_xsrf_cookie()を参照してください。

RequestHandler.xsrf_token

現在のユーザー/セッションの XSRF 保護トークン。

クロスサイトリクエストフォージェリを防ぐために、'_xsrf'クッキーを設定し、すべてのPOSTリクエストに同じ'_xsrf'値を引数として含めます。 2つが一致しない場合、フォーム送信を潜在的な偽造として拒否します。

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）クッキーがバージョン2に変換されます。

バージョン 4.3 で変更: xsrf_cookie_kwargs Application設定を使用して、追加のクッキーオプション（set_cookieに直接渡される）を提供できます。たとえば、xsrf_cookie_kwargs=dict(httponly=True, secure=True)は、_xsrfクッキーに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)[source]

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モジュールのドキュメントを参照してください）。

リクエストを受け取ると、リストを順番に反復処理し、リクエストパスに一致する正規表現を持つ最初のリクエストクラスのインスタンスを作成します。リクエストクラスは、クラスオブジェクトまたは（完全修飾された）名前のいずれかとして指定できます。

タプルの3番目の要素(target_kwargs)として辞書を渡すことができます。これは、ハンドラーのコンストラクタと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),
])

現在のリクエストのホストに一致するものがない場合、default_hostパラメータ値がホスト正規表現と照合されます。

警告

TLSを使用しないアプリケーションは、DNSリバインディング攻撃に対して脆弱な可能性があります。この攻撃は、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: Tornado 4.0以降のcompress_responseの非推奨のエイリアス。

  • log_function: この関数は、すべてのリクエストの最後に、結果をログに記録するために呼び出されます（1つの引数、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されます。これにより、アイドル状態の接続を閉じる特定のプロキシサーバーを介して接続を維持したり、websocketが適切に閉じられずに失敗した場合に検出したりできます。

  • websocket_ping_timeout: ping間隔が設定されていて、サーバーがこの秒数内に「pong」を受信しない場合、websocketが閉じられます。デフォルトはping間隔の3倍で、最小30秒です。ping間隔が設定されていない場合は無視されます。

認証とセキュリティの設定

  • cookie_secret: RequestHandler.get_signed_cookie と set_signed_cookie がクッキーに署名するために使用します。

  • key_version: cookie_secret がキー辞書の場合、requestHandler の set_signed_cookie が特定のキーでクッキーに署名するために使用します。

  • login_url: ユーザーがログインしていない場合、authenticated デコレータはこの URL にリダイレクトします。 RequestHandler.get_login_url をオーバーライドすることで、さらにカスタマイズできます。

  • xsrf_cookies: True の場合、クロスサイトリクエストフォージェリ保護 が有効になります。

  • xsrf_cookie_version: このサーバーで生成される新しい XSRF クッキーのバージョンを制御します。通常はデフォルトのまま（常に最も高いサポートバージョンになります）にしておくべきですが、バージョン移行中は一時的に低い値に設定できます。Tornado 3.2.2 で新しく導入され、XSRF クッキーバージョン 2 が導入されました。

  • xsrf_cookie_kwargs: XSRF クッキー用の RequestHandler.set_cookie に渡される追加の引数の辞書を設定できます。

  • xsrf_cookie_name: XSRF クッキーに使用される名前を制御します（デフォルトは _xsrf）。意図された使用方法は、クッキープレフィックスを利用することです。クッキープレフィックスは他のクッキーフラグと相互作用するため、{"xsrf_cookie_name": "__Host-xsrf", "xsrf_cookie_kwargs": {"secure": True}} のように、xsrf_cookie_kwargs と組み合わせて使用する必要があります。

  • 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[ソース]

アプリケーションとRequestHandlerサブクラスのリクエストを処理できるHTTPMessageDelegateを返します。

パラメータ

  • 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]]][ソース]

ユーザーがログインしている必要があるメソッドをデコレートします。

ユーザーがログインしていない場合、設定された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[_RequestHandlerType]) → Type[_RequestHandlerType][ソース]

RequestHandlerサブクラスに適用して、ストリーミングボディのサポートを有効にします。

このデコレーターは、次の変更を意味します。

  • HTTPServerRequest.body は未定義であり、body引数は RequestHandler.get_argument に含まれません。

  • RequestHandler.prepare は、リクエストボディ全体が読み込まれた後ではなく、リクエストヘッダーが読み込まれたときに呼び出されます。

  • サブクラスは、データが利用可能になったときに0回以上呼び出されるメソッド data_received(self, data): を定義する必要があります。リクエストのボディが空の場合、data_received が呼び出されない可能性があることに注意してください。

  • prepare と data_received は、Futures（例えば @gen.coroutine を介して）を返すことができます。その場合、これらのFuturesが完了するまで次のメソッドは呼び出されません。

  • 通常のHTTPメソッド（post, put など）は、ボディ全体が読み込まれた後に呼び出されます。

使用例については、ファイルレシーバーのデモを参照してください。

その他すべて

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ステータスコード。 reason キーワード引数が与えられない限り、httplib.responses にリストされている必要があります。

  • log_message (str) – このエラーのログに書き込まれるメッセージ（Application がデバッグモードの場合を除き、ユーザーには表示されません）。残りの位置パラメータで埋められる %s スタイルのプレースホルダーを含めることができます。

  • reason (str) – キーワードのみの引数。ステータス行に status_code とともに渡すHTTPの「理由」フレーズ。通常は status_code から自動的に決定されますが、非標準の数値コードを使用するために使用できます。

exception tornado.web.Finish[ソース]

エラーレスポンスを生成せずにリクエストを終了させる例外。

Finish が 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 のサブクラスであるため、キャッチされない場合は、500ではなく400のレスポンスコードが使用されます（スタックトレースはログに記録されません）。

バージョン 3.1 で新規追加。

class tornado.web.UIModule(handler: RequestHandler)[ソース]

ページ上の再利用可能なモジュール式のUIユニット。

UIモジュールは追加のクエリを実行することが多く、出力ページに含まれる追加の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)[ソース]

別の HTTP サーバコールバックをラップする RequestHandler。

フォールバックは、HTTPServerRequestを受け入れる callable オブジェクトです。これは、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 は正規表現置換をサポートしています。たとえば、パスの最初と 2 番目の部分を入れ替えながら、残りの部分を保持するには、次のようにします。

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

ディレクトリから静的コンテンツを配信できるシンプルなハンドラー。

StaticFileHandler は、static_path キーワード引数を Application に渡すと自動的に構成されます。このハンドラーは、static_url_prefix、static_handler_class、および static_handler_args 設定でカスタマイズできます。

静的データディレクトリのためにこのハンドラーに追加のパスをマッピングするには、アプリケーションに次のような行を追加します。

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

ハンドラーのコンストラクターには、配信するコンテンツのローカルルートディレクトリを指定する path 引数が必要です。

正規表現のキャプチャグループは、get() メソッドへの path 引数の値を解析するために必要です（上記のコンストラクター引数とは異なります）。詳細については、URLSpec を参照してください。

ディレクトリがリクエストされたときに index.html のようなファイルを自動的に配信するには、アプリケーション設定で static_handler_args=dict(default_filename="index.html") を設定するか、default_filename を StaticFileHandler の初期化引数として追加します。

ブラウザのキャッシュの有効性を最大化するために、このクラスはバージョン付き URL をサポートしています（デフォルトでは引数 ?v= を使用します）。バージョンが指定された場合、ブラウザにこのファイルを無期限にキャッシュするように指示します。make_static_url ( RequestHandler.static_url としても利用可能) は、バージョン付き URL を構築するために使用できます。

このハンドラーは、主に開発および軽負荷のファイル配信での使用を目的としています。トラフィックが多い場合は、専用の静的ファイルサーバー（nginx や Apache など）を使用する方が効率的です。HTTP Accept-Ranges メカニズムをサポートして、部分的なコンテンツを返します（一部のブラウザーでは、HTML5オーディオまたはビデオでシークするためにこの機能が必要なため）。

サブクラス化に関する注意

このクラスはサブクラス化による拡張を意図して設計されていますが、静的 URL がインスタンスメソッドではなくクラスメソッドで生成されるため、継承パターンはやや異例です。クラスメソッドをオーバーライドするときは、必ず @classmethod デコレーターを使用してください。インスタンスメソッドは、属性 self.path、self.absolute_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][source]

静的 URL バージョンに基づいて Etag ヘッダーを設定します。

これにより、キャッシュされたバージョンに対する効率的な If-None-Match チェックが可能になり、部分的な応答（つまり、ファイル全体と同じ Etag）に対して正しい Etag が送信されます。

バージョン 3.1 で新規追加。

set_headers() → None[source]

レスポンスにコンテンツとキャッシュヘッダーを設定します。

バージョン 3.1 で新規追加。

should_return_304() → bool[source]

ヘッダーが 304 を返す必要があることを示している場合は True を返します。

バージョン 3.1 で新規追加。

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

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 で変更: 現在、naive ではなく、aware な datetime オブジェクトを返します。このメソッドをオーバーライドするサブクラスは、どちらの種類でも返すことができます。

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 は、static_url_prefix が削除された URL のパスコンポーネントです。戻り値は、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 が、基本クラスが結果のキャッシュを処理できるようにするため、現在では推奨されています。