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 を開きます。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。

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

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