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

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

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

`urlopen`( | url[, data])

  URL url を開きます。url は文字列でも `Request` オブジェクトでもかまいません (現時点では、コードの中で引数が本当に `Request` クラスのインスタンスまたは `Request` のサブクラス のインスタンスであるかどうかがチェックされます)。

  data は文字列で、サーバに送信する追加のデータを指定します。 HTTP リクエストは data をサポートする唯一のリクエスト形式 ですが、ここでは data は例えば `urllib.urlencode()` が返すような application/x-www-form-urlencoded 形式で エンコードされたバッファでなくてはなりません。

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

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

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

`install_opener`( | opener)

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

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

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

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

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

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

  Python 2.3 からは、`BaseHandler` サブクラスでも `handler_order` メンバ変数を変更して、ハンドラリスト 内での場所を変更できるようになりました。 現在全てのハンドラの `handler_oder` は `500` ですが、 例外として `ProxyHandler` では `100` になっています。

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

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

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

exception `GopherError`

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

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

class `Request`( | url[, data[, headers]])

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

  url は有効な URL を指す文字列でなくてはなりません。 data の詳細については `add_data()` の記述を見てください。 headers は辞書でなくてはなりません。 この辞書は `add_header()` を辞書のキーおよび値を引数として呼び出した時と 同じように扱われます。

class `OpenerDirector`( | )

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

class `BaseHandler`( | )

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

class `HTTPDefaultErrorHandler`( | )

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

class `HTTPRedirectHandler`( | )

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

class `ProxyHandler`( | [proxies])

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

class `HTTPPasswordMgr`( | )

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

class `HTTPPasswordMgrWithDefaultRealm`( | )

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

class `AbstractBasicAuthHandler`( | [password_mgr])

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

class `HTTPBasicAuthHandler`( | [password_mgr])

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

class `ProxyBasicAuthHandler`( | [password_mgr])

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

class `AbstractDigestAuthHandler`( | [password_mgr])

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

class `HTTPDigestAuthHandler`( | [password_mgr])

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

class `ProxyDigestAuthHandler`( | [password_mgr])

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

class `HTTPHandler`( | )

  HTTP の URL を開きます。

class `HTTPSHandler`( | )

  HTTPS の URL を開きます。

class `FileHandler`( | )

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

class `FTPHandler`( | )

  FTP の URL を開きます。

class `CacheFTPHandler`( | )

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

class `GopherHandler`( | )

  gopher の URL を開きます。

class `UnknownHandler`( | )

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