10.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() メソッドを使用します。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。