3.12 `traceback` -- スタックトレースの表示や取り出し

このモジュールはPythonプログラムのスタックトレースを抽出し、書式を整え、表示するための標準インターフェースを提供します。モジュールがスタックトレースを表示するとき、Pythonインタープリタの動作を正確に模倣します。インタープリタの``ラッパー''の場合のように、プログラムの制御の元でスタックとレースを表示したいと思ったときに役に立ちます。

モジュールはtracebackオブジェクトを使います -- これは変数sys.exc_traceback(非推奨)とsys.last_tracebackに保存され、sys.exc_info()から三番目の項目として返されるオブジェクト型です。

モジュールは次の関数を定義します:

print_tb( traceback[, limit[, file]]): tracebackからlimitまでスタックトレース項目を出力します。limitが省略されるかNoneの場合は、すべての項目が表示されます。fileが省略されるかNoneの場合は、sys.stderrへ出力されます。それ以外の場合は、出力を受けるためのオープンしたファイルまたはファイルに類似したオブジェクトであるべきです。

print_exception( type, value, traceback[, limit[, file]]): 例外情報とtracebackからlimitまでスタックトレース項目をfileへ出力します。これは次のようにすることでprint_tb()とは異なります: (1) tracebackがNoneでない場合は、ヘッダ"Traceback (most recent call last):"を出力します。 (2) スタックトレースの後に例外typeとvalueを出力します。 (3) typeがSyntaxErrorであり、valueが適切な形式の場合は、エラーのおおよその位置を示すカレットを付けて構文エラーが起きた行を出力します。

print_exc( [limit[, file]]): これはprint_exception(sys.exc_type, sys.exc_value, sys.exc_traceback, limit, file)のための省略表現です。(非推奨の変数を使う代わりにスレッドセーフな方法で同じ情報を引き出すために、実際にはsys.exc_info()を使います。)

format_exc( [limit[, file]]): これは、print_exc(limit)に似ていますが、ファイルに出力するかわりに文字列を返します。バージョン 2.4 で新たに追加された仕様です。

print_last( [limit[, file]]): これはprint_exception(sys.last_type, sys.last_value, sys.last_traceback, limit, file)の省略表現です。

print_stack( [f[, limit[, file]]]): この関数は呼び出された時点からのスタックトレースを出力します。オプションのf引数は代わりの最初のスタックフレームを指定するために使えます。print_exception()に付いて言えば、オプションのlimitとfile引数は同じ意味を持ちます。

extract_tb( traceback[, limit]): トレースバックオブジェクトtracebackからlimitまで取り出された``前処理済み''スタックトレース項目のリストを返します。スタックトレースの代わりの書式設定を行うために役に立ちます。limitが省略されるかNoneの場合は、すべての項目が取り出されます。``前処理済み''スタックトレース項目とは四つの部分からなる(filename, line number, function name, text)で、スタックトレースに対して通常出力される情報を表しています。textは前と後ろに付いている空白を取り除いた文字列です。ソースが使えない場合はNoneです。

extract_stack( [f[, limit]]): 現在のスタックフレームから生のトレースバックを取り出します。戻り値はextract_tb()と同じ形式です。print_stack()について言えば、オプションのfとlimit引数は同じ意味を持ちます。

format_list( list): extract_tb()またはextract_stack()が返すタプルのリストが与えられると、出力の準備を整えた文字列のリストを返します。結果として生じるリストの中の各文字列は、引数リストの中の同じインデックスの要素に対応します。各文字列は末尾に改行が付いています。その上、ソーステキスト行がNoneでないそれらの要素に対しては、文字列は内部に改行を含んでいるかもしれません。

format_exception_only( type, value): トレースバックの例外部分の書式を設定します。引数はsys.last_typeとsys.last_valueのような例外の型と値です。戻り値はそれぞれが改行で終わっている文字列のリストです。通常、リストは一つの文字列を含んでいます。しかし、SyntaxError例外に対しては、(出力されるときに)構文エラーが起きた場所についての詳細な情報を示す行をいくつか含んでいます。どの例外が起きたのかを示すメッセージは、常にリストの最後の文字列です。

format_exception( type, value, tb[, limit]): スタックトレースと例外情報の書式を設定します。引数はprint_exception()の対応する引数と同じ意味を持ちます。戻り値は文字列のリストで、それぞれの文字列は改行で終わり、そのいくつかは内部に改行を含みます。これらの行が連結されて出力される場合は、厳密にprint_exception()と同じテキストが出力されます。

format_tb( tb[, limit]): format_list(extract_tb(tb, limit))の省略表現。

format_stack( [f[, limit]]): format_list(extract_stack(f, limit))の省略表現。

tb_lineno( tb): この関数はトレースバックオブジェクトに設定された現在の行番号をかえします。この関数は必要でした。なぜなら、-OフラグがPythonへ渡されたとき、Pythonの2.3より前のバージョンではtb.tb_linenoが正しく更新されなかったからです。この関数は2.3以降のバージョンでは役に立ちません。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。

3.12 traceback -- スタックトレースの表示や取り出し

3.12 `traceback` -- スタックトレースの表示や取り出し