目次

前のトピックへ

26.6. timeit — 小さなコード断片の実行時間計測

次のトピックへ

27. Python ランタイムサービス

このページ

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

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

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

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

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

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

26.7.1.1. メタオプション

--help

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

--version

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

26.7.1.2. 主要なオプション

--listfuncs オプションは --trace および --count オプションと互いに排他的です。つまり --listfuncs オプションを指定した場合 --trace--count は指定できず、逆も然りです。

--count, -c
プログラム完了時に、それぞれのステートメントが何回実行されたかを示す注釈付きリストのファイルを生成します。下記 --coverdir, --file, --no-report も参照。
--trace, -t
実行されるままに行を表示します。
--listfuncs, -l
プログラム実行の際に実行された関数を表示します。
--report, -r
--count--file 引数を使った、過去のプログラム実行結果から注釈付きリストのファイルを生成します。コードを実行するわけではありません。
--trackcalls, -T
プログラム実行によって明らかになった呼び出しの関連を表示します。

26.7.1.3. 修飾的オプション

--file=<file>, -f
複数回にわたるトレース実行についてカウント(count)を蓄積するファイルに名前をつけます。 --count オプションと一緒に使って下さい。
--coverdir=<dir>, -C
中にレポートファイルを保存するディレクトリを指定します。 package.module についてのカバレッジレポートは dir/package/module.cover に書き込まれます。
--missing, -m
注釈付きリストの生成時に、実行されなかった行に ‘>>>>>>‘ の印を付けます。
--summary, -s
--count または --report の利用時に、処理されたファイルそれぞれの簡潔なサマリを標準出力(stdout)に書き出します。
--no-report, -R
注釈付きリストを生成しません。これは --count を何度か走らせてから最後に単一の注釈付きリストを生成するような場合に便利です。
--timing, -g
各行の先頭にプログラム開始からの時間を付けます。トレース中にだけ使われます。

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

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

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

Trace.run(cmd)

cmd を、 Trace オブジェクトのコントロール下で現在のトレースパラメタのもとに実行します。 cmd は文字列かコードオブジェクトで、 exec に渡せるようなものでなければなりません。

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

cmd を、 Trace オブジェクトのコントロール下で現在のトレースパラメタのもと、定義されたグローバルおよびローカル環境で実行します。定義しない場合、 globalslocals はデフォルトで空の辞書となります。

Trace.runfunc(func, *args, **kwds)

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

Trace.results()

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

class trace.CoverageResults

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

CoverageResults.update(other)

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

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")