# 4 リファレンス・マニュアル - `profile` と `cProfile`

プロファイラのプライマリ・エントリ・ポイントはグローバル関数 `profile.run()` (または `cProfile.run()`) です。通常、プロファイル情報の作成に使われま す。情報は `pstats.Stats` クラスのメソッドを使って整形や出力をお こないます。以下はすべての標準エントリポイントと関数の解説です。さらに いくつかのコードの詳細を知りたければ、「プロファイラの拡張」を読んでく ださい。派生クラスを使ってプロファイラを``改善''する方法やモジュールの ソースコードの読み方が述べられています。

`run`( | command[, filename])

  この関数はオプション引数として `exec` 文に渡すファイル名を指定 できます。このルーチンは必ず最初の引数の `exec` を試み、実行結 果からプロファイル情報を収集しようとします。ファイル名が指定されていな いときは、各行の標準名(standard name)文字列(ファイル名/行数/関数名)で ソートされた、簡単なレポートが表示されます。以下はその出力例です。

            2706 function calls (2004 primitive calls) in 4.504 CPU seconds

      Ordered by: standard name

      ncalls  tottime  percall  cumtime  percall filename:lineno(function)
           2    0.006    0.003    0.953    0.477 pobject.py:75(save_objects)
        43/3    0.533    0.012    0.749    0.250 pobject.py:99(evaluate)
       ...

  最初の行は2706回の関数呼出しがあったことを示しています。 このうち2004回はプリミティブなものです。プリミティブ な呼 び出しとは、再帰によるものではない関数呼出しを指します。次の行 `Ordered by: standard name` は、一番右側の欄の文字列を使ってソー トされたことを意味します。各カラムの見出しの意味は次の通りです。

  ncalls

    呼出し回数

  tottime

    この関数が消費した時間の合計(サブ関数呼出しの時間は除く)

  percall

    `tottime` を `ncalls` で割った値

  cumtime

    サブ関数を含む関数の(実行開始から終了までの)消費時間の合計。この項目は 再帰的な関数においても正確に計測されます。

  percall

    `cumtime` をプリミティブな呼び出し回数で割った値

  filename:lineno(function)

    その関数のファイル名、行番号、関数名

  ("`43/3`" など)最初の欄に2つの数字が表示されている場合、最初の値は 呼出し回数、2番目はプリミティブな呼び出しの回数を表しています。関数が再 帰していない場合はどちらの回数も同じになるため、1つの数値しか表示され ません。

`runctx`( | command, globals, locals[, filename])

  この関数は `run()` に似ていますが、command 文字 列用にグローバル辞書とローカル辞書の引数を追加しています。

プロファイラ・データの分析は `Stats` クラスを使っておこないます。

注意: `Stats` クラスは `pstats` モジュールで定義されています。

クラス `Stats`( | filename[, stream=sys.stdout[, ...]])

  このコンストラクタは filename で指定した(単一または複数の)ファイ ルから``統計情報オブジェクト''のインスタンスを生成します。 `Stats` オブジェクトはレポートを出力するメソッドを通じて操作しま す。また別の出力ストリームをキーワード引数 `stream` で指定できます。

  上記コンストラクタで指定するファイルは、使用する `Stats` に対応 したバージョンの `profile` または `cProfile` で作成され たものでなければなりません。 将来のバージョンのプロファイラとの互換性は保証されておらず、 他のプロファイラとの互換性もないことに注意してください。

  複数のファイルを指定した場合、同一の関数の統計情報はすべて合算され、複 数のプロセスで構成される全体をひとつのレポートで検証することが可能にな ります。既存の `Stats` オブジェクトに別のファイルの情報を追加す るときは、`add()` メソッドを使用します。

  バージョン 2.5 で 変更 された仕様: stream 引数が追加されました