20.3. "cgitb" --- CGI スクリプトのトレースバック管理機構
********************************************************

バージョン 2.2 で追加.

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

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

   import cgitb
   cgitb.enable()

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

cgitb.enable([display[, logdir[, context[, format]]]])

   この関数は、 "sys.excepthook" を設定することで、インタプリタの標準
   の例外処理を "cgitb" モジュールに肩代わりさせるようにします。

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

cgitb.handler([info])

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