# 5 リファレンス・マニュアル

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

`run`( | command[, filename])

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

            main()
            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)
       ...

  最初の行はこのプロファイルが `profile.run('main()')` の呼び出しに よって生成されたものであり、実行された文字列は `'main()'` である ことを示しています。2行目は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])

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

プロファイラ・データの分析は `pstats` モジュールを使っておこな います。

クラス `Stats`( | filename[, ...])

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

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

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