\section{\module{urllib2} ---
         URL を開くための拡張可能なライブラリ}

\declaremodule{standard}{urllib2}
\moduleauthor{Jeremy Hylton}{jhylton@users.sourceforge.net}
\sectionauthor{Moshe Zadka}{moshez@users.sourceforge.net}

\modulesynopsis{様々なプロトコルで URL を開くための拡張可能なライブラリ}

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

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

\begin{funcdesc}{urlopen}{url\optional{, data}}
URL \var{url} を開きます。\var{url} は文字列でも \class{Request}
オブジェクトでもかまいません 。

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

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

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

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

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

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

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

\class{ProxyHandler}, \class{UnknownHandler}, \class{HTTPHandler},
\class{HTTPDefaultErrorHandler}, \class{HTTPRedirectHandler},
\class{FTPHandler}, \class{FileHandler}, \class{HTTPErrorProcessor}

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

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

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


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

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

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

\begin{excdesc}{GopherError}

\exception{URLError} のサブクラスです。この例外は Gopher ハンドラに
よって送出されます。
\end{excdesc}


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

\begin{classdesc}{Request}{url\optional{, data}\optional{, headers}
    \optional{, origin_req_host}\optional{, unverifiable}}
このクラスは URL リクエストを抽象化したものです。

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

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

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

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

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

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

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

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

\begin{classdesc}{HTTPDefaultErrorHandler}{}
HTTP エラー応答のための標準のハンドラを定義します; 全てのレスポンスに
対して、例外 \exception{HTTPError} を送出します。
\end{classdesc}

\begin{classdesc}{HTTPRedirectHandler}{}
リダイレクションを扱うクラスです。
\end{classdesc}

\begin{classdesc}{HTTPCookieProcessor}{\optional{cookiejar}}
HTTP Cookie を扱うためのクラスです。
\end{classdesc}

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

\begin{classdesc}{HTTPPasswordMgr}{}
\code{(\var{realm}, \var{uri}) -> (\var{user}, \var{password})}
の対応付けデータベースを保持します。
\end{classdesc}

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

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

\begin{classdesc}{HTTPBasicAuthHandler}{\optional{password_mgr}}
遠隔ホストとの間での認証を扱います。
\var{password_mgr} を与える場合、\class{HTTPPasswordMgr} と互換性が
なければなりません; 
互換性のためにサポートしなければならないインタフェースについての
情報はセクション~\ref{http-password-mgr} を参照してください。
\end{classdesc}

\begin{classdesc}{ProxyBasicAuthHandler}{\optional{password_mgr}}
プロキシとの間での認証を扱います。
\var{password_mgr} を与える場合、\class{HTTPPasswordMgr} と互換性が
なければなりません; 
互換性のためにサポートしなければならないインタフェースについての
情報はセクション~\ref{http-password-mgr} を参照してください。
\end{classdesc}

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

\begin{classdesc}{HTTPDigestAuthHandler}{\optional{password_mgr}}
遠隔ホストとの間での認証を扱います。
\var{password_mgr} を与える場合、\class{HTTPPasswordMgr} と互換性が
なければなりません; 
互換性のためにサポートしなければならないインタフェースについての
情報はセクション~\ref{http-password-mgr} を参照してください。
\end{classdesc}

\begin{classdesc}{ProxyDigestAuthHandler}{\optional{password_mgr}}
プロキシとの間での認証を扱います。
\var{password_mgr} を与える場合、\class{HTTPPasswordMgr} と互換性が
なければなりません; 
互換性のためにサポートしなければならないインタフェースについての
情報はセクション~\ref{http-password-mgr} を参照してください。
\end{classdesc}

\begin{classdesc}{HTTPHandler}{}
HTTP の URL を開きます。
\end{classdesc}

\begin{classdesc}{HTTPSHandler}{}
HTTPS の URL を開きます。
\end{classdesc}

\begin{classdesc}{FileHandler}{}
ローカルファイルを開きます。
\end{classdesc}

\begin{classdesc}{FTPHandler}{}
FTP の URL を開きます。
\end{classdesc}

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

\begin{classdesc}{GopherHandler}{}
gopher の URL を開きます。
\end{classdesc}

\begin{classdesc}{UnknownHandler}{}
その他諸々のためのクラスで、未知のプロトコルの URL を開きます。
\end{classdesc}


\subsection{Request オブジェクト \label{request-objects}}

以下のメソッドは \class{Request} の全ての公開インタフェースを記述します。
従ってサブクラスではこれら全てのメソッドをオーバライドしなければなりません。

\begin{methoddesc}[Request]{add_data}{data}
\class{Request} のデータを \var{data} に設定します。この値は HTTP 
ハンドラ以外のハンドラでは無視されます。HTTP ハンドラでは、データは
バイト文字列でなくてはなりません。このメソッドを使うとリクエストの形式が
\code{GET} から \code{POST} に変更されます。
\end{methoddesc}

\begin{methoddesc}[Request]{get_method}{}
HTTP リクエストメソッドを示す文字列を返します。このメソッドは
HTTP リクエストだけに対して意味があり、現状では常に \code{'GET'} か 
\code{'POST'} のいずれかの値を返します。
\end{methoddesc}

\begin{methoddesc}[Request]{has_data}{}
インスタンスが \code{None} でないデータを持つかどうかを返します。
\end{methoddesc}

\begin{methoddesc}[Request]{get_data}{}
インスタンスのデータを返します。
\end{methoddesc}

\begin{methoddesc}[Request]{add_header}{key, val}
リクエストに新たなヘッダを追加します。ヘッダは HTTP ハンドラ以外の
ハンドラでは無視されます。HTTP ハンドラでは、引数はサーバに送信される
ヘッダのリストに追加されます。同じ名前を持つヘッダを 2 つ以上持つ
ことはできず、\var{key} の衝突が生じた場合、後で追加したヘッダが前に
追加したヘッダを上書きします。現時点では、この機能は HTTP の機能を
損ねることはありません。というのは、複数回呼び出したときに意味を
持つようなヘッダには、どれもただ一つのヘッダを使って同じ機能を果たす
ための (ヘッダ特有の) 方法があるからです。
\end{methoddesc}

\begin{methoddesc}[Request]{add_unredirected_header}{key, header}
リダイレクトされたリクエストには追加されないヘッダを追加します。
\versionadded{2.4}
\end{methoddesc}

\begin{methoddesc}[Request]{has_header}{header}
インスタンスが名前つきヘッダであるかどうかを (通常のヘッダと
非リダイレクトヘッダの両方を調べて) 返します。
\versionadded{2.4}
\end{methoddesc}


\begin{methoddesc}[Request]{get_full_url}{}
コンストラクタで与えられた URL を返します。
\end{methoddesc}

\begin{methoddesc}[Request]{get_type}{}
URL のタイプ --- いわゆるスキーム (scheme) --- を返します。
\end{methoddesc}

\begin{methoddesc}[Request]{get_host}{}
接続を行う先のホスト名を返します。
\end{methoddesc}

\begin{methoddesc}[Request]{get_selector}{}
セレクタ --- サーバに送られる URL の一部分 --- を返します。
\end{methoddesc}

\begin{methoddesc}[Request]{set_proxy}{host, type}
リクエストがプロキシサーバを経由するように準備します。
\var{host} および \var{type} はインスタンスのもとの設定と置き換えられ
ます。インスタンスのセレクタはコンストラクタに与えたもともとの URL に
なります。
\end{methoddesc}

\begin{methoddesc}[Request]{get_origin_req_host}{}
\rfc{2965} の定義よる、始原トランザクションのリクエストホスト
を返します。\class{Request} コンストラクタのドキュメントを
参照してください。
\end{methoddesc}

\begin{methoddesc}[Request]{is_unverifiable}{}
リクエストが \rfc{2965} の定義における証明不能リクエストであるか
どうかを返します。\class{Request} コンストラクタのドキュメントを
参照してください。
\end{methoddesc}
 
\subsection{OpenerDirector オブジェクト \label{opener-director-objects}}

\class{OpenerDirector} インスタンスは以下のメソッドを持っています:

\begin{methoddesc}[OpenerDirector]{add_handler}{handler}
\var{handler} は \class{BaseHandler} のインスタンスでなければ
なりません。以下のメソッドを使った検索が行われ、URL を取り扱うことが
可能なハンドラの連鎖が追加されます (HTTP エラーは特別扱いされている
ので注意してください)。

\begin{itemize}
  \item \method{\var{protocol}_open()} ---
    ハンドラが \var{protocol} の URL を開く方法を知っているかどうかを
調べます。
  \item \method{http_error_\var{type}()} ---
    ハンドラが HTTP エラーコード \var{type} の処理方法を知っていることを
    示すシグナルです。
  \item \method{\var{protocol}_error()} ---
    ハンドラが (\code{http} でない) \var{protocol} のエラー
    を処理する方法を知っていることを示すシグナルです。
  \item \method{\var{protocol}_request()} ---
    ハンドラが \var{protocol} リクエストのプリプロセス方法
    を知っていることを示すシグナルです。
  \item \method{\var{protocol}_response()} ---
    ハンドラが \var{protocol} リクエストのポストプロセス方法
    を知っていることを示すシグナルです。
\end{itemize}
\end{methoddesc}

\begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}}
与えられた \var{url} (リクエストオブジェクトでも文字列でも
かまいません) を開きます。オプションとして \var{data} を与えることが
できます。
引数、返り値、および送出される例外は \function{urlopen()} と同じ
です (\function{urlopen()} の場合、標準でインストールされている
グローバルな \class{OpenerDirector} の \method{open()} メソッドを
呼び出します) 。
\end{methoddesc}

\begin{methoddesc}[OpenerDirector]{error}{proto\optional{,
                                          arg\optional{, \moreargs}}}
与えられたプロトコルにおけるエラーを処理します。このメソッドは
与えられたプロトコルにおける登録済みのエラーハンドラを
(プロトコル固有の) 引数で呼び出します。 HTTP プロトコルは特殊な
ケースで、特定のエラーハンドラを選び出すのに HTTP レスポンスコード
を使います; ハンドラクラスの \method{http_error_*()} メソッドを
参照してください。

返り値および送出される例外は \function{urlopen()} と同じものです。
\end{methoddesc}

OpenerDirector オブジェクトは、以下の 3 つのステージに分けて
URL を開きます:

各ステージで OpenerDirector オブジェクトのメソッドがどのような
順で呼び出されるかは、ハンドラインスタンスの並び方で決まります。

\begin{enumerate}
  \item \method{\var{protocol}_request()} 形式のメソッドを持つ
    全てのハンドラに対してそのメソッドを呼び出し、リクエストの
    プリプロセスを行います。

  \item \method{\var{protocol}_open()} 形式のメソッドを持つ
    ハンドラを呼び出し、リクエストを処理します。
    このステージは、ハンドラが\constant{None} でない値 (すなわち
    レスポンス) を返すか、例外 (通常は \exception{URLError}) を送出した時点で
    終了します。例外は伝播 (propagate) できます。

    実際には、上のアルゴリズムではまず \method{default_open} という名前の
    メソッドを呼び出します。このメソッドが全て \constant{None} を返す場合、
    同じアルゴリズムを繰り返して、今度は \method{\var{protocol}_open()}
    形式のメソッドを試します。メソッドが全て \constant{None} を返すと、
    さらに同じアルゴリズムを繰り返して \method{unknown_open()} を呼び出します。

    これらのメソッドの実装には、親となる \class{OpenerDirector} 
    インスタンスの \method{.open()} や\method{.error()} といったメソッド
    呼び出しが入る場合があるので注意してください。

  \item \method{\var{protocol}_response()} 形式のメソッドを持つ
    全てのハンドラに対してそのメソッドを呼び出し、リクエストの
    ポストプロセスを行います。

\end{enumerate}

\subsection{BaseHandler オブジェクト \label{base-handler-objects}}

\class{BaseHandler} オブジェクトは直接的に役に立つ 2 つのメソッド
と、その他として導出クラスで使われることを想定したメソッドを
提供します。以下は直接的に使うためのメソッドです:

\begin{methoddesc}[BaseHandler]{add_parent}{director}
親オブジェクトとして、\code{director} を追加します。
\end{methoddesc}

\begin{methoddesc}[BaseHandler]{close}{}
全ての親オブジェクトを削除します。
\end{methoddesc}

以下のメンバおよびメソッドは \class{BaseHandler} から導出された
クラスでのみ使われます:
\note{慣習的に、\method{\var{protocol}_request()} や
\method{\var{protocol}_response()} といったメソッドを定義している
サブクラスは\class{*Processor} と名づけ、その他は\class{*Handler}
と名づけることになっています}

\begin{memberdesc}[BaseHandler]{parent}
有効な \class{OpenerDirector} です。この値は違うプロトコルを
使って URL を開く場合やエラーを処理する際に使われます。
\end{memberdesc}

\begin{methoddesc}[BaseHandler]{default_open}{req}
このメソッドは \class{BaseHandler} では定義されて \emph{いません}。
しかし、全ての URL をキャッチさせたいなら、サブクラスで定義する
必要があります。

このメソッドが定義されていた場合、\class{OpenerDirector} から
呼び出されます。このメソッドは \class{OpenerDirector} の メソッド
\method{open()} が返す値について記述されているようなファイル類似の
オブジェクトか、\code{None} を返さなくてはなりません。
このメソッドが送出する例外は、真に例外的なことが起きない限り、
\exception{URLError} を送出しなければなりません (例えば、
\exception{MemoryError} を \exception{URLError} をマップしては
いけません)。

このメソッドはプロトコル固有のオープンメソッドが呼び出される前に
呼び出されます。
\end{methoddesc}

\begin{methoddescni}[BaseHandler]{\var{protocol}_open}{req}
このメソッドは \class{BaseHandler} では定義されて \emph{いません}。
しかしプロトコルの指定された URL をキャッチしたいなら、サブクラスで
定義する必要があります。

このメソッドが定義されていた場合、\class{OpenerDirector} から
呼び出されます。戻り値は \method{default_open} と同じでなければ
なりません。
\end{methoddescni}

\begin{methoddesc}[BaseHandler]{unknown_open}{req}
このメソッドは \class{BaseHandler} では定義されて \emph{いません}。
しかし URL を開くための特定のハンドラが登録されていないような URL を
キャッチしたいなら、サブクラスで定義する必要があります。

このメソッドが定義されていた場合、\class{OpenerDirector} から
呼び出されます。戻り値は \method{default_open} と同じでなければ
なりません。
\end{methoddesc}

\begin{methoddesc}[BaseHandler]{http_error_default}{req, fp, code, msg, hdrs}
このメソッドは \class{BaseHandler} では定義されて \emph{いません}。
しかしその他の処理されなかった HTTP エラーを処理する機能をもたせたいなら、
サブクラスで定義する必要があります。このメソッドはエラーに遭遇した
\class{OpenerDirector} から自動的に呼び出されます。その他の状況では
普通呼び出すべきではありません。

\var{req} は \class{Request} オブジェクトで、 \var{fp} は
HTTP エラー本体を読み出せるようなファイル類似のオブジェクトに
なります。\var{code} は 3 桁の 10 進数からなるエラーコードで、
\var{msg} ユーザ向けのエラーコード解説です。\var{hdrs} は
エラー応答のヘッダをマップしたオブジェクトです。

返される値および送出される例外は \function{urlopen()} と同じ
ものでなければなりません。
\end{methoddesc}

\begin{methoddesc}[BaseHandler]{http_error_\var{nnn}}{req, fp, code, msg, hdrs}
\var{nnn} は 3 桁の 10 進数からなる HTTP エラーコードでなくては
なりません。このメソッドも \class{BaseHandler} では定義されていませんが、
サブクラスのインスタンスで定義されていた場合、エラーコード \var{nnn}
の HTTP エラーが発生した際に呼び出されます。

特定の HTTP エラーに対する処理を行うためには、このメソッドをサブクラスで
オーバライドする必要があります。

引数、返される値、および送出される例外は \method{http_error_default()}
と同じものでなければなりません。
\end{methoddesc}

\begin{methoddescni}[BaseHandler]{\var{protocol}_request}{req}
このメソッドは\class{BaseHandler} では\emph{定義されていません} が、
サブクラスで特定のプロトコルリクエストのプリプロセスを行いたい
場合には定義せねばなりません。

このメソッドが定義されていると、親となる \class{OpenerDirector} から
呼び出されます。その際、\var{req} は\class{Request} オブジェクトに
なります。戻り値は\class{Request} オブジェクトでなければなりません。
\end{methoddescni}

\begin{methoddescni}[BaseHandler]{\var{protocol}_response}{req, response}
このメソッドは\class{BaseHandler} では\emph{定義されていません} が、
サブクラスで特定のプロトコルリクエストのポストプロセスを行いたい
場合には定義せねばなりません。

このメソッドが定義されていると、親となる \class{OpenerDirector} から
呼び出されます。その際、\var{req} は\class{Request} オブジェクトに
なります。
\var{response} は \function{urlopen()} の戻り値と同じインタフェースを
実装したオブジェクトになります。
戻り値もまた、\function{urlopen()} の戻り値と同じインタフェースを
実装したオブジェクトでなければなりません。
\end{methoddescni}


\subsection{HTTPRedirectHandler オブジェクト \label{http-redirect-handler}}

\note{HTTP リダイレクトによっては、このモジュールのクライアントコード
側での処理を必要とします。その場合、 \exception{HTTPError} が送出されます。
様々なリダイレクトコードの厳密な意味に関する詳細は \rfc{2616} を
参照してください。}

\begin{methoddesc}[HTTPRedirectHandler]{redirect_request}{req,
                                                  fp, code, msg, hdrs}
リダイレクトの通知に応じて、 \class{Request} または \code{None}
を返します。このメソッドは \code{http_error_30*()} メソッドに
おいて、リダイレクトの通知をサーバから受信した際に、
デフォルトの実装として呼び出されます。
リダイレクトを起こす場合、新たな \class{Request} を生成して、
\code{http_error_30*()} がリダイレクトを実行できるようにします。
そうでない場合、他のどのハンドラにもこの URL を
処理させたくなければ \exception{HTTPError} を送出し、
リダイレクト処理を行うことはできないが他のハンドラ
なら可能かもしれない場合には \code{None} を返します。

\begin{notice}
このメソッドのデフォルトの実装は、\rfc{2616} に厳密に従ったものでは
ありません。
\rfc{2616} では、\code{POST} リクエストに対する 301 および 302 応答が、
ユーザの承認なく自動的にリダイレクトされてはならないと述べています。
現実には、ブラウザは POST を \code{GET} に変更することで、これらの
応答に対して自動的にリダイレクトを行えるようにしています。
デフォルトの実装でも、この挙動を再現しています。
\end{notice}
\end{methoddesc}

\begin{methoddesc}[HTTPRedirectHandler]{http_error_301}{req,
                                                  fp, code, msg, hdrs}

\code{Location:} URL にリダイレクトします。このメソッドは HTTP 
における `moved permanently' レスポンスを取得した際に
親オブジェクトとなる \class{OpenerDirector} によって呼び出されます。
\end{methoddesc}

\begin{methoddesc}[HTTPRedirectHandler]{http_error_302}{req,
                                                  fp, code, msg, hdrs}
\method{http_error_301()} と同じですが、`found' レスポンスに対して
呼び出されます。
\end{methoddesc}

\begin{methoddesc}[HTTPRedirectHandler]{http_error_303}{req,
                                                  fp, code, msg, hdrs}
\method{http_error_301()} と同じですが、`see other' レスポンスに対して
呼び出されます。
\end{methoddesc}

\begin{methoddesc}[HTTPRedirectHandler]{http_error_307}{req,
                                                  fp, code, msg, hdrs}
\method{http_error_301()} と同じですが、`temporary redirect' 
レスポンスに対して呼び出されます。
\end{methoddesc}

\subsection{HTTPCookieProcessor オブジェクト \label{http-cookie-processor}}

\versionadded{2.4}

\class{HTTPCookieProcessor} インスタンスは属性をひとつだけ持ちます:

\begin{memberdesc}[HTTPCookieProcessor]{cookiejar}
クッキーの入っている\class{cookielib.CookieJar} オブジェクトです。
\end{memberdesc}

\subsection{ProxyHandler オブジェクト \label{proxy-handler}}

\begin{methoddescni}[ProxyHandler]{\var{protocol}_open}{request}
\class{ProxyHandler} は、
コンストラクタで与えた辞書 \var{proxies} にプロキシが設定されている
ような \var{protocol} 全てについて、メソッド 
\method{\var{protocol}_open()} を持つことになります。
このメソッドは \code{request.set_proxy()} を呼び出して、
リクエストがプロキシを通過できるように修正します。その後
連鎖するハンドラの中から次のハンドラを呼び出して実際に
プロトコルを実行します。
\end{methoddescni}


\subsection{HTTPPasswordMgr オブジェクト \label{http-password-mgr}}

以下のメソッドは \class{HTTPPasswordMgr} および
\class{HTTPPasswordMgrWithDefaultRealm} オブジェクトで利用できます。

\begin{methoddesc}[HTTPPasswordMgr]{add_password}{realm, uri, user, passwd}
\var{uri} は単一の URI でも複数の URI からなるシーケンスでもかまいません。
\var{realm} 、\var{user} および \var{passwd} は文字列でなくてはなりません。
このメソッドによって、\var{realm} と与えられた URI の上位 URI に対して
\code{(\var{user}, \var{passwd})} が認証トークンとして使われるようになります。
\end{methoddesc}  

\begin{methoddesc}[HTTPPasswordMgr]{find_user_password}{realm, authuri}
与えられたレルムおよび URI に対するユーザ名またはパスワードがあれば
それを取得します。該当するユーザ名／パスワードが存在しない場合、
このメソッドは \code{(None, None)} を返します。


\class{HTTPPasswordMgrWithDefaultRealm} オブジェクトでは、与えられた
\var{realm} に対して該当するユーザ名/パスワードが存在しない場合、
レルム \code{None} が検索されます。
\end{methoddesc}


\subsection{AbstractBasicAuthHandler オブジェクト
            \label{abstract-basic-auth-handler}}

\begin{methoddesc}[AbstractBasicAuthHandler]{http_error_auth_reqed}
                                            {authreq, host, req, headers}
ユーザ名／パスワードを取得し、再度サーバへのリクエストを試みることで、
サーバからの認証リクエストを処理します。 \var{authreq} はリクエストにおいて
レルムに関する情報が含まれているヘッダの名前、
\var{host} は認証を行う対象の URL とパスを指定します、
\var{req} は (失敗した) \class{Request} オブジェクト、そして \var{headers} は
エラーヘッダでなくてはなりません。

\var{host} は、オーソリティ (例 \code{"python.org"}) か、
オーソリティコンポーネント を含む URL (例 \code{"http://python.org"}) です。
どちらの場合も、オーソリティはユーザ情報コンポーネントを含んではいけません
 (なので、\code{"python.org"} や \code{"python.org:80"} は正しく、
\code{"joe:password@python.org"} は不正です) 。 
\end{methoddesc}


\subsection{HTTPBasicAuthHandler オブジェクト
            \label{http-basic-auth-handler}}

\begin{methoddesc}[HTTPBasicAuthHandler]{http_error_401}{req, fp, code, 
                                                        msg, hdrs}
認証情報がある場合、認証情報付きで再度リクエストを試みます。
\end{methoddesc}


\subsection{ProxyBasicAuthHandler オブジェクト
            \label{proxy-basic-auth-handler}}

\begin{methoddesc}[ProxyBasicAuthHandler]{http_error_407}{req, fp, code, 
                                                        msg, hdrs}
認証情報がある場合、認証情報付きで再度リクエストを試みます。
\end{methoddesc}


\subsection{AbstractDigestAuthHandler オブジェクト
            \label{abstract-digest-auth-handler}}

\begin{methoddesc}[AbstractDigestAuthHandler]{http_error_auth_reqed}
                                            {authreq, host, req, headers}
\var{authreq} はリクエストにおいてレルムに関する情報が含まれている
ヘッダの名前、\var{host} は認証を行う対象のホスト名、\var{req} は 
(失敗した) \class{Request} オブジェクト、そして \var{headers} は
エラーヘッダでなくてはなりません。
\end{methoddesc}


\subsection{HTTPDigestAuthHandler オブジェクト
            \label{http-digest-auth-handler}}

\begin{methoddesc}[HTTPDigestAuthHandler]{http_error_401}{req, fp, code, 
                                                        msg, hdrs}
認証情報がある場合、認証情報付きで再度リクエストを試みます。
\end{methoddesc}


\subsection{ProxyDigestAuthHandler オブジェクト
            \label{proxy-digest-auth-handler}}

\begin{methoddesc}[ProxyDigestAuthHandler]{http_error_407}{req, fp, code, 
                                                        msg, hdrs}
認証情報がある場合、認証情報付きで再度リクエストを試みます。
\end{methoddesc}


\subsection{HTTPHandler オブジェクト \label{http-handler-objects}}

\begin{methoddesc}[HTTPHandler]{http_open}{req}
HTTP リクエストを送ります。\code{\var{req}.has_data()} に応じて、
GET または POST のどちらでも送ることができます。
\end{methoddesc}


\subsection{HTTPSHandler オブジェクト \label{https-handler-objects}}

\begin{methoddesc}[HTTPSHandler]{https_open}{req}
HTTPS リクエストを送ります。\code{\var{req}.has_data()} に応じて、
GET または POST のどちらでも送ることができます。
\end{methoddesc}


\subsection{FileHandler オブジェクト \label{file-handler-objects}}

\begin{methoddesc}[FileHandler]{file_open}{req}
ホスト名がない場合、またはホスト名が \code{'localhost'} の場合に
ファイルをローカルでオープンします。そうでない場合、プロトコルを
\code{ftp} に切り替え、\member{parent} を使って再度オープンを
試みます。
\end{methoddesc}


\subsection{FTPHandler オブジェクト \label{ftp-handler-objects}}

\begin{methoddesc}[FTPHandler]{ftp_open}{req}
\var{req} で表されるファイルを FTP 越しにオープンします。
ログインは常に空のユーザネームおよびパスワードで行われます。
\end{methoddesc}


\subsection{CacheFTPHandler オブジェクト \label{cacheftp-handler-objects}}

\class{CacheFTPHandler} オブジェクトは \class{FTPHandler} オブジェクトに
以下のメソッドを追加したものです:

\begin{methoddesc}[CacheFTPHandler]{setTimeout}{t}
接続のタイムアウトを \var{t} 秒に設定します。
\end{methoddesc}

\begin{methoddesc}[CacheFTPHandler]{setMaxConns}{m}
キャッシュ付き接続の最大接続数を \var{m} に設定します。
\end{methoddesc}


\subsection{GopherHandler オブジェクト \label{gopher-handler}}

\begin{methoddesc}[GopherHandler]{gopher_open}{req}
\var{req} で表される gopher 上のリソースをオープンします。
\end{methoddesc}


\subsection{UnknownHandler オブジェクト \label{unknown-handler-objects}}

\begin{methoddesc}[UnknownHandler]{unknown_open}{}
例外 \exception{URLError} を送出します。
\end{methoddesc}


\subsection{HTTPErrorProcessor オブジェクト \label{http-error-processor-objects}}

\versionadded{2.4}

\begin{methoddesc}[HTTPErrorProcessor]{unknown_open}{}
HTTP エラーレスポンスを処理します。

エラーコード 200 の場合、レスポンスオブジェクトを即座に返します。

200 以外のエラーコードの場合、\method{OpenerDirector.error()}
を介して\method{\var{protocol}_error_\var{code}()} メソッドに
仕事を引き渡します。最終的にどのハンドラもエラーを処理しなかった
場合、\class{urllib2.HTTPDefaultErrorHandler} が
\exception{HTTPError} を送出します。
\end{methoddesc}

\subsection{例 \label{urllib2-examples}}

以下の例では、 python.org のメインページを取得して、その最初の
100 バイト分を表示します:

\begin{verbatim}
>>> import urllib2
>>> f = urllib2.urlopen('http://www.python.org/')
>>> print f.read(100)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<?xml-stylesheet href="./css/ht2html
\end{verbatim}

今度は CGI の標準入力にデータストリームを送信し、CGI が返すデータ
を読み出します。この例は Python が SSL をサポートしている場合にのみ
動作することに注意してください。

\begin{verbatim}
>>> import urllib2
>>> req = urllib2.Request(url='https://localhost/cgi-bin/test.cgi',
...                       data='This data is passed to stdin of the CGI')
>>> f = urllib2.urlopen(req)
>>> print f.read()
Got Data: "This data is passed to stdin of the CGI"
\end{verbatim}

上の例で使われているサンプルの CGI は以下のようになっています:

\begin{verbatim}
#!/usr/bin/env python
import sys
data = sys.stdin.read()
print 'Content-type: text-plain\n\nGot Data: "%s"' % data
\end{verbatim}


以下はベーシック HTTP 認証の例です:

\begin{verbatim}
import urllib2
# ベーシック HTTP 認証をサポートする OpenerDirector を作成する...
auth_handler = urllib2.HTTPBasicAuthHandler()
auth_handler.add_password('realm', 'host', 'username', 'password')
opener = urllib2.build_opener(auth_handler)
# ...urlopen から利用できるよう、グローバルにインストールする
urllib2.install_opener(opener)
urllib2.urlopen('http://www.example.com/login.html')
\end{verbatim}

\function{build_opener()} はデフォルトで沢山のハンドラを提供しており、
その中に\class{ProxyHandler} があります。デフォルトでは、
\class{ProxyHandler} は\code{<scheme>_proxy} という環境変数を使います。
ここで\code{<scheme>} は URL スキームです。例えば、 HTTP プロキシの
URL を得るには、環境変数\envvar{http_proxy} を読み出します。

この例では、デフォルトの \class{ProxyHandler} を置き換えて
プログラム的に作成したプロキシ URL を使うようにし、
\class{ProxyBasicAuthHandler} でプロキシ認証サポートを追加します。

\begin{verbatim}
proxy_handler = urllib2.ProxyHandler({'http': 'http://www.example.com:3128/'})
proxy_auth_handler = urllib2.HTTPBasicAuthHandler()
proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

opener = build_opener(proxy_handler, proxy_auth_handler)
# 今回は OpenerDirector をインストールするのではなく直接使います:
opener.open('http://www.example.com/login.html')
\end{verbatim}


以下は HTTP ヘッダを追加する例です:

\var{headers} 引数を使って\class{Request} コンストラクタを呼び出す方法
の他に、以下のようにできます:

\begin{verbatim}
import urllib2
req = urllib2.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
r = urllib2.urlopen(req)
\end{verbatim}

\class{OpenerDirector} は全ての \class{Request} に
\mailheader{User-Agent} ヘッダを自動的に追加します。これを変更するには:

\begin{verbatim}
import urllib2
opener = urllib2.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
opener.open('http://www.example.com/')
\end{verbatim}

のようにします。

また、\class{Request} が\function{urlopen()} (や
\method{OpenerDirector.open()}) に渡される際には、いくつかの標準ヘッダ
(\mailheader{Content-Length}, \mailheader{Content-Type} および
\mailheader{Host}) も追加されることを忘れないでください。
