http.client — HTTPプロトコルクライアント—Pythonドキュメント
http.client —HTTPプロトコルクライアント
ソースコード: :source: `Lib / http / client.py`
このモジュールは、HTTPおよびHTTPSプロトコルのクライアント側を実装するクラスを定義します。 通常は直接使用されません—モジュール urllib.request は、HTTPおよびHTTPSを使用するURLを処理するためにこれを使用します。
このモジュールは、次のクラスを提供します。
- class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None, blocksize=8192)
HTTPConnection インスタンスは、HTTPサーバーとの1つのトランザクションを表します。 ホストとオプションのポート番号を渡してインスタンス化する必要があります。 ポート番号が渡されない場合、ポートは
host:port
の形式であればホスト文字列から抽出され、それ以外の場合はデフォルトのHTTPポート(80)が使用されます。 オプションの timeout パラメーターが指定されている場合、ブロック操作(接続試行など)はその秒数後にタイムアウトします(指定されていない場合は、グローバルなデフォルトのタイムアウト設定が使用されます)。 オプションの source_address パラメーターは、HTTP接続の送信元アドレスとして使用する(ホスト、ポート)のタプルにすることができます。 オプションの blocksize パラメーターは、ファイルのようなメッセージ本文を送信するためのバッファーサイズをバイト単位で設定します。たとえば、次の呼び出しはすべて、同じホストとポートでサーバーに接続するインスタンスを作成します。
>>> 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 パラメーターが削除されました。 HTTP0.9スタイルの「SimpleResponses」はサポートされなくなりました。
バージョン3.7で変更: blocksize パラメーターが追加されました。
- class http.client.HTTPSConnection(host, port=None, key_file=None, cert_file=None, [timeout, ]source_address=None, *, context=None, check_hostname=None, blocksize=8192)
安全なサーバーとの通信にSSLを使用する HTTPConnection のサブクラス。 デフォルトのポートは
443
です。 context を指定する場合は、さまざまなSSLオプションを記述する ssl.SSLContext インスタンスである必要があります。ベストプラクティスの詳細については、セキュリティに関する考慮事項をお読みください。
バージョン3.2で変更: source_address 、 context 、および check_hostname が追加されました。
バージョン3.2で変更:このクラスは、可能であれば(つまり、 ssl.HAS_SNI がtrueの場合)HTTPS仮想ホストをサポートするようになりました。
バージョン3.4で変更: strict パラメーターが削除されました。 HTTP0.9スタイルの「SimpleResponses」はサポートされなくなりました。
バージョン3.4.3で変更:このクラスは、デフォルトで必要なすべての証明書とホスト名のチェックを実行するようになりました。 以前の未確認の動作に戻すには、動作
ssl._create_unverified_context()
を context パラメーターに渡すことができます。バージョン3.8で変更:このクラスは、デフォルトのコンテキストに対して、または cert_file がカスタムコンテキスト。
バージョン3.6以降非推奨: key_file および cert_file は非推奨になり、 context が優先されます。 代わりに ssl.SSLContext.load_cert_chain()を使用するか、 ssl.create_default_context()にシステムの信頼できるCA証明書を選択させてください。
check_hostname パラメーターも非推奨です。 代わりに、 context の ssl.SSLContext.check_hostname 属性を使用する必要があります。
- class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)
接続に成功するとインスタンスが返されるクラス。 ユーザーが直接インスタンス化することはありません。
バージョン3.4で変更: strict パラメーターが削除されました。 HTTP0.9スタイルの「SimpleResponses」はサポートされなくなりました。
このモジュールは、次の機能を提供します。
- http.client.parse_headers(fp)
HTTP要求/応答を表すファイルポインタ fp からヘッダーを解析します。 ファイルは
BufferedIOBase
リーダーである必要があります(つまり、 テキストではありません)、有効な RFC 2822 スタイルのヘッダーを提供する必要があります。この関数は、ヘッダーフィールドを保持するが、ペイロードを保持しない
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
- ImpproperConnectionState のサブクラス。
- exception http.client.CannotSendHeader
- ImpproperConnectionState のサブクラス。
- exception http.client.ResponseNotReady
- ImpproperConnectionState のサブクラス。
- exception http.client.BadStatusLine
- HTTPException のサブクラス。 サーバーが理解できないHTTPステータスコードで応答した場合に発生します。
- exception http.client.LineTooLong
- HTTPException のサブクラス。 サーバーからHTTPプロトコルで過度に長い行を受信した場合に発生します。
- exception http.client.RemoteDisconnected
ConnectionResetError および BadStatusLine のサブクラス。 HTTPConnection.getresponse()によって発生し、応答を読み取ろうとしても接続からデータが読み取られず、リモートエンドが接続を閉じたことを示します。
バージョン3.5の新機能:以前は、 BadStatusLine
()
が発生していました。
このモジュールで定義されている定数は次のとおりです。
- http.client.HTTP_PORT
- HTTPプロトコルのデフォルトポート(常に
80
)。
- http.client.HTTPS_PORT
- HTTPSプロトコルのデフォルトポート(常に
443
)。
- http.client.responses
このディクショナリは、HTTP1.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リクエストメソッドメソッドとセレクター url を使用してサーバーにリクエストが送信されます。
body が指定されている場合、指定されたデータはヘッダーが終了した後に送信されます。 str 、バイトのようなオブジェクト、開いているファイルオブジェクト、またはバイトの反復可能オブジェクトの場合があります。 body が文字列の場合、HTTPのデフォルトであるISO-8859-1としてエンコードされます。 バイトのようなオブジェクトの場合、バイトはそのまま送信されます。 ファイルオブジェクトの場合、ファイルの内容が送信されます。 このファイルオブジェクトは、少なくとも
read()
メソッドをサポートする必要があります。 ファイルオブジェクトが io.TextIOBase のインスタンスである場合、read()
メソッドによって返されるデータはISO-8859-1としてエンコードされます。それ以外の場合、read()
によって返されるデータは]はそのまま送信されます。 body がイテラブルの場合、イテラブルの要素は、イテラブルが使い果たされるまでそのまま送信されます。headers 引数は、リクエストとともに送信する追加のHTTPヘッダーのマッピングである必要があります。
headers にContent-LengthもTransfer-Encodingも含まれていないが、リクエスト本文がある場合、これらのヘッダーフィールドの1つが自動的に追加されます。 body が
None
の場合、本体を期待するメソッド(PUT
、POST
)のContent-Lengthヘッダーは0
に設定されます。 、およびPATCH
)。 body が、 file でもない文字列またはバイトのようなオブジェクトである場合、Content-Lengthヘッダーはその長さに設定されます。 その他のタイプの body (一般にファイルとイテラブル)はチャンクエンコードされ、Content-Lengthの代わりにTransfer-Encodingヘッダーが自動的に設定されます。encode_chunked 引数は、Transfer-Encodingが headers で指定されている場合にのみ関係します。 encode_chunked が
False
の場合、HTTPConnectionオブジェクトは、すべてのエンコーディングが呼び出し元のコードによって処理されると想定します。True
の場合、本文はチャンクエンコードされます。ノート
チャンク転送エンコーディングがHTTPプロトコルバージョン1.1に追加されました。 HTTPサーバーがHTTP1.1を処理することがわかっている場合を除き、呼び出し元はContent-Lengthを指定するか、 str またはファイルではないバイトのようなオブジェクトを本文表現として渡す必要があります。
バージョン3.2の新機能: body を反復可能にできるようになりました。
バージョン3.6で変更: Content-LengthもTransfer-Encodingも headers に設定されていない場合、ファイルおよび反復可能な body オブジェクトがチャンクエンコードされるようになりました。 encode_chunked 引数が追加されました。 ファイルオブジェクトのContent-Lengthを決定する試みは行われません。
- HTTPConnection.getresponse()
サーバーからの応答を取得するために要求が送信された後に呼び出す必要があります。 HTTPResponse インスタンスを返します。
ノート
サーバーに新しい要求を送信する前に、応答全体を読んでおく必要があることに注意してください。
バージョン3.5で変更: ConnectionError またはサブクラスが発生した場合、 HTTPConnection オブジェクトは、新しい要求が送信されたときに再接続できるようになります。
- HTTPConnection.set_debuglevel(level)
デバッグレベルを設定します。 デフォルトのデバッグレベルは
0
です。これは、デバッグ出力が出力されないことを意味します。0
より大きい値を指定すると、現在定義されているすべてのデバッグ出力がstdoutに出力されます。debuglevel
は、作成された新しい HTTPResponse オブジェクトに渡されます。バージョン3.1の新機能。
- HTTPConnection.set_tunnel(host, port=None, headers=None)
HTTP接続トンネリングのホストとポートを設定します。 これにより、プロキシサーバーを介して接続を実行できます。
ホストとポートの引数は、トンネリングされた接続のエンドポイントを指定します(つまり、 CONNECT要求に含まれるアドレス。ではなくプロキシサーバーのアドレス)。
headers引数は、CONNECTリクエストで送信する追加のHTTPヘッダーのマッピングである必要があります。
たとえば、ポート8080でローカルに実行されているHTTPSプロキシサーバーをトンネリングするには、プロキシのアドレスを HTTPSConnection コンストラクターに渡し、最終的に HTTPSConnection コンストラクターに到達するホストのアドレスを渡します。 X234X] set_tunnel()メソッド:
>>> import http.client >>> conn = http.client.HTTPSConnection("localhost", 8080) >>> conn.set_tunnel("www.python.org") >>> conn.request("HEAD","/index.html")
バージョン3.2の新機能。
- HTTPConnection.connect()
- オブジェクトの作成時に指定したサーバーに接続します。 デフォルトでは、クライアントがまだ接続していない場合、これはリクエストを行うときに自動的に呼び出されます。
- HTTPConnection.close()
- サーバーへの接続を閉じます。
- HTTPConnection.blocksize
ファイルのようなメッセージ本文を送信するためのバイト単位のバッファサイズ。
バージョン3.7の新機能。
上記の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 をFalse以外の値で指定します。
- HTTPConnection.putheader(header, argument[, ...])
- RFC 822 スタイルのヘッダーをサーバーに送信します。 ヘッダー、コロンとスペース、および最初の引数で構成される行をサーバーに送信します。 さらに引数を指定すると、タブと引数で構成される継続行が送信されます。
- HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)
ヘッダーの終わりを示す空白行をサーバーに送信します。 オプションの message_body 引数を使用して、リクエストに関連付けられたメッセージ本文を渡すことができます。
encode_chunked が
True
の場合、 message_body の各反復の結果は、 RFC 7230 で指定されているようにチャンクエンコードされます。 ]、セクション3.3.1。 データのエンコード方法は、 message_body のタイプによって異なります。 message_body がバッファインターフェイスを実装している場合、エンコーディングは単一のチャンクになります。 message_body が collections.abc.Iterable の場合、 message_body の各反復はチャンクになります。 message_body がファイルオブジェクトの場合、.read()
を呼び出すたびにチャンクが発生します。 このメソッドは、 message_body の直後にチャンクエンコードされたデータの終わりを自動的に通知します。ノート
チャンクエンコーディングの仕様により、イテレータ本体によって生成された空のチャンクは、チャンクエンコーダによって無視されます。 これは、エンコードの形式が正しくないために、ターゲットサーバーによる要求の読み取りが途中で終了するのを防ぐためです。
バージョン3.6の新機能:チャンクエンコーディングのサポート。 encode_chunked パラメーターが追加されました。
- HTTPConnection.send(data)
- サーバーにデータを送信します。 これは、 endheaders()メソッドが呼び出された後、 getresponse()が呼び出される前にのみ直接使用する必要があります。
HTTPResponseオブジェクト
HTTPResponse インスタンスは、サーバーからのHTTP応答をラップします。 リクエストヘッダーとエンティティ本体へのアクセスを提供します。 応答は反復可能なオブジェクトであり、withステートメントで使用できます。
バージョン3.5での変更: io.BufferedIOBase インターフェイスが実装され、すべてのリーダー操作がサポートされるようになりました。
- HTTPResponse.read([amt])
- 応答本文、または次の amt バイトまでを読み取って返します。
- HTTPResponse.readinto(b)
応答本文の次のlen(b)バイトまでをバッファ b に読み込みます。 読み取られたバイト数を返します。
バージョン3.3の新機能。
- HTTPResponse.getheader(name, default=None)
- ヘッダー name の値を返します。 name に一致するヘッダーがない場合は、 default を返します。 name という名前のヘッダーが複数ある場合は、「、」で結合されたすべての値を返します。 'default'が単一の文字列以外の反復可能である場合、その要素は同様にコンマで結合されて返されます。
- HTTPResponse.getheaders()
- (ヘッダー、値)タプルのリストを返します。
- HTTPResponse.fileno()
- 基になるソケットの
fileno
を返します。
- HTTPResponse.msg
- 応答ヘッダーを含む
http.client.HTTPMessage
インスタンス。http.client.HTTPMessage
は、 email.message.Message のサブクラスです。
- HTTPResponse.version
- サーバーが使用するHTTPプロトコルのバージョン。 HTTP / 1.0の場合は10、HTTP /1.1の場合は11。
- HTTPResponse.status
- サーバーから返されたステータスコード。
- HTTPResponse.reason
- サーバーから返された理由句。
- HTTPResponse.debuglevel
- デバッグフック。 debuglevel がゼロより大きい場合、応答が読み取られて解析されるときに、メッセージがstdoutに出力されます。
- 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() # This will return entire content.
>>> # The following example demonstrates reading data in chunks.
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> while chunk := r1.read(200):
... print(repr(chunk))
b'<!doctype html>\n<!--[if"...
...
>>> # Example of an invalid request
>>> 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="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
>>> conn.close()
クライアント側のHTTP PUT
リクエストは、POST
リクエストと非常によく似ています。 違いは、HTTPサーバーがPUT
リクエストを介してリソースを作成できるようにするサーバー側のみです。 カスタムHTTPメソッドは、適切なメソッド属性を設定することにより、 urllib.request.Request でも処理されることに注意してください。 http.clientを使用してPUT
リクエストを送信する方法を示すセッションの例を次に示します。
>>> # This creates an HTTP message
>>> # 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オブジェクト
http.client.HTTPMessage
インスタンスは、HTTP応答からのヘッダーを保持します。 email.message.Message クラスを使用して実装されます。