26.7. trace — Python ステートメント実行のトレースと追跡

ソースコード: Lib/trace.py

trace モジュールはプログラム実行のトレースを可能にし、 generate ステートメントのカバレッジリストを注釈付きで生成して、呼び出し元/呼び出し先の関連やプログラム実行中に実行された関数のリストを出力します。これは別個のプログラム中またはコマンドラインから利用することができます。

26.7.1. コマンドラインからの使用

trace モジュールはコマンドラインから起動することができます。これは次のように単純です

python -m trace --count -C . somefile.py ...

これで、 somefile.py の実行中に import された Python モジュールの注釈付きリストがカレントディレクトリに生成されます。

--help

使い方を表示して終了します。

--version

モジュールのバージョンを表示して終了します。

26.7.1.1. 主要なオプション

trace を実行するときには、以下のオプションの少なくとも 1 つを指定しなければいけません。 --listfuncs オプションは、 --trace オプション、 --count オプションと相互排他的です。 --listfuncs が与えられたとき、 --trace オプション、 --count オプションの両方とも受け付けず、他の場合も同様です。

-c, --count

プログラム完了時に、それぞれのステートメントが何回実行されたかを示す注釈付きリストのファイルを生成します。下記の --coverdir, --file, --no-report も参照。

-t, --trace

実行されるままに行を表示します。

-l, --listfuncs

プログラム実行の際に実行された関数を表示します。

-r, --report

--count と --file 引数を使った、過去のプログラム実行結果から注釈付きリストのファイルを生成します。コードを実行するわけではありません。

-T, --trackcalls

プログラム実行によって明らかになった呼び出しの関連を表示します。

26.7.1.2. 修飾的オプション

-f, --file=<file>

複数回にわたるトレース実行についてカウント(count)を蓄積するファイルに名前をつけます。 --count オプションと一緒に使って下さい。

-C, --coverdir=<dir>

レポートファイルを保存するディレクトリを指定します。 package.module についてのカバレッジレポートは dir/package/module.cover に書き込まれます。

-m, --missing

注釈付きリストの生成時に、実行されなかった行に >>>>>> の印を付けます。

-s, --summary

--count または --report の利用時に、処理されたファイルそれぞれの簡潔なサマリを標準出力(stdout)に書き出します。

-R, --no-report

注釈付きリストを生成しません。これは --count を何度か走らせてから最後に単一の注釈付きリストを生成するような場合に便利です。

-g, --timing

各行の先頭にプログラム開始からの時間を付けます。トレース中にだけ使われます。

26.7.1.3. フィルターオプション

これらのオプションは複数回指定できます。

--ignore-module=<mod>

指定されたモジュールと（パッケージだった場合は）そのサブモジュールを無視します。引数はカンマ区切りのモジュール名リストです。

--ignore-dir=<dir>

指定されたディレクトリとサブディレクトリ中のモジュールとパッケージを全て無視します。引数は os.pathsep で区切られたディレクトリのリストです。

26.7.2. プログラミングインターフェース

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 は、タイムスタンプをトレース開始時点からの相対秒数で表示します。

run(cmd)

コマンドを実行して、現在のトレースパラメータに基づいてその実行から統計情報を集めます。 cmd は、 exec() に渡せるような文字列か code オブジェクトです。

runctx(cmd, globals=None, locals=None)

指定された globals と locals 環境下で、コマンドを実行して、現在のトレースパラメータに基づいてその実行から統計情報を集めます。cmd は、exec() に渡せるような文字列か code オブジェクトです。定義しない場合、globals と locals はデフォルトで空の辞書となります。

runfunc(func, *args, **kwds)

与えられた引数の func を、 Trace オブジェクトのコントロール下で現在のトレースパラメタのもとに呼び出します。

results()

与えられた Trace インスタンスの run, runctx, runfunc の以前の呼び出しについて集計した結果を納めた CoverageResults オブジェクトを返します。蓄積されたトレース結果はリセットしません。

class trace.CoverageResults

カバレッジ結果のコンテナで、 Trace.results() で生成されるものです。ユーザーが直接生成するものではありません。

update(other)

別の CoverageResults オブジェクトのデータを統合します。

write_results([show_missing=True[, summary=False[, coverdir=None]]])

カバレッジ結果を書き出します。ヒットしなかった行も出力するには show_missing を指定します。モジュールごとのサマリーを出力に含めるには summary を指定します。coverdir に指定するのは結果ファイルを出力するディレクトリです。None の場合は各ソースファイルごとの結果がそれぞれのディレクトリに置かれます。

簡単な例でプログラミングインターフェースの使い方を見てみましょう:

import sys
import trace

# create a Trace object, telling it what to ignore, and whether to
# do tracing or line-counting or both.
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# run the new command using the given tracer
tracer.run('main()')

# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")