20.7. httplib --- HTTP プロトコルクライアント¶
Source code: Lib/httplib.py
このモジュールでは HTTP および HTTPS プロトコルのクライアント側を実装しているクラスを定義しています。通常、このモジュールは直接使いません --- urllib モジュールが HTTP や HTTPS を使った URL を扱う上でこのモジュールを使います。
参考
より高水準の HTTP クライアントインターフェイスとしては Requests package がお奨めです。
注釈
HTTPS のサポートは、socket モジュールが SSL サポート付きでコンパイルされている場合にのみ利用できます。
注釈
このモジュールは Python 2.0 で大幅に公開インターフェイスを変更しました。 HTTP クラスは 1.5.2 との後方互換性のためだけに残されています。新しいコードではこれは使ってはいけません。このドキュメントでは説明しないので、docstring をみてください。
このモジュールでは以下のクラスを提供しています:
-
class
httplib.HTTPConnection(host[, port[, strict[, timeout[, source_address]]]])¶ HTTPConnectionインスタンスは、HTTP サーバとの一回のトランザクションを表現します。インスタンスの生成はホスト名とオプションのポート番号を与えて行います。ポート番号を指定しなかった場合、ホスト名文字列がhost:portの形式であれば、ホスト名からポート番号を導き、そうでない場合には標準の HTTP ポート番号 (80) を使います。オプションパラメータ strict (デフォルトは偽) を真にすると、ステータス行が HTTP/1.0 あるいは HTTP/1.1 として解釈出来ない場合にBadStatusLineを送出します。オプションの引数 timeout が渡された場合、ブロックする処理 (コネクション接続など) のタイムアウト時間 (秒数) として利用されます (渡されなかった場合は、グローバルのデフォルトタイムアウト設定が利用されます)。オプションの引数 source_address を (host, port) という形式のタプルにすると HTTP 接続の接続元アドレスとして使用します。例えば、以下の呼び出しは全て同じサーバの同じポートに接続するインスタンスを生成します:
>>> h1 = httplib.HTTPConnection('www.cwi.nl') >>> h2 = httplib.HTTPConnection('www.cwi.nl:80') >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80) >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10)
バージョン 2.0 で追加.
バージョン 2.6 で変更: timeout が追加されました。
バージョン 2.7 で変更: source_address が追加されました。
-
class
httplib.HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout[, source_address[, context]]]]]]])¶ HTTPConnectionのサブクラスはセキュア・サーバとやりとりする為の SSL を使う場合に用います。デフォルトのポート番号は443です。context が指定されれば、それは様々な SSL オプションを記述するssl.SSLContextインスタンスでなければなりません。key_file と cert_file は廃止されたので、代わりに
ssl.SSLContext.load_cert_chain()を使うか、またはssl.create_default_context()が、システムが信頼する CA 証明書をあなたのために選んでくれます。ベストプラクティスに関するより良い情報が セキュリティで考慮すべき点 にありますのでお読みください。
バージョン 2.0 で追加.
バージョン 2.6 で変更: timeout が追加されました。
バージョン 2.7 で変更: source_address が追加されました。
バージョン 2.7.9 で変更: context が追加されました。
このクラスは今や全ての必要な証明書とホスト名の検証をデフォルトで行うようになりました。昔の、検証を行わない振る舞いに戻したければ、 context に
ssl._create_unverified_context()を渡すことで出来ます。
-
class
httplib.HTTPResponse(sock, debuglevel=0, strict=0)¶ コネクションに成功したときに、このクラスのインスタンスが返されます。ユーザーから直接利用されることはありません。
バージョン 2.0 で追加.
-
class
httplib.HTTPMessage¶ HTTPMessageのインスタンスは、 HTTP レスポンスヘッダを格納するために利用されます。mimetools.Messageクラスを利用して実装されていて、 HTTP ヘッダを扱うための便利な関数を提供しています。このクラスはユーザーが直接インスタンス生成するものではありません。
必要に応じて以下の例外が送出されます:
-
exception
httplib.NotConnected¶ HTTPExceptionサブクラスです。バージョン 2.0 で追加.
-
exception
httplib.InvalidURL¶ HTTPExceptionのサブクラスです。ポート番号を指定したものの、その値が数字でなかったり空のオブジェクトであった場合に送出されます。バージョン 2.3 で追加.
-
exception
httplib.UnknownProtocol¶ HTTPExceptionサブクラスです。バージョン 2.0 で追加.
-
exception
httplib.UnknownTransferEncoding¶ HTTPExceptionサブクラスです。バージョン 2.0 で追加.
-
exception
httplib.UnimplementedFileMode¶ HTTPExceptionサブクラスです。バージョン 2.0 で追加.
-
exception
httplib.IncompleteRead¶ HTTPExceptionサブクラスです。バージョン 2.0 で追加.
-
exception
httplib.ImproperConnectionState¶ HTTPExceptionサブクラスです。バージョン 2.0 で追加.
-
exception
httplib.CannotSendRequest¶ ImproperConnectionStateのサブクラスです。バージョン 2.0 で追加.
-
exception
httplib.CannotSendHeader¶ ImproperConnectionStateのサブクラスです。バージョン 2.0 で追加.
-
exception
httplib.ResponseNotReady¶ ImproperConnectionStateのサブクラスです。バージョン 2.0 で追加.
-
exception
httplib.BadStatusLine¶ HTTPExceptionのサブクラスです。サーバが理解できない HTTP 状態コードで応答した場合に送出されます。バージョン 2.0 で追加.
このモジュールで定義されている定数は以下の通りです:
-
httplib.HTTP_PORT¶ HTTP プロトコルの標準のポート (通常は
80) です。
-
httplib.HTTPS_PORT¶ HTTPS プロトコルの標準のポート (通常は
443) です。
また、整数の状態コードについて以下の定数が定義されています:
定数 |
|
定義 |
|---|---|---|
|
|
HTTP/1.1, RFC 2616, Section 10.1.1 |
|
|
HTTP/1.1, RFC 2616, Section 10.1.2 |
|
|
WEBDAV, RFC 2518, Section 10.1 |
|
|
HTTP/1.1, RFC 2616, Section 10.2.1 |
|
|
HTTP/1.1, RFC 2616, Section 10.2.2 |
|
|
HTTP/1.1, RFC 2616, Section 10.2.3 |
|
|
HTTP/1.1, RFC 2616, Section 10.2.4 |
|
|
HTTP/1.1, RFC 2616, Section 10.2.5 |
|
|
HTTP/1.1, RFC 2616, Section 10.2.6 |
|
|
HTTP/1.1, RFC 2616, Section 10.2.7 |
|
|
WEBDAV RFC 2518, Section 10.2 |
|
|
Delta encoding in HTTP, RFC 3229, Section 10.4.1 |
|
|
HTTP/1.1, RFC 2616, Section 10.3.1 |
|
|
HTTP/1.1, RFC 2616, Section 10.3.2 |
|
|
HTTP/1.1, RFC 2616, Section 10.3.3 |
|
|
HTTP/1.1, RFC 2616, Section 10.3.4 |
|
|
HTTP/1.1, RFC 2616, Section 10.3.5 |
|
|
HTTP/1.1, RFC 2616, Section 10.3.6 |
|
|
HTTP/1.1, RFC 2616, Section 10.3.8 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.1 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.2 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.3 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.4 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.5 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.6 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.7 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.8 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.9 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.10 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.11 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.12 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.13 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.14 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.15 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.16 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.17 |
|
|
HTTP/1.1, RFC 2616, Section 10.4.18 |
|
|
WEBDAV, RFC 2518, Section 10.3 |
|
|
WEBDAV RFC 2518, Section 10.4 |
|
|
WEBDAV, RFC 2518, Section 10.5 |
|
|
HTTP Upgrade to TLS, RFC 2817, Section 6 |
|
|
HTTP/1.1, RFC 2616, Section 10.5.1 |
|
|
HTTP/1.1, RFC 2616, Section 10.5.2 |
|
|
HTTP/1.1 RFC 2616, Section 10.5.3 |
|
|
HTTP/1.1, RFC 2616, Section 10.5.4 |
|
|
HTTP/1.1 RFC 2616, Section 10.5.5 |
|
|
HTTP/1.1, RFC 2616, Section 10.5.6 |
|
|
WEBDAV, RFC 2518, Section 10.6 |
|
|
An HTTP Extension Framework, RFC 2774, Section 7 |
-
httplib.responses¶ このディクショナリは、HTTP 1.1ステータスコードをW3Cの名前にマップしたものです。
例:
httplib.responses[httplib.NOT_FOUND]は'Not Found'を示します。バージョン 2.5 で追加.
20.7.1. HTTPConnection オブジェクト¶
HTTPConnection インスタンスには以下のメソッドがあります:
-
HTTPConnection.request(method, url[, body[, headers]])¶ このメソッドは、 HTTP 要求メソッド method およびセレクタ url を使って、要求をサーバに送ります。body 引数を指定する場合、ヘッダが終了した後に送信する文字列データでなければなりません。もしくは、開いているファイルオブジェクトを body に渡すこともできます。その場合、そのファイルの内容が送信されます。このファイルオブジェクトは、
fileno()とread()メソッドをサポートしている必要があります。headers 引数は要求と同時に送信される拡張 HTTP ヘッダの内容からなるマップ型でなくてはなりません。headers で Content-Length が提供されない場合、全てのメソッドにおいて、body の長さがわかるならば、つまり
strとしての長さあるいはファイルのディスク上のサイズをもとに、Content-Length ヘッダは自動的に正しい値にセットされます。 body がNoneの場合はそのヘッダは、body がないメソッドではセットされず、body が期待されているメソッド(PUT,POST,PATCH)では0にセットします。バージョン 2.6 で変更: body にファイルオブジェクトを渡せるようになりました
-
HTTPConnection.getresponse()¶ サーバに対して HTTP 要求を送り出した後に呼び出されなければりません。要求に対する応答を取得します。
HTTPResponseインスタンスを返します。注釈
すべての応答を読み込んでからでなければ新しい要求をサーバに送ることはできないことに注意しましょう。
-
HTTPConnection.set_debuglevel(level)¶ デバッグレベル (印字されるデバッグ出力の量) を設定します。デフォルトのデバッグレベルは
0で、デバッグ出力を全く印字しません。
-
HTTPConnection.set_tunnel(host, port=None, headers=None)¶ Set the host and the port for HTTP Connect Tunnelling. Normally used when it is required to do HTTPS Connection through a proxy server.
ヘッダのパラメータは CONNECT リクエストで送信するために他の HTTP ヘッダにマッピングされます。
バージョン 2.7 で追加.
-
HTTPConnection.connect()¶ オブジェクトを生成するときに指定したサーバに接続します。
-
HTTPConnection.close()¶ サーバへの接続を閉じます。
上で説明した request() メソッドを使うかわりに、以下の4つの関数を使用して要求をステップバイステップで送信することもできます。
-
HTTPConnection.putrequest(request, selector[, skip_host[, skip_accept_encoding]])¶ サーバへの接続が確立したら、最初にこのメソッドを呼び出さなくてはなりません。このメソッドは request 文字列、selector 文字列、そして HTTP バージョン (
HTTP/1.1) からなる一行を送信します。Host:やAccept-Encoding:ヘッダの自動送信を無効にしたい場合 (例えば別のコンテンツエンコーディングを受け入れたい場合) には、skip_host や skip_accept_encoding を偽でない値に設定してください。バージョン 2.4 で変更: skip_accept_encoding 引数が追加されました。
-
HTTPConnection.putheader(header, argument[, ...])¶ RFC 822 形式のヘッダをサーバに送ります。この処理では、 header 、コロンとスペース、そして最初の引数からなる 1 行をサーバに送ります。追加の引数を指定した場合、継続して各行にタブ一つと引数の入った引数行が送信されます。
-
HTTPConnection.endheaders(message_body=None)¶ サーバに空行を送り、ヘッダ部が終了したことを通知します。オプションの message_body 引数を、リクエストに関連したメッセージボディを渡すのに使うことが出来ます。
バージョン 2.7 で変更: message_body が追加されました。
-
HTTPConnection.send(data)¶ サーバにデータを送ります。このメソッドは
endheaders()が呼び出された直後で、かつgetresponse()が呼び出される前に使わなければなりません。
20.7.2. HTTPResponse オブジェクト¶
HTTPResponse インスタンスは以下のメソッドと属性を持っています:
-
HTTPResponse.read([amt])¶ 応答の本体全体か、amt バイトまで読み出して返します。
-
HTTPResponse.getheader(name[, default])¶ ヘッダ name の内容を取得して返すか、該当するヘッダがない場合には default を返します。
-
HTTPResponse.getheaders()¶ (header, value) のタプルからなるリストを返します。
バージョン 2.4 で追加.
-
HTTPResponse.fileno()¶ 下層のソケットの
filenoを返します。
-
HTTPResponse.msg¶ 応答ヘッダを含む
mimetools.Messageインスタンスです。
-
HTTPResponse.version¶ サーバが使用した HTTP プロトコルバージョンです。10 は HTTP/1.0 を、11 は HTTP/1.1 を表します。
-
HTTPResponse.status¶ サーバから返される状態コードです。
-
HTTPResponse.reason¶ サーバから返される応答の理由文です。
20.7.3. 例¶
以下は GET リクエストの送信方法を示した例です:
>>> import httplib
>>> conn = httplib.HTTPSConnection("www.python.org")
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> print r1.status, r1.reason
200 OK
>>> data1 = r1.read()
>>> conn.request("GET", "/")
>>> r2 = conn.getresponse()
>>> print r2.status, r2.reason
404 Not Found
>>> data2 = r2.read()
>>> conn.close()
次の例のセッションでは、HEAD メソッドを利用しています。HEAD メソッドは全くデータを返さないことに注目してください。
>>> import httplib
>>> conn = httplib.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 == ''
True
以下は POST リクエストの送信方法を示した例です:
>>> import httplib, urllib
>>> params = urllib.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
... "Accept": "text/plain"}
>>> conn = httplib.HTTPConnection("bugs.python.org")
>>> conn.request("POST", "", params, headers)
>>> response = conn.getresponse()
>>> print response.status, response.reason
302 Found
>>> data = response.read()
>>> data
'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
>>> conn.close()
HTTP PUT リクエストは POST リクエストととても似ています。違いは、HTTP サーバが PUT リクエストによりリソースの作成をサーバ側にすることだけです。httplib を使って PUT リクエストを行うセッションの例です:
>>> # This creates an HTTP message
>>> # with the content of BODY as the enclosed representation
>>> # for the resource http://localhost:8080/foobar
...
>>> import httplib
>>> BODY = "***filecontents***"
>>> conn = httplib.HTTPConnection("localhost", 8080)
>>> conn.request("PUT", "/file", BODY)
>>> response = conn.getresponse()
>>> print response.status, response.reason
200, OK