"trace" --- Trace or track Python statement execution
*****************************************************

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

======================================================================

"trace" モジュールにより、プログラム実行のトレース、 注釈された文のカ
バレッジの一覧の作成、呼び出し元/呼び出し先の関係の出力、プログラム実
行中に実行された関数の表の作成を行うことができます。 これは別のプログ
ラム中やコマンドラインから利用することができます。

参考:

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


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

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

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

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

--help

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

--version

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

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


主要なオプション
----------------

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

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

      カバレッジ結果を書き出します。ヒットしなかった行も出力するには
      *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=".")
