このモジュールでは HTTP および HTTPS プロトコルのクライアント側を実装しているクラスを定義しています。通常、このモジュールは直接使いません — urllib モジュールが HTTP や HTTPS を使った URL を扱う上でこのモジュールを使います。
ノート
HTTPS のサポートは、SSL をサポートするように socket モジュールをコンパイルした場合にのみ利用できます。
このモジュールでは以下のクラスを提供しています:
HTTPConnection インスタンスは、HTTP サーバとの一回のトランザクションを表現します。インスタンスの生成はホスト名と オプションのポート番号を与えて行います。 ポート番号を指定しなかった場合、ホスト名文字列が host:port の形式であれば、ホスト名からポート番号を導き、そうでない場合には標準の HTTP ポート番号 (80) を使います。
オプションの引数 strict に True が渡された場合(デフォルトでは False)、 ステータスラインが正しい(valid) HTTP/1.0 もしくは 1.1 status line としてパースできなかった時に、 BadStatusLine 例外を発生させます。
オプションの引数 timeout が渡された場合、ブロックする処理(コネクション接続など) のタイムアウト時間(秒数)として利用されます。(渡されなかった場合は、グローバルのデフォルト タイムアウト設定が利用されます。)
例えば、以下の呼び出しは全て同じサーバの同じポートに接続するインスタンスを生成します:
>>> 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 引数が追加されました
HTTPConnection のサブクラスで、セキュアなサーバと通信するために SSL を使います。標準のポート番号は 443 です。 key_file には、秘密鍵を格納したPEM形式ファイルのファイル名を指定します。 cert_file には、PEM形式の証明書チェーンファイルを指定します。
警告
この関数は証明書の検査を行いません!
バージョン 2.6 で変更: timeout 引数が追加されました
コネクションに成功したときに、このクラスのインスタンスが返されます。 ユーザーから直接利用されることはありません。
バージョン 2.0 で追加.
必要に応じて以下の例外が送出されます:
HTTPException サブクラスです。
バージョン 2.0 で追加.
HTTPException のサブクラスです。ポート番号を指定したものの、その値が数字でなかったり空のオブジェクトであった場合に送出されます。
バージョン 2.3 で追加.
HTTPException のサブクラスです。
HTTPException のサブクラスです。
HTTPException のサブクラスです。
HTTPException のサブクラスです。
HTTPException のサブクラスです。
HTTPException のサブクラスです。
ImproperConnectionState のサブクラスです。
ImproperConnectionState のサブクラスです。
ImproperConnectionState のサブクラスです。
HTTPException のサブクラスです。サーバが理解できない HTTP 状態コードで応答した場合に送出されます。
このモジュールで定義されている定数は以下の通りです:
HTTP プロトコルの標準のポート (通常は 80) です。
HTTPS プロトコルの標準のポート (通常は 443) です。
また、整数の状態コードについて以下の定数が定義されています:
Constant | Value | Definition |
---|---|---|
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 |
このディクショナリは、HTTP 1.1ステータスコードをW3Cの名前にマップしたものです。
たとえば httplib.responses[httplib.NOT_FOUND] は 'Not Found' となります。
バージョン 2.5 で追加.
HTTPConnection インスタンスには以下のメソッドがあります:
このメソッドは、 HTTP 要求メソッド method およびセレクタ url を使って、要求をサーバに送ります。 body 引数を指定する場合、ヘッダが終了した後に送信する文字列データでなければなりません。 もしくは、開いているファイルオブジェクトを body に渡すこともできます。その場合、そのファイルの内容が送信されます。 このファイルオブジェクトは、 fileno() と read() メソッドをサポートしている必要があります。 ヘッダの Content-Length は自動的に正しい値に設定されます。 headers 引数は要求と同時に送信される拡張 HTTP ヘッダの内容からなるマップ型でなくてはなりません。
バージョン 2.6 で変更: body にファイルオブジェクトを渡せるようになりました
サーバに対して HTTP 要求を送り出した後に呼び出されなければりません。要求に対する応答を取得します。 HTTPResponse インスタンスを返します。
ノート
すべての応答を読み込んでからでなければ新しい要求をサーバに送ることはできないことに注意しましょう。
デバッグレベル (印字されるデバッグ出力の量) を設定します。標準のデバッグレベルは 0 で、デバッグ出力を全く印字しません。
オブジェクトを生成するときに指定したサーバに接続します。
サーバへの接続を閉じます。
上で説明した request() メソッドを使うかわりに、以下の4つの関数を使用して要求をステップバイステップで送信することもできます。
サーバへの接続が確立したら、最初にこのメソッドを呼び出さなくてはなりません。このメソッドは request 文字列、 selector 文字列、そして HTTP バージョン (HTTP/1.1) からなる一行を送信します。 Host: や Accept-Encoding: ヘッダの自動送信を無効にしたい場合 (例えば別のコンテンツエンコーディングを受け入れたい場合) には、 skip_host や skip_accept_encoding を偽でない値に設定してください。
RFC 822 形式のヘッダをサーバに送ります。この処理では、 header 、コロンとスペース、そして最初の引数からなる 1 行をサーバに送ります。 追加の引数を指定した場合、継続して各行にタブ一つと引数の入った引数行が送信されます。
サーバに空行を送り、ヘッダ部が終了したことを通知します。
サーバにデータを送ります。このメソッドは endheaders() が呼び出された直後で、かつ getreply() が呼び出される 前に使わなければなりません。
HTTPResponse インスタンスは以下のメソッドと属性を持ちます:
応答の本体全体か、 amt バイトまで読み出して返します。
ヘッダ name の内容を取得して返すか、該当するヘッダがない場合には default を返します。
(header, value) のタプルからなるリストを返します。
バージョン 2.4 で追加.
応答ヘッダを含む mimetools.Message インスタンスです。
サーバが使用した HTTP プロトコルバージョンです。10 は HTTP/1.0 を、 11 は HTTP/1.1 を表します。
サーバから返される状態コードです。
サーバから返される応答の理由文です。
以下は GET リクエストの送信方法を示した例です:
>>> import httplib
>>> conn = httplib.HTTPConnection("www.python.org")
>>> conn.request("GET", "/index.html")
>>> r1 = conn.getresponse()
>>> print r1.status, r1.reason
200 OK
>>> data1 = r1.read()
>>> conn.request("GET", "/parrot.spam")
>>> r2 = conn.getresponse()
>>> print r2.status, r2.reason
404 Not Found
>>> data2 = r2.read()
>>> conn.close()
以下は POST リクエストの送信方法を示した例です:
>>> import httplib, urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
... "Accept": "text/plain"}
>>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80")
>>> conn.request("POST", "/cgi-bin/query", params, headers)
>>> response = conn.getresponse()
>>> print response.status, response.reason
200 OK
>>> data = response.read()
>>> conn.close()