trace --- Python 文実行のトレースと追跡¶
ソースコード: Lib/trace.py
trace モジュールを使うと、プログラムの実行をトレースし、各文のカバレッジを示す注釈付きリストを生成できます。
また、呼び出し元と呼び出し先の関係を表示したり、プログラムの実行中に呼び出された関数を列挙したりできます。
他のプログラムからも、コマンドラインからも利用できます。
参考
- Coverage.py
サードパーティの人気なカバレッジツールで、 HTML 出力に加えて分岐カバレッジのような高度な機能も提供しています。
コマンドラインからの使用¶
trace モジュールはコマンドラインから起動できます。
例えば、次のように簡単に使えます。
python -m trace --count -C . somefile.py ...
これで、 somefile.py の実行中に import された Python モジュールの注釈付きリストがカレントディレクトリに生成されます。
- --help¶
使い方を表示して終了します。
- --version¶
モジュールのバージョンを表示して終了します。
Added in version 3.8: 実行可能なモジュールを実行するための --module オプションが追加されました。
主要なオプション¶
trace を起動するときは、以下のオプションのうち少なくとも 1 つを指定しなければなりません。
--listfuncs オプションは、--trace および --count オプションとは同時に指定できません。
--listfuncs を指定すると --count も --trace も指定できず、その逆も同様です。
- -c, --count¶
プログラム完了時に、それぞれの文が何回実行されたかを示す注釈付きリストのファイルを生成します。下記の
--coverdir,--file,--no-reportも参照してください。
- -t, --trace¶
実行された通りに行を表示します。
- -l, --listfuncs¶
プログラム実行の際に実行された関数を表示します。
- -T, --trackcalls¶
プログラム実行によって明らかになった呼び出しの関係を表示します。
修飾的オプション¶
- -C, --coverdir=<dir>¶
レポートファイルを保存するディレクトリを指定します。
package.moduleについてのカバレッジレポートはdir/package/module.coverに書き込まれます。
- -m, --missing¶
注釈付きリストの生成時に、実行されなかった行に
>>>>>>の印を付けます。
- -g, --timing¶
各行の先頭にプログラム開始からの時間を付けます。トレース中にだけ使われます。
フィルターオプション¶
これらのオプションは複数回指定できます。
- --ignore-module=<mod>¶
指定されたモジュールと（パッケージだった場合は）そのサブモジュールを無視します。引数はカンマ区切りのモジュール名リストです。
- --ignore-dir=<dir>¶
指定されたディレクトリとサブディレクトリ中のモジュールとパッケージを全て無視します。引数は
os.pathsepで区切られたディレクトリのリストです。
プログラミングインターフェース¶
- class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)¶
文 (statement) や式 (expression) の実行をトレースするオブジェクトを作成します。 引数は全てオプションです。 count は各行の実行回数の集計を有効にします。 trace は行実行のトレースを行います。 countfuncs は実行中に呼ばれた関数を列挙します。 countcallers は呼び出しの関係を追跡します。 ignoremods は無視するモジュールやパッケージのリストです。 ignoredirs は無視するパッケージやモジュールを含むディレクトリのリストです。 infile は保存された集計 (count) 情報を読むファイルの名前です。 outfile は更新された集計 (count) 情報を書き出すファイルの名前です。 timing は、タイムスタンプをトレース開始時点からの相対秒数で表示します。
- runctx(cmd, globals=None, locals=None)¶
指定された globals と locals 環境下で、コマンドを実行して、現在のトレースパラメータに基づいてその実行から統計情報を集めます。定義しない場合、globals と locals はデフォルトで空の辞書となります。
- results()¶
与えられた
Traceインスタンスのrun,runctx,runfuncの以前の呼び出しについて集計した結果を納めたCoverageResultsオブジェクトを返します。蓄積されたトレース結果はリセットしません。
- class trace.CoverageResults¶
カバレッジ結果のコンテナで、
Trace.results()で生成されるものです。ユーザーが直接生成するものではありません。- update(other)¶
別の
CoverageResultsオブジェクトのデータを統合します。
- write_results(show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False)¶
カバレッジ結果を書き出します。ヒットしなかった行も出力するには show_missing を指定します。モジュールごとの概要を出力に含めるには summary を指定します。coverdir に指定するのは結果ファイルを出力するディレクトリです。
Noneの場合は各ソースファイルごとの結果がそれぞれのディレクトリに置かれます。ignore_missing_files が
Trueの場合には、すでに存在しないファイルのカバレッジカウントはサイレントに無視されます。そうでなければ、ファイルが見つからないとFileNotFoundErrorが発生します。バージョン 3.13 で変更: ignore_missing_files 引数が追加されました。
簡単な例でプログラミングインターフェースの使い方を見てみましょう:
import sys
import trace
# Trace オブジェクトを作成し、無視する対象と、トレース・行の実行回数の集計の
# どちらか、または両方を行うかを指定する
tracer = trace.Trace(
ignoredirs=[sys.prefix, sys.exec_prefix],
trace=0,
count=1)
# 指定したトレーサを使って新しいコマンドを実行する
tracer.run('main()')
# レポートを作成し、カレントディレクトリに出力する
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")