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

### ナビゲーション

- 索引
- モジュール |
- 次へ |
- 前へ |
- Python 2.7ja1 documentation »
- Python 標準ライブラリ »
- 26. デバッグとプロファイル »

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

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

参考

最新バージョンの trace module Python source code

## 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 および --counts オプションと互いに排他的です。つまり --listfuncs オプションを指定した場合 --trace や --counts は指定できず、逆も然りです。

`-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

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

### ナビゲーション

- 索引
- モジュール |
- 次へ |
- 前へ |
- Python 2.7ja1 documentation »
- Python 標準ライブラリ »
- 26. デバッグとプロファイル »