# 6 `urllib2` -- URL を開くための拡張可能なライブラリ

`urllib2` モジュールは基本的な認証、暗号化認証、リダイレクション、 クッキー、その他の介在する複雑なアクセス環境において (大抵は HTTP で) URL を開くための関数とクラスを定義します。

`urllib2` モジュールでは以下の関数を定義しています:

`urlopen`( | url[, data])

  URL url を開きます。url は文字列でも `Request` オブジェクトでもかまいません 。

  data はサーバに送信する追加のデータを示す文字列か、 そのようなデータが無ければNoneを指定します。 現時点でHTTP リクエストは data をサポートする唯一のリクエスト形式 です; data パラメタが指定が指定された場合、HTTP リクエストは GET でなく POST に なります。 data は標準的な application/x-www-form-urlencoded 形式の バッファでなくてはなりません。 `urllib.urlencode()` 関数は マップ型か2タプルのシーケンスを取り、この形式の文字列を返します。

  この関数は以下の 2 つのメソッドを持つファイル類似のオブジェクトを返します:

  - `geturl()` -- 取得されたリソースの URL を返します。
  - `info()` -- 取得されたページのメタ情報を辞書形式の オブジェクトで返します。

  エラーが発生した場合 `URLError` を送出します。

  どのハンドラもリクエストを処理しなかった場合には `None` を 返すことがあるので注意してください (デフォルトでインストールされる グローバルハンドラの `OpenerDirector` は、`UnknownHandler` を使って上記の問題が起きないようにしています)。

`install_opener`( | opener)

  標準で URL を開くオブジェクトとして `OpenerDirector` のインスタンス をインストールします。このコードは引数が本当に `OpenerDirector` のインスタンスであるかどうかはチェックしないので、適切なインタフェース を持ったクラスは何でも動作します。

`build_opener`( | [handler, ...])

  与えられた順番に URL ハンドラを連鎖させる `OpenerDirector` のインスタンスを返します。handler は `BaseHandler` または `BaseHandler` のサブクラスのインスタンスのどちらか です (どちらの場合も、コンストラクトは引数無しで呼び出せるように なっていなければなりません) 。以下のクラス:

  `ProxyHandler`, `UnknownHandler`, `HTTPHandler`, `HTTPDefaultErrorHandler`, `HTTPRedirectHandler`, `FTPHandler`, `FileHandler`, `HTTPErrorProcessor`

  については、そのクラスの インスタンスか、そのサブクラスのインスタンスが handler に含まれていない限り、handler よりも先に連鎖します。

  Python が SSL をサポートするように設定してインストールされている 場合 (`socket.ssl()` が存在する場合) 、 `HTTPSHandler` も追加されます。

  Python 2.3 からは、`BaseHandler` サブクラスでも `handler_order` メンバ変数を変更して、ハンドラリスト 内での場所を変更できるようになりました。

状況に応じて、以下の例外が送出されます:

exception `URLError`
  ハンドラが何らかの問題に遭遇した場合、この例外 (またはこの例外から 導出された例外)を送出します。この例外は `IOError` のサブクラスです。

exception `HTTPError`
  `URLError` のサブクラスです。このオブジェクトは例外でない ファイル類似のオブジェクトとして返り値に使うことができます (`urlopen()` が返すのと同じものです)。この機能は、例えば サーバからの認証リクエストのように、変わった HTTP エラーを処理する のに役立ちます。

exception `GopherError`

  `URLError` のサブクラスです。この例外は Gopher ハンドラに よって送出されます。

以下のクラスが提供されています:

クラス `Request`( | url[, data][, headers] [, origin_req_host][, unverifiable])

  このクラスは URL リクエストを抽象化したものです。

  url は有効な URL を指す文字列でなくてはなりません。

  data はサーバに送信する追加のデータを示す文字列か、 そのようなデータが無ければNoneを指定します。 現時点でHTTP リクエストは data をサポートする唯一のリクエスト形式 です; data パラメタが指定が指定された場合、HTTP リクエストは GET でなく POST に なります。 data は標準的な application/x-www-form-urlencoded 形式の バッファでなくてはなりません。 `urllib.urlencode()` 関数は マップ型か2タプルのシーケンスを取り、この形式の文字列を返します。

  headers は辞書でなくてはなりません。 この辞書は `add_header()` を辞書のキーおよび値を引数として呼び出した時と 同じように扱われます。

  最後の二つの引数は、サードパーティの HTTP クッキーを正しく扱いたい 場合にのみ関係してきます:

  origin_req_host は、RFC 2965 で定義されている 元のトランザクションにおけるリクエストホスト (request-host of the origin transaction) です。デフォルトの値は `cookielib.request_host(self)` です。 この値は、ユーザによって開始された元々のリクエストにおける ホスト名や IP アドレスです。例えば、もしリクエストがある HTML ドキュメント内の画像を指していれば、この値は 画像を含んでいるページへのリクエストにおけるリクエストホストに なるはずです。

  unverifiable は、RFC 2965 の定義において、該当するリクエストが 証明不能 (unverifiable) であるかどうかを示します。デフォルトの値は False です。証明不能なリクエストとは、ユーザが受け入れの可否を選択 できないような URL を持つリクエストのことです。例えば、リクエストが HTML ドキュメント中の画像であり、ユーザがこの画像を自動的に取得するか どうかを選択できない場合には、証明不能フラグは True になります。

クラス `OpenerDirector`( | )

  `OpenerDirector` クラスは、`BaseHandler` の連鎖的に 呼び出して URL を開きます。このクラスはハンドラをどのように連鎖 させるか、またどのようにエラーをリカバリするかを管理します。

クラス `BaseHandler`( | )

  このクラスはハンドラ連鎖に登録される全てのハンドラがベースとしている クラスです - このクラスでは登録のための単純なメカニズムだけを扱います。

クラス `HTTPDefaultErrorHandler`( | )

  HTTP エラー応答のための標準のハンドラを定義します; 全てのレスポンスに 対して、例外 `HTTPError` を送出します。

クラス `HTTPRedirectHandler`( | )

  リダイレクションを扱うクラスです。

クラス `HTTPCookieProcessor`( | [cookiejar])

  HTTP Cookie を扱うためのクラスです。

クラス `ProxyHandler`( | [proxies])

  このクラスはプロキシを通過してリクエストを送らせます。 引数 proxies を与える場合、プロトコル名からプロキシの URL へ対応付ける辞書でなくてはなりません。 標準では、プロキシのリストを環境変数 <protocol>_proxy から読み出します。

クラス `HTTPPasswordMgr`( | )

  `(realm, uri) -> (user, password)` の対応付けデータベースを保持します。

クラス `HTTPPasswordMgrWithDefaultRealm`( | )

  `(realm, uri) -> (user, password)` の対応付けデータベースを保持します。 レルム `None` はその他諸々のレルムを表し、他のレルムが 該当しない場合に検索されます。

クラス `AbstractBasicAuthHandler`( | [password_mgr])

  このクラスはHTTP 認証を補助するための混ぜ込みクラス (mixin class) です。 遠隔ホストとプロキシの両方に対応しています。 password_mgr を与える場合、`HTTPPasswordMgr` と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 18.6.7 を参照してください。

クラス `HTTPBasicAuthHandler`( | [password_mgr])

  遠隔ホストとの間での認証を扱います。 password_mgr を与える場合、`HTTPPasswordMgr` と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 18.6.7 を参照してください。

クラス `ProxyBasicAuthHandler`( | [password_mgr])

  プロキシとの間での認証を扱います。 password_mgr を与える場合、`HTTPPasswordMgr` と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 18.6.7 を参照してください。

クラス `AbstractDigestAuthHandler`( | [password_mgr])

  このクラスはHTTP 認証を補助するための混ぜ込みクラス (mixin class) です。 遠隔ホストとプロキシの両方に対応しています。 password_mgr を与える場合、`HTTPPasswordMgr` と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 18.6.7 を参照してください。

クラス `HTTPDigestAuthHandler`( | [password_mgr])

  遠隔ホストとの間での認証を扱います。 password_mgr を与える場合、`HTTPPasswordMgr` と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 18.6.7 を参照してください。

クラス `ProxyDigestAuthHandler`( | [password_mgr])

  プロキシとの間での認証を扱います。 password_mgr を与える場合、`HTTPPasswordMgr` と互換性が なければなりません; 互換性のためにサポートしなければならないインタフェースについての 情報はセクション 18.6.7 を参照してください。

クラス `HTTPHandler`( | )

  HTTP の URL を開きます。

クラス `HTTPSHandler`( | )

  HTTPS の URL を開きます。

クラス `FileHandler`( | )

  ローカルファイルを開きます。

クラス `FTPHandler`( | )

  FTP の URL を開きます。

クラス `CacheFTPHandler`( | )

  FTP の URL を開きます。遅延を最小限にするために、開かれている FTP 接続に対するキャッシュを保持します。

クラス `GopherHandler`( | )

  gopher の URL を開きます。

クラス `UnknownHandler`( | )

  その他諸々のためのクラスで、未知のプロトコルの URL を開きます。