18.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 つのメソッドを持つファイル類似のオブジェクトを返します:

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

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

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

build_opener( [handler, ...])
与えられた順番に URL ハンドラを連鎖させる OpenerDirector のインスタンスを返します。handlerBaseHandler または 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 を開きます。



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