"http.client" --- HTTP プロトコルクライアント
*********************************************

**ソースコード:** Lib/http/client.py

======================================================================

このモジュールでは HTTP および HTTPS プロトコルのクライアントサイドを
実装しているクラスを定義しています。通常、このモジュールは直接使いませ
ん --- "urllib.request" モジュールが HTTP や HTTPS を使った URL を扱う
上でこのモジュールを使います。

参考: より高水準の HTTP クライアントインターフェースとして Requests パッケ
    ージ が推奨されています。

注釈:

  HTTPS のサポートは、Python が SSL サポート付きでコンパイルされている
  場合にのみ利用できます ("ssl" モジュールによって)。

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは
、WebAssembly プラットフォーム を見てください。

このモジュールでは以下のクラスを提供しています:

class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None, blocksize=8192, max_response_headers=None)

   "HTTPConnection" インスタンスは、HTTP サーバーとの 1 つのトランザク
   ションを表します。 ホストと、省略可能なポート番号を渡してインスタン
   ス化します。 ポート番号を指定しない場合、ホスト文字列が "host:port"
   形式ならそこからポートを取り出し、そうでなければ HTTP のデフォルト
   ポート (80) を使います。 オプションの *timeout* 引数を指定すると、
   接続の試行などのブロックする操作は、指定した秒数が経過するとタイム
   アウトします (省略するとグローバルなデフォルトのタイムアウト設定を
   使います)。 オプションの *source_address* 引数には、HTTP 接続の送信
   元アドレスとして使う (host, port) タプルを指定できます。 オプション
   の *blocksize* 引数は、ファイル類似オブジェクトからメッセージ本体を
   送信する際のバッファーサイズをバイト単位で設定します。 オプションの
   *max_response_headers* 引数は、サービス拒否攻撃を防ぐために、許容す
   るレスポンスヘッダーの数の上限を設定します。 省略するとデフォルト値
   (100) を使います。

   例えば、以下の呼び出しは全て同じサーバの同じポートに接続するインス
   タンスを生成します:

      >>> h1 = http.client.HTTPConnection('www.python.org')
      >>> h2 = http.client.HTTPConnection('www.python.org:80')
      >>> h3 = http.client.HTTPConnection('www.python.org', 80)
      >>> h4 = http.client.HTTPConnection('www.python.org', 80, timeout=10)

   バージョン 3.2 で変更: *source_address* が追加されました。

   バージョン 3.4 で変更: *strict* パラメータは廃止されました。HTTP
   0.9 の "シンプルなレスポンス" のような形式はもはやサポートされませ
   ん。

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

   バージョン 3.15 で変更: *max_response_headers* 引数を追加しました。

class http.client.HTTPSConnection(host, port=None, *, [timeout, ]source_address=None, context=None, blocksize=8192, max_response_headers=None)

   "HTTPConnection" のサブクラスはセキュア・サーバとやりとりする為の
   SSL を使う場合に用います。デフォルトのポート番号は "443" です。
   *context* が指定されれば、それは様々な SSL オプションを記述する
   "ssl.SSLContext" インスタンスでなければなりません。

   ベストプラクティスに関するより良い情報が セキュリティで考慮すべき点
   にありますのでお読みください。

   バージョン 3.2 で変更: *source_address*、*context* そして
   *check_hostname* が追加されました。

   バージョン 3.2 で変更: このクラスは現在、可能であれば (つまり
   "ssl.HAS_SNI" が真の場合) HTTPS のバーチャルホストをサポートしてい
   ます。

   バージョン 3.4 で変更: *strict* パラメータは廃止されました。HTTP
   0.9 の "シンプルなレスポンス" のような形式はもはやサポートされませ
   ん。

   バージョン 3.4.3 で変更: このクラスは今や全ての必要な証明書とホスト
   名の検証をデフォルトで行うようになりました。 *context* パラメーター
   に "ssl._create_unverified_context()" を渡すことで、昔の、検証を行
   わない振る舞いに戻すことができます。

   バージョン 3.8 で変更: デフォルトの *context* を使う場合、またはカ
   スタムの *context* とともに *cert_file* を渡した場合、このクラスは
   TLS 1.3 の "ssl.SSLContext.post_handshake_auth" を有効にするように
   なりました。

   バージョン 3.10 で変更: *context* を指定しない場合、このクラスはプ
   ロトコル識別子 "http/1.1" を含む ALPN 拡張を送信するようになりまし
   た。 カスタムの *context* では "set_alpn_protocols()" を使って ALPN
   プロトコルを設定してください。

   バージョン 3.12 で変更: 非推奨だった引数 *key_file*、*cert_file*、
   *check_hostname* を削除しました。

   バージョン 3.15 で変更: *max_response_headers* 引数を追加しました。

class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)

   接続に成功すると、このクラスのインスタンスが返されます。 利用者が直
   接インスタンス化するクラスではありません。

   バージョン 3.4 で変更: *strict* パラメータは廃止されました。HTTP
   0.9 の "シンプルなレスポンス" のような形式はもはやサポートされませ
   ん。

このモジュールは以下の関数を提供します:

http.client.parse_headers(fp)

   HTTP リクエストまたはレスポンスを表すファイルポインター *fp* からヘ
   ッダーを解析します。 ファイルは "BufferedIOBase" の読み込み用オブジ
   ェクト (テキストではありません) で、有効な **RFC 5322** 形式のヘッ
   ダーを提供しなければなりません。

   この関数は、ヘッダーフィールドを保持し、ペイロードは持たない
   "http.client.HTTPMessage" インスタンスを返します
   ("HTTPResponse.msg" や "http.server.BaseHTTPRequestHandler.headers"
   と同様です)。 関数から戻ると、ファイルポインター *fp* は HTTP 本体
   を読み込める位置にあります。

   注釈:

     "parse_headers()" は HTTP メッセージの開始行を解析せず、"Name:
     value" 形式の行だけを解析します。 ファイルはこれらのフィールド行
     を読み込める状態でなければならないため、関数を呼び出す前に最初の
     行を読み込んでおく必要があります。

状況に応じて、以下の例外が送出されます:

exception http.client.HTTPException

   このモジュールにおける他の例外クラスの基底クラスです。 "Exception"
   のサブクラスです。

exception http.client.NotConnected

   "HTTPException" サブクラスです。

exception http.client.InvalidURL

   "HTTPException" のサブクラスです。ポート番号を指定したものの、その
   値が数字でなかったり空のオブジェクトであった場合に送出されます。

exception http.client.UnknownProtocol

   "HTTPException" サブクラスです。

exception http.client.UnknownTransferEncoding

   "HTTPException" サブクラスです。

exception http.client.UnimplementedFileMode

   "HTTPException" サブクラスです。

exception http.client.IncompleteRead

   "HTTPException" サブクラスです。

exception http.client.ImproperConnectionState

   "HTTPException" サブクラスです。

exception http.client.CannotSendRequest

   "ImproperConnectionState" のサブクラスです。

exception http.client.CannotSendHeader

   "ImproperConnectionState" のサブクラスです。

exception http.client.ResponseNotReady

   "ImproperConnectionState" のサブクラスです。

exception http.client.BadStatusLine

   "HTTPException" のサブクラスです。 サーバーから返された HTTP ステー
   タスコードをクライアントが理解できない場合に送出されます。

exception http.client.LineTooLong

   "HTTPException" のサブクラスです。 HTTP プロトコルでサーバーから長
   すぎる行を受信した場合に送出されます。

exception http.client.RemoteDisconnected

   "ConnectionResetError" と "BadStatusLine" のサブクラスです。
   "HTTPConnection.getresponse()" がレスポンスを読み込もうとしても接続
   からデータをまったく読み込めず、相手側が接続を閉じたと分かった場合
   に送出されます。

   Added in version 3.5: 以前は "BadStatusLine""('')" を送出していまし
   た。

このモジュールで定義されている定数は以下の通りです:

http.client.HTTP_PORT

   HTTP プロトコルのデフォルトポート (常に "80") です。

http.client.HTTPS_PORT

   HTTPS プロトコルのデフォルトポート (常に "443") です。

http.client.responses

   このディクショナリは、HTTP 1.1ステータスコードをW3Cの名前にマップし
   たものです。

   例: "http.client.responses[http.client.NOT_FOUND]" は "'Not Found'"
   を示します。

このモジュールで定数として利用できる HTTP ステータスコードの一覧は
HTTP ステータスコード を参照してください。


HTTPConnection オブジェクト
===========================

"HTTPConnection" インスタンスには以下のメソッドがあります:

HTTPConnection.request(method, url, body=None, headers={}, *, encode_chunked=False)

   HTTP リクエストメソッド *method* とリクエスト URI *url* を使って、
   サーバーにリクエストを送信します。 **RFC 2616 §5.1.2** に準拠するた
   め、*url* は絶対パスでなければなりません (HTTP プロキシサーバーへの
   接続時や、"OPTIONS" または "CONNECT" メソッドを使う場合を除きます)
   。

   *body* を指定すると、ヘッダーの送信後にそのデータを送信します。
   "str"、*bytes-like object*、開いた *file object*、または "bytes" の
   イテラブルを指定できます。 *body* が文字列の場合は、HTTP のデフォル
   トである ISO-8859-1 でエンコードします。 バイト列類似オブジェクトの
   場合は、そのバイト列をそのまま送信します。 *file object* の場合は、
   ファイルの内容を送信します。 このファイルオブジェクトは少なくとも
   "read()" メソッドをサポートしなければなりません。 ファイルオブジェ
   クトが "io.TextIOBase" のインスタンスの場合、"read()" メソッドが返
   すデータを ISO-8859-1 でエンコードします。 それ以外の場合は、
   "read()" が返すデータをそのまま送信します。 *body* がイテラブルの場
   合は、イテラブルが *尽きる* までその要素をそのまま送信します。

   *headers* 引数には、リクエストとともに送信する追加の HTTP ヘッダー
   のマッピングを指定します。 **RFC 2616 §5.1.2** に準拠するため、
   **Host ヘッダー** を指定しなければなりません (HTTP プロキシサーバー
   への接続時や、"OPTIONS" または "CONNECT" メソッドを使う場合を除きま
   す)。

   *headers* に Content-Length も Transfer-Encoding も含まれておらず、
   リクエスト本体がある場合は、どちらかのヘッダーフィールドを自動で追
   加します。 *body* が "None" の場合、本体を想定するメソッド ("PUT"、
   "POST"、"PATCH") では Content-Length ヘッダーを "0" に設定します。
   *body* が文字列か、*ファイル* ではないバイト列類似オブジェクトの場
   合は、Content-Length ヘッダーをその長さに設定します。 それ以外の型
   の *body* (ファイルや一般のイテラブル) はチャンク形式でエンコードし
   、Content-Length の代わりに Transfer-Encoding ヘッダーを自動で設定
   します。

   *encode_chunked* 引数が関係するのは、*headers* に Transfer-Encoding
   を指定した場合だけです。 *encode_chunked* が "False" の場合、
   HTTPConnection オブジェクトは呼び出し側のコードですべてのエンコード
   を行うものとみなします。 "True" の場合、本体をチャンク形式でエンコ
   ードします。

   例えば、"https://docs.python.org/3/" への "GET" リクエストは次のよ
   うに実行します。

      >>> import http.client
      >>> host = "docs.python.org"
      >>> conn = http.client.HTTPSConnection(host)
      >>> conn.request("GET", "/3/", headers={"Host": host})
      >>> response = conn.getresponse()
      >>> print(response.status, response.reason)
      200 OK

   注釈:

     チャンク転送エンコーディングは HTTP プロトコルのバージョン 1.1 で
     追加されました。 HTTP サーバーが HTTP 1.1 に対応していると分かっ
     ていない限り、呼び出し側は Content-Length を指定するか、 本体とし
     て "str" またはファイルではないバイト列類似オブジェクトを渡す必要
     があります。

   注釈:

     サーバーに新しいリクエストを送信する前に、レスポンス全体を読み込
     んでおく必要があります。 "getresponse()" が "ConnectionError" 以
     外の例外を送出した場合は、"close()" を呼び出してください。

   バージョン 3.2 で変更: *body* にイテラブルを指定できるようになりま
   した。

   バージョン 3.6 で変更: *headers* に Content-Length も Transfer-
   Encoding も設定されていない場合、ファイルやイテラブルの *body* オブ
   ジェクトをチャンク形式でエンコードするようになりました。
   *encode_chunked* 引数を追加しました。 ファイルオブジェクトの
   Content-Length を調べることはしません。

HTTPConnection.getresponse()

   サーバに対して HTTP 要求を送り出した後に呼び出されなければりません
   。要求に対する応答を取得します。 "HTTPResponse" インスタンスを返し
   ます。

   バージョン 3.5 で変更: "ConnectionError" またはそのサブクラスの例外
   が送出された場合、"HTTPConnection" オブジェクトは新しいリクエストの
   送信時に再接続できる状態になります。これは内部のソケットが送出する
   "OSError" には当てはまりません。 この場合、呼び出し側が既存の接続の
   "close()" を呼び出す必要があります。

HTTPConnection.set_debuglevel(level)

   デバッグレベルを設定します。 デフォルトのデバッグレベルは "0" で、
   デバッグ出力は表示しません。 "0" より大きい値にすると、現在定義され
   ているすべてのデバッグ出力を標準出力に表示します。 "debuglevel" は
   、新しく作成されるすべての "HTTPResponse" オブジェクトに渡されます
   。

   Added in version 3.1.

HTTPConnection.set_tunnel(host, port=None, headers=None)

   HTTP トンネリング接続のホスト名とポート番号を設定します。これにより
   プロキシサーバを通しての接続を実行できます。

   引数 *host* と *port* は、トンネル接続の終点を指定します (CONNECT
   リクエストに含まれるアドレスであり、プロキシサーバーのアドレスでは
   *ありません*)。

   *headers* 引数には、CONNECT リクエストとともに送信する追加の HTTP
   ヘッダーのマッピングを指定します。 文字列以外のヘッダー値は "str()"
   で文字列に変換します。

   HTTP CONNECT のトンネル接続リクエストには HTTP/1.1 を使うため、RFC
   の規定 に従い、 CONNECT リクエストの接続先として指定したリクエスト
   ターゲットの authority 形式に一致する HTTP "Host:" ヘッダーが必要で
   す。 "headers" 引数で HTTP "Host:" ヘッダーを指定しなければ、自動で
   生成して送信します。

   例えば、ローカルのポート 8080 で動作する HTTPS プロキシサーバーを経
   由してトンネル接続するには、 "HTTPSConnection" コンストラクタにプロ
   キシのアドレスを、"set_tunnel()" メソッドに最終的な接続先ホストのア
   ドレスを渡します。

      >>> import http.client
      >>> conn = http.client.HTTPSConnection("localhost", 8080)
      >>> conn.set_tunnel("www.python.org")
      >>> conn.request("HEAD","/index.html")

   Added in version 3.2.

   バージョン 3.12 で変更: HTTP CONNECT のトンネル接続リクエストは、
   HTTP/1.0 に代わって HTTP/1.1 プロトコルを使うようになりました。
   HTTP/1.1 では "Host:" HTTP ヘッダーが必須のため、"headers" 引数で指
   定しなければ自動で生成して送信します。

HTTPConnection.get_proxy_response_headers()

   CONNECT リクエストに対してプロキシサーバーから受信したレスポンスの
   ヘッダーを辞書で返します。

   CONNECT リクエストを送信していない場合、このメソッドは "None" を返
   します。

   Added in version 3.12.

HTTPConnection.connect()

   オブジェクトの作成時に指定したサーバーに接続します。 デフォルトでは
   、クライアントがまだ接続していない場合、リクエストの送信時に自動で
   呼び出されます。

   引数 "self"、"host"、"port" を指定して 監査イベント
   "http.client.connect" を送出します。

HTTPConnection.close()

   サーバへの接続を閉じます。

HTTPConnection.blocksize

   ファイル類似オブジェクトからメッセージ本体を送信する際のバッファー
   サイズ (バイト単位)。

   Added in version 3.7.

HTTPConnection.max_response_headers

   サービス拒否攻撃を防ぐために、許容するレスポンスヘッダーの数の上限
   。 デフォルトの上限は 100 です。 チャンク形式のレスポンスのトレーラ
   ー部にも同じ上限が適用されます。

   Added in version 3.15.

前述の "request()" メソッドの代わりに、以下の 4 つの関数を使ってリクエ
ストを段階的に送信することもできます。

HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)

   サーバへの接続が確立したら、最初にこのメソッドを呼び出さなくてはな
   りません。このメソッドは *method* 文字列、*url* 文字列、そして HTTP
   バージョン ("HTTP/1.1") からなる一行を送信します。"Host:" や
   "Accept-Encoding:" ヘッダの自動送信を無効にしたい場合 (例えば別のコ
   ンテンツエンコーディングを受け入れたい場合) には、*skip_host* や
   *skip_accept_encoding* を偽でない値に設定してください。

HTTPConnection.putheader(header, argument[, ...])

   **RFC 822** 形式のヘッダをサーバに送ります。この処理では、 *header*
   、コロンとスペース、そして最初の引数からなる 1 行をサーバに送ります
   。追加の引数を指定した場合、継続して各行にタブ一つと引数の入った引
   数行が送信されます。

HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)

   サーバに空行を送り、ヘッダ部が終了したことを通知します。オプション
   の *message_body* 引数を、リクエストに関連したメッセージボディを渡
   すのに使うことが出来ます。

   *encode_chunked* が "True" の場合、*message_body* の各イテレーショ
   ンの結果を **RFC 7230** の 3.3.1 節に従ってチャンク形式でエンコード
   します。 エンコード方法は *message_body* の型によって異なります。
   *message_body* が バッファーインターフェース を実装している場合、1
   つのチャンクになります。 *message_body* が
   "collections.abc.Iterable" の場合、各イテレーションの結果が 1 つの
   チャンクになります。 *message_body* が *file object* の場合、
   ".read()" の各呼び出しの結果が 1 つのチャンクになります。 このメソ
   ッドは、*message_body* の直後にチャンク形式のデータの終わりを自動で
   通知します。

   注釈:

     チャンク形式のエンコーディングの仕様上、リクエスト本体として渡し
     たイテレータが yield する空のチャンクは、チャンクエンコーダーに無
     視されます。 これは、不正なエンコードによって接続先サーバーがリク
     エストの読み込みを途中で終了するのを防ぐためです。

   バージョン 3.6 で変更: チャンク形式のエンコーディングのサポートと
   *encode_chunked* 引数を追加しました。

HTTPConnection.send(data)

   サーバーにデータを送信します。 このメソッドを直接使うのは、
   "endheaders()" を呼び出した後、"getresponse()" を呼び出す前に限りま
   す。

   引数 "self"、"data" を指定して 監査イベント "http.client.send" を送
   出します。


HTTPResponse オブジェクト
=========================

"HTTPResponse" インスタンスはサーバからのHTTPレスポンスをラップします
。これを使用してリクエストヘッダとエンティティボディへアクセスすること
ができます。レスポンスはイテレート可能なオブジェクトであり、また with
文と使うことも可能です。

バージョン 3.5 で変更: "io.BufferedIOBase" インターフェースを実装し、
読み込み操作をすべてサポートするようになりました。

HTTPResponse.read([amt])

   応答の本体全体か、*amt* バイトまで読み出して返します。

HTTPResponse.readinto(b)

   バッファ *b* にレスポンスボディの次のデータを最大 len(b) バイト読み
   込みます。何バイト読んだかを返します。

   Added in version 3.3.

HTTPResponse.getheader(name, default=None)

   ヘッダー *name* の値を返します。 *name* に一致するヘッダーがない場
   合は *default* を返します。 *name* という名前のヘッダーが複数ある場
   合は、すべての値を ', ' で連結して返します。 *default* が単一の文字
   列以外のイテラブルの場合は、同様にその要素をカンマで連結して返しま
   す。

HTTPResponse.getheaders()

   (header, value) のタプルからなるリストを返します。

HTTPResponse.fileno()

   ソケットの "fileno" を返します。

HTTPResponse.msg

   レスポンスヘッダーを保持する "http.client.HTTPMessage" インスタンス
   です。 "http.client.HTTPMessage" は "email.message.Message" のサブ
   クラスです。

HTTPResponse.version

   サーバが使用した HTTP プロトコルバージョンです。10 は HTTP/1.0 を、
   11 は HTTP/1.1 を表します。

HTTPResponse.url

   取得されたリソースの URL、主にリダイレクトが発生したかどうかを確認
   するために利用します。

HTTPResponse.headers

   Headers of the response in the form of an
   "email.message.EmailMessage" instance.

HTTPResponse.status

   サーバから返される状態コードです。

HTTPResponse.reason

   サーバから返される応答の理由文です。

HTTPResponse.debuglevel

   デバッグ用のフックです。 "debuglevel" が 0 より大きい場合、レスポン
   スの読み込みと解析の際にメッセージを標準出力に表示します。

HTTPResponse.closed

   ストリームが閉じている場合 "True" となります。

HTTPResponse.geturl()

   バージョン 3.9 で非推奨: 非推奨となったので "url" を使用してくださ
   い。

HTTPResponse.info()

   バージョン 3.9 で非推奨: 非推奨となったので "headers" を使用してく
   ださい。

HTTPResponse.getcode()

   バージョン 3.9 で非推奨: 非推奨となったので "status" を使用してくだ
   さい。


使用例
======

以下は "GET" リクエストの送信方法を示した例です:

   >>> import http.client
   >>> conn = http.client.HTTPSConnection("www.python.org")
   >>> conn.request("GET", "/")
   >>> r1 = conn.getresponse()
   >>> print(r1.status, r1.reason)
   200 OK
   >>> data1 = r1.read()  # 内容全体を返します。
   >>> # 以下はデータを小分けに読み込む例です。
   >>> conn.request("GET", "/")
   >>> r1 = conn.getresponse()
   >>> while chunk := r1.read(200):
   ...     print(repr(chunk))
   b'<!doctype html>\n<!--[if"...
   ...
   >>> # 無効なリクエストの例
   >>> conn = http.client.HTTPSConnection("docs.python.org")
   >>> conn.request("GET", "/parrot.spam")
   >>> r2 = conn.getresponse()
   >>> print(r2.status, r2.reason)
   404 Not Found
   >>> data2 = r2.read()
   >>> conn.close()

次の例のセッションでは、"HEAD" メソッドを利用しています。"HEAD" メソッ
ドは全くデータを返さないことに注目してください。

   >>> import http.client
   >>> conn = http.client.HTTPSConnection("www.python.org")
   >>> conn.request("HEAD", "/")
   >>> res = conn.getresponse()
   >>> print(res.status, res.reason)
   200 OK
   >>> data = res.read()
   >>> print(len(data))
   0
   >>> data == b''
   True

以下は "POST" メソッドを使うセッションの例です。

   >>> import http.client, urllib.parse
   >>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
   >>> headers = {"Content-type": "application/x-www-form-urlencoded",
   ...            "Accept": "text/plain"}
   >>> conn = http.client.HTTPConnection("bugs.python.org")
   >>> conn.request("POST", "", params, headers)
   >>> response = conn.getresponse()
   >>> print(response.status, response.reason)
   302 Found
   >>> data = response.read()
   >>> data
   b'Redirecting to <a href="https://bugs.python.org/issue12524">https://bugs.python.org/issue12524</a>'
   >>> conn.close()

クライアント側では、HTTP の "PUT" リクエストは "POST" リクエストとよく
似ています。 違いはサーバー側にあり、HTTP サーバーは "PUT" リクエスト
によるリソースの作成を許可します。 "urllib.request.Request" でも、適切
な "method" 属性を設定すれば独自の HTTP メソッドを扱えます。 以下は
"PUT" メソッドを使うセッションの例です。

   >>> # This creates an HTTP request
   >>> # with the content of BODY as the enclosed representation
   >>> # for the resource http://localhost:8080/file
   ...
   >>> import http.client
   >>> BODY = "***filecontents***"
   >>> conn = http.client.HTTPConnection("localhost", 8080)
   >>> conn.request("PUT", "/file", BODY)
   >>> response = conn.getresponse()
   >>> print(response.status, response.reason)
   200, OK


HTTPMessage オブジェクト
========================

class http.client.HTTPMessage(email.message.Message)

"http.client.HTTPMessage" のインスタンスは HTTP レスポンスヘッダを格納
します。 "email.message.Message" クラスを利用して実装されています。
