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() から取得されます。