
:mod:`cgitb` --- CGI スクリプトのトレースバック管理機構
=======================================================

.. module:: cgitb
   :synopsis: 設定可能な、CGI スクリプトのトレースバック処理機構です。
.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>


.. versionadded:: 2.2

.. index::
   single: CGI; exceptions
   single: CGI; tracebacks
   single: exceptions; in CGI scripts
   single: tracebacks; in CGI scripts

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

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

   import cgitb
   cgitb.enable()

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


.. function:: enable([display[, logdir[, context [, format]]]])

   .. index:: single: excepthook() (in module sys)

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

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


.. function:: handler([info])

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

