# `trace` --- Python 文実行のトレースと追跡

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

The `trace` module allows you to trace program execution, generate annotated statement coverage listings, print caller/callee relationships and list functions executed during a program run. It can be used in another program or from the command line.

参考

Coverage.py

  サードパーティの人気なカバレッジツールで、 HTML 出力に加えて分岐カバレッジのような高度な機能も提供しています。

## コマンドラインからの使用

The `trace` module can be invoked from the command line. It can be as simple as

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

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

--help

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

--version

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

Added in version 3.8: 実行可能なモジュールを走らせられる `--module` オプションが追加されました。

### 主要なオプション

At least one of the following options must be specified when invoking `trace`. The `--listfuncs` option is mutually exclusive with the `--trace` and `--count` options. When `--listfuncs` is provided, neither `--count` nor `--trace` are accepted, and vice versa.

-c, --count

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

-t, --trace

  実行された通りに行を表示します。

-l, --listfuncs

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

-r, --report

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

-T, --trackcalls

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

### 修飾的オプション

-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

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

### フィルターオプション

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

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

  run(cmd)

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

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

    指定された globals と locals 環境下で、コマンドを実行して、現在のトレースパラメータに基づいてその実行から統計情報を集めます。定義しない場合、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, *, ignore_missing_files=False)

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

    ignore_missing_files が `True` の場合には、すでに存在しないファイルのカバレッジカウントはサイレントに無視されます。そうでなければ、ファイルが見つからないと `FileNotFoundError` が発生します。

    バージョン 3.13 で変更: ignore_missing_files 引数が追加されました。

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

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