20.7. httplib — HTTP プロトコルクライアント

注釈

httplib モジュールは、Python 3.0 では http.client にリネームされました。2to3 ツールが自動的にソースコードのimportを修正します。

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_filecert_file は廃止されたので、代わりに ssl.SSLContext.load_cert_chain() を使うか、または ssl.create_default_context() が、システムが信頼する CA 証明書をあなたのために選んでくれます。

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

バージョン 2.0 で追加.

バージョン 2.6 で変更: timeout が追加されました。

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

バージョン 2.7.9 で変更: context が追加されました。

このクラスは今や全ての必要な証明書とホスト名の検証をデフォルトで行うようになりました。昔の、検証を行わない振る舞いに戻したければ、 contextssl._create_unverified_context() を渡すことで出来ます。

class httplib.HTTPResponse(sock, debuglevel=0, strict=0)

コネクションに成功したときに、このクラスのインスタンスが返されます。ユーザーから直接利用されることはありません。

バージョン 2.0 で追加.

class httplib.HTTPMessage

HTTPMessage のインスタンスは、 HTTP レスポンスヘッダを格納するために利用されます。 mimetools.Message クラスを利用して実装されていて、 HTTP ヘッダを扱うための便利な関数を提供しています。このクラスはユーザーが直接インスタンス生成するものではありません。

必要に応じて以下の例外が送出されます:

exception httplib.HTTPException

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

バージョン 2.0 で追加.

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) です。

また、整数の状態コードについて以下の定数が定義されています:

定数

定義

CONTINUE 100 HTTP/1.1, RFC 2616, Section 10.1.1
SWITCHING_PROTOCOLS 101 HTTP/1.1, RFC 2616, Section 10.1.2
PROCESSING 102 WEBDAV, RFC 2518, Section 10.1
OK 200 HTTP/1.1, RFC 2616, Section 10.2.1
CREATED 201 HTTP/1.1, RFC 2616, Section 10.2.2
ACCEPTED 202 HTTP/1.1, RFC 2616, Section 10.2.3
NON_AUTHORITATIVE_INFORMATION 203 HTTP/1.1, RFC 2616, Section 10.2.4
NO_CONTENT 204 HTTP/1.1, RFC 2616, Section 10.2.5
RESET_CONTENT 205 HTTP/1.1, RFC 2616, Section 10.2.6
PARTIAL_CONTENT 206 HTTP/1.1, RFC 2616, Section 10.2.7
MULTI_STATUS 207 WEBDAV RFC 2518, Section 10.2
IM_USED 226 Delta encoding in HTTP, RFC 3229, Section 10.4.1
MULTIPLE_CHOICES 300 HTTP/1.1, RFC 2616, Section 10.3.1
MOVED_PERMANENTLY 301 HTTP/1.1, RFC 2616, Section 10.3.2
FOUND 302 HTTP/1.1, RFC 2616, Section 10.3.3
SEE_OTHER 303 HTTP/1.1, RFC 2616, Section 10.3.4
NOT_MODIFIED 304 HTTP/1.1, RFC 2616, Section 10.3.5
USE_PROXY 305 HTTP/1.1, RFC 2616, Section 10.3.6
TEMPORARY_REDIRECT 307 HTTP/1.1, RFC 2616, Section 10.3.8
BAD_REQUEST 400 HTTP/1.1, RFC 2616, Section 10.4.1
UNAUTHORIZED 401 HTTP/1.1, RFC 2616, Section 10.4.2
PAYMENT_REQUIRED 402 HTTP/1.1, RFC 2616, Section 10.4.3
FORBIDDEN 403 HTTP/1.1, RFC 2616, Section 10.4.4
NOT_FOUND 404 HTTP/1.1, RFC 2616, Section 10.4.5
METHOD_NOT_ALLOWED 405 HTTP/1.1, RFC 2616, Section 10.4.6
NOT_ACCEPTABLE 406 HTTP/1.1, RFC 2616, Section 10.4.7
PROXY_AUTHENTICATION_REQUIRED 407 HTTP/1.1, RFC 2616, Section 10.4.8
REQUEST_TIMEOUT 408 HTTP/1.1, RFC 2616, Section 10.4.9
CONFLICT 409 HTTP/1.1, RFC 2616, Section 10.4.10
GONE 410 HTTP/1.1, RFC 2616, Section 10.4.11
LENGTH_REQUIRED 411 HTTP/1.1, RFC 2616, Section 10.4.12
PRECONDITION_FAILED 412 HTTP/1.1, RFC 2616, Section 10.4.13
REQUEST_ENTITY_TOO_LARGE 413 HTTP/1.1, RFC 2616, Section 10.4.14
REQUEST_URI_TOO_LONG 414 HTTP/1.1, RFC 2616, Section 10.4.15
UNSUPPORTED_MEDIA_TYPE 415 HTTP/1.1, RFC 2616, Section 10.4.16
REQUESTED_RANGE_NOT_SATISFIABLE 416 HTTP/1.1, RFC 2616, Section 10.4.17
EXPECTATION_FAILED 417 HTTP/1.1, RFC 2616, Section 10.4.18
UNPROCESSABLE_ENTITY 422 WEBDAV, RFC 2518, Section 10.3
LOCKED 423 WEBDAV RFC 2518, Section 10.4
FAILED_DEPENDENCY 424 WEBDAV, RFC 2518, Section 10.5
UPGRADE_REQUIRED 426 HTTP Upgrade to TLS, RFC 2817, Section 6
INTERNAL_SERVER_ERROR 500 HTTP/1.1, RFC 2616, Section 10.5.1
NOT_IMPLEMENTED 501 HTTP/1.1, RFC 2616, Section 10.5.2
BAD_GATEWAY 502 HTTP/1.1 RFC 2616, Section 10.5.3
SERVICE_UNAVAILABLE 503 HTTP/1.1, RFC 2616, Section 10.5.4
GATEWAY_TIMEOUT 504 HTTP/1.1 RFC 2616, Section 10.5.5
HTTP_VERSION_NOT_SUPPORTED 505 HTTP/1.1, RFC 2616, Section 10.5.6
INSUFFICIENT_STORAGE 507 WEBDAV, RFC 2518, Section 10.6
NOT_EXTENDED 510 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 ヘッダは自動的に正しい値にセットされます。 bodyNone の場合はそのヘッダは、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_hostskip_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