pytho****@googl*****
pytho****@googl*****
2011年 11月 22日 (火) 01:28:08 JST
Revision: bc0a4bab632d Author: Naoki INADA <inada****@klab*****> Date: Mon Nov 21 08:27:21 2011 Log: Update 2.7.2: library/trace http://code.google.com/p/python-doc-ja/source/detail?r=bc0a4bab632d Modified: /library/trace.rst /library/trace.rst.diff ======================================= --- /library/trace.rst Fri Apr 1 19:44:28 2011 +++ /library/trace.rst Mon Nov 21 08:27:21 2011 @@ -10,6 +10,10 @@ 呼び出し元/呼び出し先の関連やプログラム実行中に実行された関数のリストを出力 します。 これは別個のプログラム中またはコマンドラインから利用することができます。 +.. seealso:: + + 最新バージョンの `trace module Python source code + <http://svn.python.org/view/python/branches/release27-maint/Lib/trace.py?view=markup>`_ .. _trace-cli: @@ -24,80 +28,102 @@ これで、 :file:`somefile.py` の実行中に import された Python モジュールの注釈付きリストがカレントディレクトリに生成されます。 -メタオプション -^^^^^^^^^^^^^^ - -``--help`` + +.. program:: trace + +.. cmdoption:: --help 使い方を表示して終了します。 -``--version`` +.. cmdoption:: --version モジュールのバージョンを表示して終了します。 主要なオプション ^^^^^^^^^^^^^^^^ -``--listfuncs`` オプションは ``--trace`` および ``--count`` オプションと -互いに排他的です。つまり ``--listfuncs`` オプションを指定した場合 ``--trace`` -や ``--count`` は指定できず、逆も然りです。 - -``--count, -c`` +:mod:`trace` を実行する時、以下のオプションのうち少なくとも1つを指定しなけ ればなりません。 +:option:`--listfuncs <-l>` オプションは :option:`--trace <-t>` および +:option:`--counts <-c>` オプションと互いに排他的です。 +つまり :option:`--listfuncs <-l>` オプションを指定した場 合 :option:`--trace <-t>` +や :option:`--counts <-c>` は指定できず、逆も然りです。 + +.. program:: trace + +.. cmdoption:: -c, --count + プログラム完了時に、それぞれのステートメントが何回実行されたかを示す 注釈付きリストのファイルを生成します。 - 下記 ``--coverdir``, ``--file``, ``--no-report`` も参照。 - -``--trace, -t`` + 下記の :option:`--coverdir <-C>`, :option:`--file <-f>`, :option:`--no-report <-R>` も参照。 + +.. cmdoption:: -t, --trace + 実行されるままに行を表示します。 -``--listfuncs, -l`` +.. cmdoption:: -l, --listfuncs + プログラム実行の際に実行された関数を表示します。 -``--report, -r`` - ``--count`` と ``--file`` 引数を使った、過去のプログラム実行結果から +.. cmdoption:: -r, --report + + :option:`--count <-c>` と :option:`--file <-f>` 引数を使った、過去のプロ グラム実行結果から 注釈付きリストのファイルを生成します。コードを実行するわけではありませ ん。 -``--trackcalls, -T`` +.. cmdoption:: -T, --trackcalls + プログラム実行によって明らかになった呼び出しの関連を表示します。 修飾的オプション ^^^^^^^^^^^^^^^^ -``--file=<file>, -f`` +.. program:: trace + +.. cmdoption:: -f, --file=<file> + 複数回にわたるトレース実行についてカウント(count)を蓄積するファイルに名 前をつけます。 - ``--count`` オプションと一緒に使って下さい。 - -``--coverdir=<dir>, -C`` - 中にレポートファイルを保存するディレクトリを指定します。 + :option:`--count <-c>` オプションと一緒に使って下さい。 + +.. cmdoption:: -C, --coverdir=<dir> + + レポートファイルを保存するディレクトリを指定します。 ``package.module`` についてのカバレッジレポートは - ``dir/package/module.cover`` に書き込まれます。 - -``--missing, -m`` - 注釈付きリストの生成時に、実行されなかった行に '``>>>>>>``' の印を付けま す。 - -``--summary, -s`` - ``--count`` または ``--report`` の利用時に、 + :file:`{dir}/{package}/{module}.cover` に書き込まれます。 + +.. cmdoption:: -m, --missing + + 注釈付きリストの生成時に、実行されなかった行に ``>>>>>>`` の印を付けま す。 + +.. cmdoption:: -s, --summary + + :option:`--count <-c>` または :option:`--report <-r>` の利用時に、 処理されたファイルそれぞれの簡潔なサマリを標準出力(stdout)に書き出しま す。 -``--no-report, -R`` - 注釈付きリストを生成しません。これは ``--count`` を何度か走らせてから +.. cmdoption:: -R, --no-report + + 注釈付きリストを生成しません。これは :option:`--count <-c>` を何度か走ら せてから 最後に単一の注釈付きリストを生成するような場合に便利です。 -``--timing, -g`` +.. cmdoption:: -g, --timing + 各行の先頭にプログラム開始からの時間を付けます。トレース中にだけ使われま す。 + フィルターオプション ^^^^^^^^^^^^^^^^^^^^ これらのオプションは複数回指定できます。 -``--ignore-module=<mod>`` - カンマ区切りのモジュール名リストを受け取ります。 +.. program:: trace + +.. cmdoption:: --ignore-module=<mod> + 指定されたモジュールと（パッケージだった場合は）そのサブモジュールを無視 します。 - -``--ignore-dir=<dir>`` + 引数はカンマ区切りのモジュール名リストです。 + +.. cmdoption:: --ignore-dir=<dir> + 指定されたディレクトリとサブディレクトリ中のモジュールとパッケージを全て 無視します。 - (複数のディレクトリを指定する場合は os.pathsep で区切ります) + 引数は :data:`os.pathsep` で区切られたディレクトリのリストです。 .. _trace-api: @@ -106,7 +132,7 @@ ------------------------------ -.. class:: Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False) +.. class:: Trace([count=1[, trace=1[, countfuncs=0[, countcallers=0[, ignoremods=()[, ignoredirs=()[, infile=None[, outfile=None[, timing=False]]]]]]]]]) 文(statement)や式(expression)の実行をトレースするオブジェクトを作成しま す。 全てのパラメタがオプションです。 @@ -121,53 +147,48 @@ *timing* は、タイムスタンプをトレース開始時点からの相対秒数で表示しま す。 -.. method:: Trace.run(cmd) - - *cmd* を、 :class:`Trace` オブジェクトのコントロール下で - 現在のトレースパラメタのもとに実行します。 - *cmd* は文字列かコードオブジェクトで、 :keyword:`exec` に渡せる - ようなものでなければなりません。 - - .. (メモ) :func:`exec` とあったが exec が関数になったのは 3.x - だけなので、ここでは :keyword:`exec` にしておいた。 - - -.. method:: Trace.runctx(cmd, globals=None, locals=None) - - *cmd* を、 :class:`Trace` オブジェクトのコントロール下で - 現在のトレースパラメタのもと、定義されたグローバルおよびローカル環境で実 行します。 - 定義しない場合、 *globals* と *locals* はデフォルトで空の辞書となりま す。 - - -.. method:: Trace.runfunc(func, *args, **kwds) - - 与えられた引数の *func* を、 :class:`Trace` オブジェクトのコントロール下 で - 現在のトレースパラメタのもとに呼び出します。 - -.. method:: Trace.results() - - 与えられた :class:`Trace` インスタンスの ``run``, ``runctx``, ``runfunc`` - の以前の呼び出しについて集計した結果を納めた :class:`CoverageResults` - オブジェクトを返します。蓄積されたトレース結果はリセットしません。 + .. method:: run(cmd) + + コマンドを実行して、現在のトレースパラメータに基づいてその実行から + 統計情報を集めます。 + *cmd* は、 :func:`exec` に渡せるような文字列か code オブジェクトで す。 + + + .. method:: runctx(cmd[, globals=None[, locals=None]]) + + 指定された globals と locals 環境下で、コマンドを実行して、現在の + トレースパラメータに基づいてその実行から統計情報を集めます。 + *cmd* は、 :func:`exec` に渡せるような文字列か code オブジェクトで す。 + 定義しない場合、 *globals* と *locals* はデフォルトで空の辞書となり ます。 + + + .. method:: runfunc(func, *args, **kwds) + + 与えられた引数の *func* を、 :class:`Trace` オブジェクトのコントロー ル下で + 現在のトレースパラメタのもとに呼び出します。 + + .. method:: results() + + 与えられた :class:`Trace` インスタンスの ``run``, ``runctx``, ``runfunc`` + の以前の呼び出しについて集計した結果を納め た :class:`CoverageResults` + オブジェクトを返します。蓄積されたトレース結果はリセットしません。 .. class:: CoverageResults カバレッジ結果のコンテナで、 :meth:`Trace.results` で生成されるもので す。 ユーザーが直接生成するものではありません。 -.. method:: CoverageResults.update(other) - - 別の :class:`CoverageResults` オブジェクトのデータを統合します。 - -.. method:: CoverageResults.write_results(show_missing=True, summary=False, coverdir=None) - - カバレッジ結果を書き出します。 - ヒットしなかった行も出力するには *show_missing* を指定します。 - モジュールごとのサマリーを出力に含めるには *summary* を指定します。 - *coverdir* に指定するのは結果ファイルを出力するディレクトリです。 - ``None`` の場合は各ソースファイルごとの結果がそれぞれのディレクトリに置 かれます。 - -.. + .. method:: update(other) + + 別の :class:`CoverageResults` オブジェクトのデータを統合します。 + + .. method:: write_results([show_missing=True[, summary=False[, coverdir=None]]]) + + カバレッジ結果を書き出します。 + ヒットしなかった行も出力するには *show_missing* を指定します。 + モジュールごとのサマリーを出力に含めるには *summary* を指定します。 + *coverdir* に指定するのは結果ファイルを出力するディレクトリです。 + ``None`` の場合は各ソースファイルごとの結果がそれぞれのディレクトリ に置かれます。 簡単な例でプログラミングインターフェースの使い方を見てみましょう :: ======================================= --- /library/trace.rst.diff Sun Oct 30 17:04:23 2011 +++ /library/trace.rst.diff Mon Nov 21 08:27:21 2011 @@ -98,25 +98,25 @@ Modifiers ^^^^^^^^^ --``--file=<file>, -f`` +.. program:: trace -- Name of a file to accumulate counts over several tracing runs. Should be used -- with the ``--count`` option. +-``--file=<file>, -f`` +.. cmdoption:: -f, --file=<file> --``--coverdir=<dir>, -C`` +- Name of a file to accumulate counts over several tracing runs. Should be used +- with the ``--count`` option. + Name of a file to accumulate counts over several tracing runs. Should be + used with the :option:`--count <-c>` option. -- Directory where the report files go. The coverage report for -- ``package.module`` is written to file ``dir/package/module.cover``. +-``--coverdir=<dir>, -C`` +.. cmdoption:: -C, --coverdir=<dir> --``--missing, -m`` +- Directory where the report files go. The coverage report for +- ``package.module`` is written to file ``dir/package/module.cover``. + Directory where the report files go. The coverage report for + ``package.module`` is written to file :file:`{dir}/{package}/{module}.cover`. + +-``--missing, -m`` +.. cmdoption:: -m, --missing When generating annotated listings, mark lines which were not executed with @@ -152,21 +152,21 @@ These options may be repeated multiple times. --``--ignore-module=<mod>`` +.. program:: trace -- Accepts comma separated list of module names. Ignore each of the named -- modules and its submodules (if it is a package). +-``--ignore-module=<mod>`` +.. cmdoption:: --ignore-module=<mod> --``--ignore-dir=<dir>`` +- Accepts comma separated list of module names. Ignore each of the named +- modules and its submodules (if it is a package). + Ignore each of the given module names and its submodules (if it is a + package). The argument can be a list of names separated by a comma. -- Ignore all modules and packages in the named directory and subdirectories -- (multiple directories can be joined by ``os.pathsep``). +-``--ignore-dir=<dir>`` +.. cmdoption:: --ignore-dir=<dir> + +- Ignore all modules and packages in the named directory and subdirectories +- (multiple directories can be joined by ``os.pathsep``). + Ignore all modules and packages in the named directory and subdirectories. + The argument can be a list of directories separated by :data:`os.pathsep`. @@ -177,61 +177,59 @@ +Programmatic Interface +---------------------- +-.. class:: Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False) +.. class:: Trace([count=1[, trace=1[, countfuncs=0[, countcallers=0[, ignoremods=()[, ignoredirs=()[, infile=None[, outfile=None[, timing=False]]]]]]]]]) --.. class:: Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False) +- Create an object to trace execution of a single statement or expression. All +- parameters are optional. *count* enables counting of line numbers. *trace* + Create an object to trace execution of a single statement or expression. All + parameters are optional. *count* enables counting of line numbers. *trace* +- enables line execution tracing. *countfuncs* enables listing of the functions +- called during the run. *countcallers* enables call relationship tracking. + enables line execution tracing. *countfuncs* enables listing of the + functions called during the run. *countcallers* enables call relationship +- *ignoremods* is a list of modules or packages to ignore. *ignoredirs* is a list +- of directories whose modules or packages should be ignored. *infile* is the + tracking. *ignoremods* is a list of modules or packages to ignore. + *ignoredirs* is a list of directories whose modules or packages should be +- name of the file from which to read stored count information. *outfile* is +- the name of the file in which to write updated count information. *timing* + ignored. *infile* is the name of the file from which to read stored count + information. *outfile* is the name of the file in which to write updated +- enables a timestamp relative to when tracing was started to be displayed. + count information. *timing* enables a timestamp relative to when tracing was + started to be displayed. - -- Create an object to trace execution of a single statement or expression. All -- parameters are optional. *count* enables counting of line numbers. *trace* -- enables line execution tracing. *countfuncs* enables listing of the functions -- called during the run. *countcallers* enables call relationship tracking. -- *ignoremods* is a list of modules or packages to ignore. *ignoredirs* is a list -- of directories whose modules or packages should be ignored. *infile* is the -- name of the file from which to read stored count information. *outfile* is -- the name of the file in which to write updated count information. *timing* -- enables a timestamp relative to when tracing was started to be displayed. + +-.. method:: Trace.run(cmd) + .. method:: run(cmd) +- Run *cmd* under control of the :class:`Trace` object with the current tracing parameters. +- *cmd* must be a string or code object, suitable for passing into :func:`exec`. + Execute the command and gather statistics from the execution with + the current tracing parameters. *cmd* must be a string or code object, + suitable for passing into :func:`exec`. --.. method:: Trace.run(cmd) +-.. method:: Trace.runctx(cmd, globals=None, locals=None) + .. method:: runctx(cmd[, globals=None[, locals=None]]) -- Run *cmd* under control of the :class:`Trace` object with the current tracing parameters. -- *cmd* must be a string or code object, suitable for passing into :func:`exec`. +- Run *cmd* under control of the :class:`Trace` object with the current tracing parameters +- in the defined global and local environments. If not defined, *globals* and +- *locals* default to empty dictionaries. + Execute the command and gather statistics from the execution with the + current tracing parameters, in the defined global and local + environments. If not defined, *globals* and *locals* default to empty + dictionaries. +-.. method:: Trace.runfunc(func, *args, **kwds) + .. method:: runfunc(func, *args, **kwds) --.. method:: Trace.runctx(cmd, globals=None, locals=None) +- Call *func* with the given arguments under control of the :class:`Trace` object +- with the current tracing parameters. + Call *func* with the given arguments under control of the :class:`Trace` + object with the current tracing parameters. -- Run *cmd* under control of the :class:`Trace` object with the current tracing parameters -- in the defined global and local environments. If not defined, *globals* and -- *locals* default to empty dictionaries. + .. method:: results() -- --.. method:: Trace.runfunc(func, *args, **kwds) -- -- Call *func* with the given arguments under control of the :class:`Trace` object -- with the current tracing parameters. - -.. method:: Trace.results() -
