\section{\module{cgitb} --- CGI スクリプトのトレースバック管理機構}

\declaremodule{standard}{cgitb}
\modulesynopsis{設定可能な、CGI スクリプトのトレースバック処理機構です。}
\moduleauthor{Ka-Ping Yee}{ping@lfw.org}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}

\versionadded{2.2}
\index{CGI!exceptions}
\index{CGI!tracebacks}
\index{exceptions!in CGI scripts}
\index{tracebacks!in CGI scripts}

\module{cgitb} モジュールでは、Python スクリプトのための特殊な例外処理を
提供します。(実はこの説明は少し的外れです。このモジュールはもともと
徹底的なトレースバック情報を CGI スクリプトで生成した HTML 内に表示
するための設計されました。その後この情報を平文テキストでも
表示できるように一般化されています。)
このモジュールの有効化後に捕捉されない例外が生じた場合、
詳細で書式化された報告が Web ブラウザに送信されます。この報告には
各レベルにおけるソースコードの抜粋が示されたトレースバックと、現在動作
している関数の引数やローカルな変数が収められており、問題のデバッグを
助けます。オプションとして、この情報をブラウザに送信する代わりに
ファイルに保存することもできます。

この機能を有効化するためには、単に自作の CGI スクリプトの最初に以下の一行を
追加します:

\begin{verbatim}
import cgitb; cgitb.enable()
\end{verbatim}

\function{enable()} 関数のオプションは、報告をブラウザに表示するか
どうかと、後で解析するためにファイルに報告をログ記録するかどうかを
制御します。


\begin{funcdesc}{enable}{\optional{display\optional{, logdir\optional{,
                         context \optional{, format}}}}}
この関数は、\code{\refmodule{sys}.excepthook} を設定することで、
インタプリタの標準の例外処理を \module{cgitb} モジュールに肩代わり
させるようにします。
  \withsubitem{(in module sys)}{\ttindex{excepthook()}}

オプションの引数 \var{display} は標準で \code{1} になっており、
この値は \code{0} にしてトレースバックをブラウザに送らないように抑制する
こともできます。引数 \var{logdir} はログファイルを配置する
ディレクトリです。オプションの引数 \var{context} は、トレースバック
の中で現在の行の周辺の何行を表示するかです; この値は標準で \code{5} です。
オプションの引数 \var{format} が \code{"html"} の場合、出力は
HTML に書式化されます。その他の値を指定すると平文テキストの出力を
強制します。デフォルトの値は \code{"html"} です。
\end{funcdesc}

\begin{funcdesc}{handler}{\optional{info}}
この関数は標準の設定 (ブラウザに報告を表示しますがファイルには
ログを書き込みません) を使って例外を処理します。
この関数は、例外を捕捉した際に \module{cgitb} を使って報告
したい場合に使うことができます。
オプションの \var{info} 引数は、例外の型、例外の値、トレースバック
オブジェクトからなる 3 要素のタプルでなければなりません。これは
\code{\refmodule{sys}.exc_info()} によって返される値と全く
同じです。\var{info} 引数が与えられていない場合、現在の
例外は \code{\refmodule{sys}.exc_info()} から取得されます。
\end{funcdesc}
