tornado.httpclient — 非同期 HTTP クライアント

ブロッキングとノンブロッキングの HTTP クライアントインターフェース。

このモジュールは、simple_httpclient と curl_httpclient の 2 つの実装で共有される共通インターフェースを定義します。アプリケーションは、選択した実装クラスを直接インスタンス化するか、このモジュールの AsyncHTTPClient クラスを使用できます。このクラスは、AsyncHTTPClient.configure メソッドでオーバーライドできる実装を選択します。

デフォルトの実装は simple_httpclient で、ほとんどのユーザーのニーズに適していると考えられます。ただし、次のような理由で curl_httpclient に切り替えたいアプリケーションもあるかもしれません。

  • curl_httpclient には、HTTP プロキシのサポートや指定されたネットワークインターフェースを使用する機能など、simple_httpclient には見られない機能がいくつかあります。

  • curl_httpclient は、HTTP 仕様に完全には準拠していないサイトや、HTTP のあまり使われていない機能を使用するサイトとの互換性が高い可能性があります。

  • curl_httpclient の方が高速です。

curl_httpclient を使用している場合は、最新バージョンの libcurl と pycurl を使用することを強くお勧めします。現在、サポートされている libcurl の最小バージョンは 7.22.0 で、pycurl の最小バージョンは 7.18.2 です。 libcurl のインストールは、非同期 DNS リゾルバー (スレッドまたは c-ares) を使用してビルドすることを強くお勧めします。そうしないと、リクエストのタイムアウトに関するさまざまな問題が発生する可能性があります (詳細については、http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCONNECTTIMEOUTMS と curl_httpclient.py のコメントを参照してください)。

curl_httpclient を選択するには、起動時に AsyncHTTPClient.configure を呼び出します。

AsyncHTTPClient.configure("tornado.curl_httpclient.CurlAsyncHTTPClient")

HTTP クライアントインターフェース

class tornado.httpclient.HTTPClient(async_client_class: Optional[Type[AsyncHTTPClient]] = None, **kwargs: Any)[source]

ブロッキング HTTP クライアント。

このインターフェースは、同期アプリケーションと非同期アプリケーション間でコードを共有しやすくするために提供されています。 IOLoop を実行しているアプリケーションは、代わりに AsyncHTTPClient を使用する必要があります。

典型的な使用例は次のようになります。

http_client = httpclient.HTTPClient()
try:
    response = http_client.fetch("http://www.google.com/")
    print(response.body)
except httpclient.HTTPError as e:
    # HTTPError is raised for non-200 responses; the response
    # can be found in e.response.
    print("Error: " + str(e))
except Exception as e:
    # Other errors are possible, such as IOError.
    print("Error: " + str(e))
http_client.close()

バージョン 5.0 で変更: asyncio の制限により、IOLoop の実行中に同期 HTTPClient を使用できなくなりました。代わりに AsyncHTTPClient を使用してください。

close() → None[source]

HTTPClient を閉じ、使用されているリソースを解放します。

fetch(request: Union[HTTPRequest, str], **kwargs: Any) → HTTPResponse[source]

HTTPResponse を返して、リクエストを実行します。

リクエストは、文字列 URL または HTTPRequest オブジェクトのいずれかです。文字列の場合、追加の kwargs を使用して HTTPRequest を構築します: HTTPRequest(request, **kwargs)

フェッチ中にエラーが発生した場合、raise_error キーワード引数が False に設定されていない限り、HTTPError を発生させます。

class tornado.httpclient.AsyncHTTPClient(force_instance: bool = False, **kwargs: Any)[source]

ノンブロッキング HTTP クライアント。

使用例

async def f():
    http_client = AsyncHTTPClient()
    try:
        response = await http_client.fetch("http://www.google.com")
    except Exception as e:
        print("Error: %s" % e)
    else:
        print(response.body)

このクラスのコンストラクタは、いくつかの点で特殊です。実際には、実装固有のサブクラスのインスタンスを作成し、インスタンスは擬似シングルトン ( IOLoop ごとに 1 つ) の一種として再利用されます。キーワード引数 force_instance=True を使用すると、このシングルトン動作を抑制できます。 force_instance=True を使用しない限り、AsyncHTTPClient コンストラクタに引数を渡すべきではありません。実装サブクラスと、そのコンストラクタへの引数は、静的メソッド configure() で設定できます。

すべての AsyncHTTPClient 実装は、defaults キーワード引数をサポートしています。これは、HTTPRequest 属性のデフォルト値を設定するために使用できます。例えば

AsyncHTTPClient.configure(
    None, defaults=dict(user_agent="MyUserAgent"))
# or with force_instance:
client = AsyncHTTPClient(force_instance=True,
    defaults=dict(user_agent="MyUserAgent"))

バージョン 5.0 で変更: io_loop 引数 (バージョン 4.1 から非推奨) は削除されました。

close() → None[source]

この HTTP クライアントを破棄し、使用されているファイル記述子を解放します。

AsyncHTTPClient オブジェクトは透過的に再利用されるため、このメソッドは**通常の使用では必要ありません**。 close() は、一般的に IOLoop も閉じられる場合、または AsyncHTTPClient の作成時に force_instance=True 引数が使用された場合にのみ必要です。

close() 後は、AsyncHTTPClient で他のメソッドを呼び出すことはできません。

fetch(request: Union[str, HTTPRequest], raise_error: bool = True, **kwargs: Any) → Future[HTTPResponse][source]

リクエストを実行し、HTTPResponse を非同期的に返します。

リクエストは、文字列 URL または HTTPRequest オブジェクトのいずれかです。文字列の場合、追加の kwargs を使用して HTTPRequest を構築します: HTTPRequest(request, **kwargs)

このメソッドは、結果が HTTPResponse である Future を返します。デフォルトでは、リクエストが 200 以外のレスポンスコードを返した場合、Future は HTTPError を発生させます (サーバーに接続できなかった場合にも、他のエラーが発生する可能性があります)。代わりに、raise_error が False に設定されている場合、レスポンスコードに関係なく、常にレスポンスが返されます。

callback が指定されている場合、HTTPResponse を使用して呼び出されます。コールバックインターフェースでは、HTTPError は自動的に発生しません。代わりに、レスポンスの error 属性を確認するか、rethrow メソッドを呼び出す必要があります。

バージョン 6.0 で変更: callback 引数は削除されました。代わりに、返された Future を使用してください。

raise_error=False 引数は、すべてのエラーを抑制する代わりに、200 以外のレスポンスコードが使用されたときに発生する HTTPError のみに影響します。

classmethod configure(impl: Union[None, str, Type[Configurable]], **kwargs: Any) → None[source]

使用する AsyncHTTPClient サブクラスを設定します。

AsyncHTTPClient() は、実際にはサブクラスのインスタンスを作成します。このメソッドは、クラスオブジェクトまたはそのようなクラスの完全修飾名（またはデフォルトの SimpleAsyncHTTPClient を使用するには None）で呼び出すことができます。

追加のキーワード引数が指定された場合、それらは作成された各サブクラスインスタンスのコンストラクターに渡されます。キーワード引数 max_clients は、各 IOLoop で並列に実行できる fetch() 操作の最大数を決定します。使用中の実装クラスによっては、追加の引数がサポートされる場合があります。

例

AsyncHTTPClient.configure("tornado.curl_httpclient.CurlAsyncHTTPClient")

リクエストオブジェクト

class tornado.httpclient.HTTPRequest(url: str, method: str = 'GET', headers: Optional[Union[Dict[str, str], HTTPHeaders]] = None, body: Optional[Union[bytes, str]] = None, auth_username: Optional[str] = None, auth_password: Optional[str] = None, auth_mode: Optional[str] = None, connect_timeout: Optional[float] = None, request_timeout: Optional[float] = None, if_modified_since: Optional[Union[float, datetime]] = None, follow_redirects: Optional[bool] = None, max_redirects: Optional[int] = None, user_agent: Optional[str] = None, use_gzip: Optional[bool] = None, network_interface: Optional[str] = None, streaming_callback: Optional[Callable[[bytes], None]] = None, header_callback: Optional[Callable[[str], None]] = None, prepare_curl_callback: Optional[Callable[[Any], None]] = None, proxy_host: Optional[str] = None, proxy_port: Optional[int] = None, proxy_username: Optional[str] = None, proxy_password: Optional[str] = None, proxy_auth_mode: Optional[str] = None, allow_nonstandard_methods: Optional[bool] = None, validate_cert: Optional[bool] = None, ca_certs: Optional[str] = None, allow_ipv6: Optional[bool] = None, client_key: Optional[str] = None, client_cert: Optional[str] = None, body_producer: Optional[Callable[[Callable[[bytes], None]], Future[None]]] = None, expect_100_continue: bool = False, decompress_response: Optional[bool] = None, ssl_options: Optional[Union[Dict[str, Any], SSLContext]] = None)[source]

HTTPクライアントリクエストオブジェクト。

url 以外のパラメータはすべてオプションです。

パラメータ

  • **url** (str) – フェッチするURL

  • **method** (str) – HTTPメソッド、例：「GET」または「POST」

  • **headers** (HTTPHeaders または dict) – リクエストで渡す追加のHTTPヘッダー

  • **body** (str または bytes) – 文字列としてのHTTPリクエスト本文（バイトまたはユニコード; ユニコードの場合、utf-8エンコーディングが使用されます）

  • **body_producer** (collections.abc.Callable) – 遅延/非同期リクエスト本文に使用される呼び出し可能オブジェクト。1つの引数、write 関数で呼び出され、Future を返す必要があります。新しいデータが利用可能になったら、write 関数を呼び出してデータを渡す必要があります。write 関数は、フロー制御に使用できる Future を返します。body と body_producer のいずれか一方のみを指定できます。body_producer は curl_httpclient ではサポートされていません。body_producer を使用する場合、チャンクエンコーディングが使用されるため、ヘッダーに Content-Length を渡すことをお勧めします。多くのサーバーは、リクエストでチャンクエンコーディングをサポートしていません。Tornado 4.0 での新機能

  • **auth_username** (str) – HTTP認証のユーザー名

  • **auth_password** (str) – HTTP認証のパスワード

  • **auth_mode** (str) – 認証モード。デフォルトは「basic」です。許可される値は実装定義です。curl_httpclient は「basic」と「digest」をサポートします。simple_httpclient は「basic」のみをサポートします。

  • **connect_timeout** (float) – 初期接続のタイムアウト（秒単位）、デフォルトは20秒（0はタイムアウトなし）

  • request_timeout (float) – リクエスト全体のタイムアウト（秒単位）。デフォルトは20秒（0はタイムアウトなし）

  • if_modified_since (datetime または float) – If-Modified-Since ヘッダーのタイムスタンプ

  • follow_redirects (bool) – リダイレクトを自動的に追跡するか、3xxレスポンスを返すか。デフォルトはTrue。

  • max_redirects (int) – follow_redirects の上限。デフォルトは5。

  • user_agent (str) – User-Agent ヘッダーとして送信する文字列

  • decompress_response (bool) – サーバーから圧縮されたレスポンスを要求し、ダウンロード後に解凍する。デフォルトはTrue。Tornado 4.0で追加。

  • use_gzip (bool) – Tornado 4.0以降、decompress_response の非推奨エイリアス。

  • network_interface (str) – リクエストに使用するネットワークインターフェースまたはソースIP。後述のcurl_httpclient の注意事項を参照。

  • streaming_callback (collections.abc.Callable) – 設定されている場合、データの各チャンクが受信されるたびにstreaming_callback が実行され、最終レスポンスではHTTPResponse.body と HTTPResponse.buffer は空になります。

  • header_callback (collections.abc.Callable) – 設定されている場合、各ヘッダー行が受信されるたびにheader_callback が実行されます（最初の行（例：HTTP/1.0 200 OK\r\n）と、\r\nのみを含む最後の行を含む）。すべての行には、末尾の改行文字が含まれます）。最終レスポンスではHTTPResponse.headers は空になります。これは、リクエストの処理中にヘッダーデータにアクセスする唯一の方法であるため、streaming_callback と組み合わせて使用​​するのが最も効果的です。

  • prepare_curl_callback (collections.abc.Callable) – 設定されている場合、アプリケーションが追加のsetopt 呼び出しを行えるように、pycurl.Curl オブジェクトを使用して呼び出されます。

  • proxy_host (str) – HTTPプロキシホスト名。プロキシを使用するには、proxy_host と proxy_port を設定する必要があります。proxy_username、proxy_pass、proxy_auth_mode はオプションです。プロキシは現在、curl_httpclient でのみサポートされています。

  • proxy_port (int) – HTTPプロキシポート

  • proxy_username (str) – HTTPプロキシユーザー名

  • proxy_password (str) – HTTPプロキシパスワード

  • proxy_auth_mode (str) – HTTPプロキシ認証モード。デフォルトは「basic」。「basic」と「digest」をサポートします。

  • allow_nonstandard_methods (bool) – method 引数に不明な値を許可するかどうか。デフォルトはFalse。

  • validate_cert (bool) – HTTPSリクエストの場合、サーバーの証明書を検証するかどうか。デフォルトはTrue。

  • ca_certs (str) – PEM形式のCA証明書のファイル名、またはデフォルトを使用する場合はNone。curl_httpclient で使用する場合の後述の注意事項を参照。

  • client_key (str) – クライアントSSLキーのファイル名（存在する場合）。curl_httpclient で使用する場合の後述の注意事項を参照。

  • client_cert (str) – クライアントSSL証明書のファイル名（存在する場合）。curl_httpclient で使用する場合の後述の注意事項を参照。

  • ssl_options (ssl.SSLContext) – simple_httpclient で使用するssl.SSLContext オブジェクト（curl_httpclient ではサポートされていません）。validate_cert、ca_certs、client_key、およびclient_cert をオーバーライドします。

  • allow_ipv6 (bool) – 使用可能な場合はIPv6を使用するかどうか。デフォルトはTrue。

  • expect_100_continue (bool) – trueの場合、Expect: 100-continue ヘッダーを送信し、リクエスト本文を送信する前に継続レスポンスを待ちます。simple_httpclient でのみサポートされています。

注記

curl_httpclient を使用する場合、pycurl ではそれらをクリーンにリセットできないため、特定のオプションが後続のフェッチによって継承される場合があります。これは、ca_certs、client_key、client_cert、およびnetwork_interface 引数に適用されます。これらのオプションを使用する場合は、すべてのリクエストでそれらを渡す必要があります（常に同じ値を使用する必要はありませんが、これらのオプションを指定するリクエストとデフォルトを使用するリクエストを混在させることはできません）。

バージョン 3.1 で追加: auth_mode 引数。

バージョン 4.0 で追加: body_producer および expect_100_continue 引数。

バージョン 4.2 で追加: ssl_options 引数。

バージョン 4.5 で追加: proxy_auth_mode 引数。

レスポンスオブジェクト

class tornado.httpclient.HTTPResponse(request: HTTPRequest, code: int, headers: Optional[HTTPHeaders] = None（以下略）

HTTP レスポンスオブジェクト。

属性

  • request: HTTPRequest オブジェクト

  • code: 数値の HTTP ステータスコード、例： 200 または 404

  • reason: ステータスコードを説明する人間が読める理由句

  • headers: tornado.httputil.HTTPHeaders オブジェクト

  • effective_url: リダイレクトに従った後のリソースの最終的な場所

  • buffer: レスポンスボディのための cStringIO オブジェクト

  • body: バイトとしてのレスポンスボディ (self.buffer からオンデマンドで作成)

  • error: Exception オブジェクト（もしあれば）

  • request_time: リクエスト開始から終了までの秒数。DNS 解決から最後のデータバイトの受信までのすべてのネットワーク操作が含まれます。キューで費やされた時間は含まれません（max_clients オプションのため）。リダイレクトがフォローされた場合、最後のリクエストのみが含まれます。

  • start_time: time.time に基づく HTTP 操作の開始時刻（IOLoop.time が使用するモノトニッククロックではありません）。リクエストがキュー内でタイムアウトした場合、Noneになる可能性があります。

  • time_info: リクエストからの診断タイミング情報の辞書。利用可能なデータは変更される可能性がありますが、現在は http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html から入手可能なタイミングに加えて、AsyncHTTPClient の max_clients 設定でスロットを待つことによって発生する遅延（もしあれば）である queue を使用します。

バージョン 5.1 で追加: start_time 属性が追加されました。

バージョン 5.1 で変更: request_time 属性には、以前は simple_httpclient のキューで費やされた時間が含まれていましたが、curl_httpclient では含まれていませんでした。現在、キューイング時間は両方の実装で除外されています。request_time は、利用可能な場合はモノトニッククロックを使用するため、curl_httpclient の方が正確になりました。

rethrow() → None[source]

リクエストでエラーが発生した場合、HTTPError を発生させます。

例外

exception tornado.httpclient.HTTPClientError(code: int, message: Optional[str] = None, response: Optional[HTTPResponse] = None)[source]

失敗した HTTP リクエストに対してスローされる例外。

属性

  • code - HTTP エラー整数エラーコード、例： 404。エラーコード 599 は、タイムアウトなど、HTTP レスポンスが受信されなかった場合に使用されます。

  • response - HTTPResponse オブジェクト（もしあれば）。

もしfollow_redirectsがFalseの場合、リダイレクトはHTTPErrorsとなり、error.response.headers['Location']を見ることでリダイレクト先を確認できます。

バージョン 5.1 で変更: tornado.web.HTTPErrorとの衝突を避けるため、HTTPErrorからHTTPClientErrorに名前変更されました。tornado.httpclient.HTTPErrorという名前はエイリアスとして残ります。

exception tornado.httpclient.HTTPError

HTTPClientErrorのエイリアス。

コマンドラインインターフェース

このモジュールは、TornadoのHTTPクライアントを使用してURLを取得するためのシンプルなコマンドラインインターフェースを提供します。 使用例

# Fetch the url and print its body
python -m tornado.httpclient http://www.google.com

# Just print the headers
python -m tornado.httpclient --print_headers --print_body=false http://www.google.com

実装

class tornado.simple_httpclient.SimpleAsyncHTTPClient(force_instance: bool = False, **kwargs: Any)[ソース]

外部依存関係のないノンブロッキングHTTPクライアント。

このクラスは、TornadoのIOStreamsの上にHTTP 1.1クライアントを実装します。 curlベースのAsyncHTTPClientにある一部の機能はまだサポートされていません。 特に、プロキシはサポートされておらず、接続は再利用されず、呼び出し元は使用するネットワークインターフェースを選択できません。

この実装は、グローバルシングルトンを制御するためにconfigure()に渡すか、force_instance=Trueの場合にコンストラクターに渡すことができる、以下の引数をサポートしています。

max_clientsは、同時に進行できるリクエストの数です。 この制限に達すると、追加のリクエストはキューに入れられます。 このキューで待機する時間もrequest_timeoutにカウントされることに注意してください。

defaultsは、このクライアントに送信されるすべてのHTTPRequestオブジェクトのデフォルトとして使用されるパラメータの辞書です。

hostname_mapping は、ホスト名をIPアドレスにマッピングする辞書です。 /etc/hosts のようなシステム全体の設定を変更することが不可能または望ましくない場合（例えば、単体テストの場合）に、ローカルDNSの変更を行うために使用できます。 resolver も同様ですが、単純なマッピングではなく Resolver インターフェースを使用します。

max_buffer_size（デフォルトは100MB）は、一度にメモリに読み込むことができるバイト数です。 max_body_size (デフォルトは max_buffer_size) は、クライアントが受け入れる最大のレスポンスボディです。 streaming_callback がない場合、これら2つの制限のうち小さい方が適用されます。 streaming_callback がある場合は、max_body_size のみが適用されます。

バージョン 4.2 で変更: max_body_size 引数が追加されました。

class tornado.curl_httpclient.CurlAsyncHTTPClient(max_clients=10, defaults=None)

libcurlベースのHTTPクライアント。

この実装は、グローバルシングルトンを制御するためにconfigure()に渡すか、force_instance=Trueの場合にコンストラクターに渡すことができる、以下の引数をサポートしています。

max_clientsは、同時に進行できるリクエストの数です。 この制限に達すると、追加のリクエストはキューに入れられます。

defaultsは、このクライアントに送信されるすべてのHTTPRequestオブジェクトのデフォルトとして使用されるパラメータの辞書です。

サンプルコード