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