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.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引数で HTTPHost:ヘッダーを指定しなければ、自動で生成して送信します。例えば、ローカルのポート 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.EmailMessageinstance.
- HTTPResponse.status¶
サーバから返される状態コードです。
- HTTPResponse.reason¶
サーバから返される応答の理由文です。
- HTTPResponse.debuglevel¶
デバッグ用のフックです。
debuglevelが 0 より大きい場合、レスポンスの読み込みと解析の際にメッセージを標準出力に表示します。
- HTTPResponse.closed¶
ストリームが閉じている場合
Trueとなります。
使用例¶
以下は 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 クラスを利用して実装されています。