Python プロファイラ
*******************

**ソースコード:** Lib/profile.py と Lib/pstats.py

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


プロファイラとは
================

"cProfile" と "profile" は *決定論的プロファイリング (deterministic
profiling)* を行います。 *プロファイル (profile)* とは、プログラムの各
部分がどれだけ頻繁に呼ばれたか、そして実行にどれだけ時間がかかったかと
いう統計情報です。 "pstats" モジュールを使ってこの統計情報をフォーマッ
トし表示することができます。

Python 標準ライブラリは同じインターフェイスを提供するプロファイラの実
装を2つ提供しています:

1. "cProfile" はほとんどのユーザーに推奨されるモジュールです。 C言語で
   書かれた拡張モジュールで、オーバーヘッドが少ないため長時間実行され
   るプログラムのプロファイルに適しています。 Brett Rosen と Ted
   Czotter によって提供された "lsprof" に基づいています。

2. "profile" はピュア Python モジュールで、 "cProfile" モジュールはこ
   のモジュールのインターフェースを真似ています。対象プログラムに相当
   のオーバーヘッドが生じます。もしプロファイラに何らかの拡張をしたい
   のであれば、こちらのモジュールを拡張する方が簡単でしょう。このモジ
   ュールはもともと Jim Roskind により設計、実装されました。

注釈:

  2つのプロファイラモジュールは、与えられたプログラムの実行時プロファ
  イルを取得するために設計されており、ベンチマークのためのものではあり
  ません (ベンチマーク用途には "timeit" のほうが正確な計測結果を求めら
  れます)。これは Python コードと C で書かれたコードをベンチマークする
  ときに特に大きく影響します。プロファイラは Python コードに対してオー
  バーヘッドを発生しますが、C言語レベルの関数に対してはオーバーヘッド
  を生じません。なのでC言語で書かれたコードが、実際の速度と関係なく、
  Pythonで書かれたコードより速く見えるでしょう。


かんたんユーザマニュアル
========================

この節は "マニュアルなんか読みたくない人"のために書かれています。ここ
ではきわめて簡単な概要説明とアプリケーションのプロファイリングを手っ取
り早く行う方法だけを解説します。

1つの引数を取る関数をプロファイルしたい場合、次のようにできます:

   import cProfile
   import re
   cProfile.run('re.compile("foo|bar")')

(お使いのシステムで "cProfile" が使えないときは代わりに "profile" を使
って下さい)

上のコードは "re.compile()" を実行して、プロファイル結果を次のように表
示します:

         214 function calls (207 primitive calls) in 0.002 seconds

   Ordered by: cumulative time

   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
        1    0.000    0.000    0.002    0.002 {built-in method builtins.exec}
        1    0.000    0.000    0.001    0.001 <string>:1(<module>)
        1    0.000    0.000    0.001    0.001 __init__.py:250(compile)
        1    0.000    0.000    0.001    0.001 __init__.py:289(_compile)
        1    0.000    0.000    0.000    0.000 _compiler.py:759(compile)
        1    0.000    0.000    0.000    0.000 _parser.py:937(parse)
        1    0.000    0.000    0.000    0.000 _compiler.py:598(_code)
        1    0.000    0.000    0.000    0.000 _parser.py:435(_parse_sub)

The first line indicates that 214 calls were monitored.  Of those
calls, 207 were *primitive*, meaning that the call was not induced via
recursion. The next line: "Ordered by: cumulative time" indicates the
output is sorted by the "cumtime" values. The column headings include:

ncalls
   呼び出し回数

tottime
   与えられた関数に消費された合計時間 (sub-function の呼び出しで消費さ
   れた時間は除外されています)

percall
   "tottime" を "ncalls" で割った値

cumtime
   この関数と全ての subfunction に消費された累積時間 (起動から終了まで
   )。この数字は再帰関数に *ついても* 正確です。

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

filename:lineno(function)
   その関数のファイル名、行番号、関数名

最初の行に 2 つの数字がある場合 (たとえば "3/1") は、関数が再帰的に呼
び出されたということです。2 つ目の数字はプリミティブな呼び出しの回数で
、1 つ目の数字は総呼び出し回数です。関数が再帰的に呼び出されなかった場
合、それらは同じ値で数字は 1 つしか表示されないことに留意してください
。

"run()" 関数でファイル名を指定することで、プロファイル実行の終了時に出
力を表示する代わりに、ファイルに保存することが出来ます。

   import cProfile
   import re
   cProfile.run('re.compile("foo|bar")', 'restats')

"pstats.Stats" クラスはファイルからプロファイルの結果を読み込んで様々
な書式に整えます。

ファイル "cProfile" と "profile" は他のスクリプトをプロファイルするた
めのスクリプトとして起動することも出来ます。例えば:

   python -m cProfile [-o output_file] [-s sort_order] (-m module | myscript.py)

-o <output_file>

   Writes the profile results to a file instead of to stdout.

-s <sort_order>

   Specifies one of the "sort_stats()" sort values to sort the output
   by. This only applies when "-o" is not supplied.

-m <module>

   Specifies that a module is being profiled instead of a script.

   Added in version 3.7: Added the "-m" option to "cProfile".

   Added in version 3.8: Added the "-m" option to "profile".

"pstats" モジュールの "Stats" クラスにはプロファイル結果のファイルに保
存されているデータを処理して出力するための様々なメソッドがあります。

   import pstats
   from pstats import SortKey
   p = pstats.Stats('restats')
   p.strip_dirs().sort_stats(-1).print_stats()

"strip_dirs()" メソッドによって全モジュール名から無関係なパスが取り除
かれました。"sort_stats()" メソッドにより、出力される標準的な モジュー
ル/行/名前 文字列にしたがって全項目がソートされました。"print_stats()"
メソッドによって全統計が出力されました。以下のようなソート呼び出しを試
すことができます:

   p.sort_stats(SortKey.NAME)
   p.print_stats()

最初の行ではリストを関数名でソートしています。2行目で情報を出力してい
ます。さらに次の内容も試してください:

   p.sort_stats(SortKey.CUMULATIVE).print_stats(10)

このようにすると、関数が消費した累計時間でソートして、さらにその上位10
件だけを表示します。どのアルゴリズムが時間を多く消費しているのか知りた
いときは、この方法が役に立つはずです。

ループで多くの時間を消費している関数はどれか調べたいときは、次のように
します:

   p.sort_stats(SortKey.TIME).print_stats(10)

上記はそれぞれの関数で消費された時間でソートして、上位10件の関数の情報
が表示されます。

次の内容も試してください:

   p.sort_stats(SortKey.FILENAME).print_stats('__init__')

このようにするとファイル名でソートされ、そのうちクラスの初期化メソッド
(メソッド名 "__init__") に関する統計情報だけが表示されます:

   p.sort_stats(SortKey.TIME, SortKey.CUMULATIVE).print_stats(.5, 'init')

上記は時間 (time) をプライマリキー、累計時間 (cumulative time) をセカ
ンダリキーにしてソートした後でさらに条件を絞って統計情報を出力します。
".5" は上位 50% だけを選択することを意味し、さらにその中から文字列
"init" を含むものだけが表示されます。

どの関数がどの関数を呼び出しているのかを知りたければ、次のようにします
("p" は最後に実行したときの状態でソートされています):

   p.print_callers(.5, 'init')

このようにすると、関数ごとの呼び出し側関数の一覧が得られます。

さらに詳しい機能を知りたければマニュアルを読むか、次の関数の実行結果か
ら内容を推察してください:

   p.print_callees()
   p.add('restats')

スクリプトとして起動した場合、 "pstats" モジュールはプロファイルのダン
プを読み込み、分析するための統計ブラウザとして動きます。シンプルな行指
向のインターフェース ("cmd" を使って実装) とヘルプ機能を備えています。


リファレンスマニュアル -- "profile" と "cProfile"
=================================================

"profile" および "cProfile" モジュールは以下の関数を提供します:

profile.run(command, filename=None, sort=-1)

   この関数は "exec()" 関数に渡せる一つの引数と、オプション引数として
   ファイル名を指定できます。全ての場合でこのルーチンは以下を実行しま
   す:

      exec(command, __main__.__dict__, __main__.__dict__)

   そして実行結果からプロファイル情報を収集します。 ファイル名が指定さ
   れていない場合は、 "Stats" のインスタンスが自動的に作られ、簡単なプ
   ロファイルレポートが表示されます。 *sort* が指定されている場合は、
   "Stats" インスタンスに渡され、結果をどのように並び替えるかを制御し
   ます。

profile.runctx(command, globals, locals, filename=None, sort=-1)

   This function is similar to "run()", with added arguments to supply
   the globals and locals mappings for the *command* string. This
   routine executes:

      exec(command, globals, locals)

   そしてプロファイル統計情報を "run()" 同様に収集します。

class profile.Profile(timer=None, timeunit=0.0, subcalls=True, builtins=True)

   このクラスは普通、プロファイリングを "cProfile.run()" 関数が提供す
   るもの以上に正確に制御したい場合にのみ使われます。

   *timer* 引数に、コードの実行時間を計測するためのカスタムな時刻取得
   用関数を渡せます。これは現在時刻を表す単一の数値を返す関数でなけれ
   ばなりません。もしこれが整数を返す関数ならば、 *timeunit* には単位
   時間当たりの実際の持続時間を指定します。たとえば関数が 1000 分の 1
   秒単位で計測した時間を返すとすると、 *timeunit* は ".001" でしょう
   。

   "Profile" クラスを直接使うと、プロファイルデータをファイルに書き出
   すことなしに結果をフォーマット出来ます:

      import cProfile, pstats, io
      from pstats import SortKey
      pr = cProfile.Profile()
      pr.enable()
      # ... do something ...
      pr.disable()
      s = io.StringIO()
      sortby = SortKey.CUMULATIVE
      ps = pstats.Stats(pr, stream=s).sort_stats(sortby)
      ps.print_stats()
      print(s.getvalue())

   The "Profile" class can also be used as a context manager
   (supported only in "cProfile" module. see コンテキストマネージャ型
   ):

      import cProfile

      with cProfile.Profile() as pr:
          # ... do something ...

          pr.print_stats()

   バージョン 3.8 で変更: コンテキストマネージャーサポートが追加されま
   した。

   enable()

      Start collecting profiling data. Only in "cProfile".

   disable()

      Stop collecting profiling data. Only in "cProfile".

   create_stats()

      プロファイリングデータの収集を停止し、現在のプロファイルとして結
      果を内部で記録します。

   print_stats(sort=-1)

      現在のプロファイルに基づいて "Stats" オブジェクトを作成し、結果
      を標準出力に出力します。

      The *sort* parameter specifies the sorting order of the
      displayed statistics. It accepts a single key or a tuple of keys
      to enable multi-level sorting, as in "Stats.sort_stats".

      Added in version 3.13: "print_stats()" now accepts a tuple of
      keys.

   dump_stats(filename)

      現在のプロファイルの結果を *filename* に書き出します。

   run(cmd)

      "exec()" を用いて cmd をプロファイルします。

   runctx(cmd, globals, locals)

      "exec()" を用いて指定されたグローバルおよびローカルな環境で cmd
      をプロファイルします。

   runcall(func, /, *args, **kwargs)

      "func(*args, **kwargs)" をプロファイルします。

Note that profiling will only work if the called command/function
actually returns.  If the interpreter is terminated (e.g. via a
"sys.exit()" call during the called command/function execution) no
profiling results will be printed.


"Stats" クラス
==============

"Stats" クラスを使用してプロファイラデータを解析します。

class pstats.Stats(*filenames or profile, stream=sys.stdout)

   このコンストラクタは *filename* で指定した (単一または複数の) ファ
   イルもしくは "Profile" のインスタンスから "統計情報オブジェクト" の
   インスタンスを生成します。出力は *stream* で指定したストリームに出
   力されます。

   上記コンストラクタで指定するファイルは、使用する "Stats" に対応した
   バージョンの "profile" または "cProfile" で作成されたものでなければ
   なりません。将来のバージョンのプロファイラとの互換性は *保証されて
   おらず* 、他のプロファイラで生成されたファイルや異なるオペレーティ
   ングシステムで実行される同じプロファイルとの互換性もないことに注意
   してください。複数のファイルを指定した場合、同一の関数の統計情報は
   すべて合算され、複数のプロセスで構成される全体をひとつのレポートで
   検証することが可能になります。既存の "Stats" オブジェクトに別のファ
   イルの情報を追加するときは、 "add()" メソッドを使用します。

   プロファイルデータをファイルから読み込む代わりに、
   "cProfile.Profile" または "profile.Profile" オブジェクトをプロファ
   イルデータのソースとして使うことができます。

   "Stats" には次のメソッドがあります:

   strip_dirs()

      "Stats" クラスのこのメソッドは、ファイル名の前に付いているすべて
      のパス情報を取り除くためのものです。出力の幅を80文字以内に収めた
      いときに重宝します。このメソッドはオブジェクトを変更するため、取
      り除いたパス情報は失われます。パス情報除去の操作後、オブジェクト
      が保持するデータエントリは、オブジェクトの初期化、ロード直後と同
      じように "ランダムに" 並んでいます。 "strip_dirs()" を実行した結
      果、2つの関数名が区別できない (両者が同じファイルの同じ行番号で
      同じ関数名となった) 場合、一つのエントリに合算されされます。

   add(*filenames)

      "Stats" クラスのこのメソッドは、既存のプロファイリングオブジェク
      トに情報を追加します。引数は対応するバージョンの "profile.run()"
      または "cProfile.run()" によって生成されたファイルの名前でなくて
      はなりません。関数の名前が区別できない (ファイル名、行番号、関数
      名が同じ) 場合、一つの関数の統計情報として合算されます。

   dump_stats(filename)

      "Stats" オブジェクトに読み込まれたデータを、ファイル名
      *filename* のファイルに保存します。ファイルが存在しない場合は新
      たに作成され、すでに存在する場合には上書きされます。このメソッド
      は "profile.Profile" クラスおよび "cProfile.Profile" クラスの同
      名のメソッドと等価です。

   sort_stats(*keys)

      This method modifies the "Stats" object by sorting it according
      to the supplied criteria.  The argument can be either a string
      or a SortKey enum identifying the basis of a sort (example:
      "'time'", "'name'", "SortKey.TIME" or "SortKey.NAME"). The
      SortKey enums argument have advantage over the string argument
      in that it is more robust and less error prone.

      2つ以上のキーが指定された場合、2つ目以降のキーは、それ以前のキー
      で等価となったデータエントリの再ソートに使われます。たとえば
      "sort_stats(SortKey.NAME, SortKey.FILE)" とした場合、まずすべて
      のエントリが関数名でソートされた後、同じ関数名で複数のエントリが
      あればファイル名でソートされます。

      For the string argument, abbreviations can be used for any key
      names, as long as the abbreviation is unambiguous.

      The following are the valid string and SortKey:

      +--------------------+-----------------------+------------------------+
      | Valid String Arg   | Valid enum Arg        | 意味                   |
      |====================|=======================|========================|
      | "'calls'"          | SortKey.CALLS         | 呼び出し数             |
      +--------------------+-----------------------+------------------------+
      | "'cumulative'"     | SortKey.CUMULATIVE    | 累積時間               |
      +--------------------+-----------------------+------------------------+
      | "'cumtime'"        | N/A                   | 累積時間               |
      +--------------------+-----------------------+------------------------+
      | "'file'"           | N/A                   | ファイル名             |
      +--------------------+-----------------------+------------------------+
      | "'filename'"       | SortKey.FILENAME      | ファイル名             |
      +--------------------+-----------------------+------------------------+
      | "'module'"         | N/A                   | ファイル名             |
      +--------------------+-----------------------+------------------------+
      | "'ncalls'"         | N/A                   | 呼び出し数             |
      +--------------------+-----------------------+------------------------+
      | "'pcalls'"         | SortKey.PCALLS        | プリミティブな呼び出し |
      |                    |                       | 回数                   |
      +--------------------+-----------------------+------------------------+
      | "'line'"           | SortKey.LINE          | 行番号                 |
      +--------------------+-----------------------+------------------------+
      | "'name'"           | SortKey.NAME          | 関数名                 |
      +--------------------+-----------------------+------------------------+
      | "'nfl'"            | SortKey.NFL           | 関数名/ファイル名/行番 |
      |                    |                       | 号                     |
      +--------------------+-----------------------+------------------------+
      | "'stdname'"        | SortKey.STDNAME       | 標準名                 |
      +--------------------+-----------------------+------------------------+
      | "'time'"           | SortKey.TIME          | 内部時間               |
      +--------------------+-----------------------+------------------------+
      | "'tottime'"        | N/A                   | 内部時間               |
      +--------------------+-----------------------+------------------------+

      すべての統計情報のソート結果は降順 (最も多く時間を消費したものが
      一番上に来る) となることに注意してください。ただし、関数名、ファ
      イル名、行数に関しては昇順 (アルファベット順) になります。
      "SortKey.NFL" と "SortKey.STDNAME" には微妙な違いがあります。標
      準名 (standard name) とは表示された名前によるソートで、埋め込ま
      れた行番号のソート順が特殊です。たとえば、 (ファイル名が同じで)
      3、20、40という行番号のエントリがあった場合、20、3、40 の順に表
      示されます。一方 "SortKey.NFL" は行番号を数値として比較します。
      要するに、 "sort_stats(SortKey.NFL)" は
      "sort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE)" と指
      定した場合と同じになります。

      後方互換性のため、数値を引数に使った "-1", "0", "1", "2" の形式
      もサポートしています。それぞれ "'stdname'", "'calls'", "'time'",
      "'cumulative'" として処理されます。引数をこの旧スタイルで指定し
      た場合、最初のキー (数値キー) だけが使われ、複数のキーを指定して
      も2番目以降は無視されます。

      Added in version 3.7: Added the SortKey enum.

   reverse_order()

      "Stats" クラスのこのメソッドは、オブジェクト内の情報のリストを逆
      順にソートします。デフォルトでは選択したキーに応じて昇順、降順が
      適切に選ばれることに注意してください。

   print_stats(*restrictions)

      "Stats" クラスのこのメソッドは、 "profile.run()" の項で述べたプ
      ロファイルのレポートを出力します。

      出力するデータの順序はオブジェクトに対し最後に行った
      "sort_stats()" による操作に基づきます ("add()" と "strip_dirs()"
      による制限にも支配されます)。

      引数は (もし与えられると) リストを重要なエントリのみに制限するた
      めに使われます。初期段階でリストはプロファイルした関数の完全な情
      報を持っています。制限の指定は、 (行数を指定する) 整数、 (行のパ
      ーセンテージを指定する) 0.0 から 1.0 までの割合を指定する小数、
      (出力する standard name にマッチする) 正規表現として解釈される文
      字列のいずれかを使って行います。複数の制限が指定された場合、指定
      の順に適用されます。たとえば次のようになります:

         print_stats(.1, 'foo:')

      上記の場合まず出力するリストは全体の10%に制限され、さらにファイ
      ル名の一部に文字列 ".*foo:" を持つ関数だけが出力されます:

         print_stats('foo:', .1)

      こちらの例の場合、リストはまずファイル名に ".*foo:" を持つ関数だ
      けに制限され、その中の最初の 10% だけが出力されます。

   print_callers(*restrictions)

      "Stats" クラスのこのメソッドは、プロファイルのデータベースの中か
      ら何らかの関数呼び出しを行った関数をすべて出力します。出力の順序
      は "print_stats()" によって与えられるものと同じです。出力を制限
      する引数も同じです。各呼び出し側関数についてそれぞれ一行ずつ表示
      されます。フォーマットは統計を作り出したプロファイラごとに微妙に
      異なります:

      * "profile" の場合、呼び出し側関数の後に括弧で囲まれて表示される
        数値はその呼び出しが何回行われたかを示しています。利便性のため
        、 2番目の括弧なしで表示される数値によって、関数が消費した累積
        時間を表しています。

      * "cProfile" の場合、各呼び出し側関数の後に3つの数字が付きます。
        呼び出しが何回行われたかと、この呼び出し側関数からの呼び出しに
        よって現在の関数内で消費された合計時間および累積時間です。

   print_callees(*restrictions)

      "Stats" クラスのこのメソッドは、指定した関数から呼び出された関数
      のリストを出力します。呼び出し側、呼び出される側の方向は逆ですが
      、引数と出力の順序に関しては "print_callers()" と同じです。

   get_stats_profile()

      This method returns an instance of StatsProfile, which contains
      a mapping of function names to instances of FunctionProfile.
      Each FunctionProfile instance holds information related to the
      function's profile such as how long the function took to run,
      how many times it was called, etc...

      Added in version 3.9: Added the following dataclasses:
      StatsProfile, FunctionProfile. Added the following function:
      get_stats_profile.


決定論的プロファイリングとは
============================

*決定論的プロファイリング* とは、すべての *関数呼び出し*, *関数からの
リターン*, *例外発生* をモニターし、正確なタイミングを記録することで、
イベント間の時間、つまりどの時間にユーザコードが実行されているのかを計
測するやり方です。もう一方の *統計的プロファイリング* (このモジュール
でこの方法は採用していません) とは、有効なインストラクションポインタか
らランダムにサンプリングを行い、プログラムのどこで時間が使われているか
を推定する方法です。後者の方法は、オーバヘッドが少ないものの、プログラ
ムのどこで多くの時間が使われているか、その相対的な示唆に留まります。

Python の場合、実行中は必ずインタプリタが動作しているため、決定論的プ
ロファイリングを行うために計測用のコードを追加する必要はありません。
Python は自動的に各イベントに *フック* (オプションのコールバック) を提
供します。加えて Python のインタプリタという性質によって、実行時に大き
なオーバーヘッドを伴う傾向がありますが、それに比べると一般的なアプリケ
ーションでは決定論的プロファイリングで追加される処理のオーバーヘッドは
少ない傾向にあります。結果的に、決定論的プロファイリングは少ないコスト
で Python プログラムの実行時間に関する詳細な統計を得られる方法となって
いるのです。

呼び出し回数はコード中のバグ発見にも使用できます (とんでもない数の呼び
出しが行われている部分)。インライン拡張の対象とすべき部分を見つけるた
めにも使えます (呼び出し頻度の高い部分)。内部時間の統計は、注意深く最
適化すべき"ホットループ"の発見にも役立ちます。累積時間の統計は、アルゴ
リズム選択に関連した高レベルのエラー検知に役立ちます。なお、このプロフ
ァイラは再帰的なアルゴリズム実装の累計時間を計ることが可能で、通常のル
ープを使った実装と直接比較することもできるようになっています。


制限事項
========

一つの制限はタイミング情報の正確さに関するものです。決定論的プロファイ
ラには正確さに関する根本的問題があります。最も明白な制限は、 (一般に)
"クロック"は .001 秒の精度しかないということです。これ以上の精度で計測
することはできません。仮に充分な精度が得られたとしても、"誤差"が計測の
平均値に影響を及ぼすことがあります。この最初の誤差を取り除いたとしても
、それがまた別の誤差を引き起こす原因となります。

もう一つの問題として、イベントを検知してからプロファイラがその時刻を実
際に *取得* するまでに "いくらかの時間がかかる" ことです。同様に、イベ
ントハンドラが終了する時にも、時刻を取得して (そしてその値を保存して)
から、ユーザコードが処理を再開するまでの間に遅延が発生します。結果的に
多く呼び出される関数または多数の関数から呼び出される関数の情報にはこの
種の誤差が蓄積する傾向にあります。このようにして蓄積される誤差は、典型
的にはクロックの精度を下回ります (1クロック以下) が、一方でこの時間が
累計して非常に大きな値になることも *あり得ます* 。

この問題はオーバーヘッドの小さい "cProfile" よりも "profile" において
より重要です。そのため、 "profile" は誤差が確率的に (平均値で) 減少す
るようにプラットフォームごとに補正する機能を備えています。プロファイラ
に補正を施すと (最小二乗の意味で) 正確さが増しますが、ときには数値が負
の値になってしまうこともあります (呼び出し回数が極めて少なく、確率の神
があなたに意地悪をしたとき :-) )。プロファイルの結果に負の値が出力され
ても *驚かないでください* 。これは補正を行った場合にのみ生じることで、
補正を行わない場合に比べて計測結果は実際にはより正確になっているはずだ
からです。


キャリブレーション (補正)
=========================

"profile" のプロファイラは time 関数呼び出しおよびその値を保存するため
のオーバーヘッドを補正するために、各イベントの処理時間から定数を引きま
す。デフォルトでこの定数の値は 0 です。以下の手順で、プラットフォーム
に合った、より適切な定数が得られます (制限事項 参照)。

   import profile
   pr = profile.Profile()
   for i in range(5):
       print(pr.calibrate(10000))

calibrate メソッドは引数として与えられた数だけ Python の呼び出しを行い
ます。直接呼び出す場合と、プロファイラを使って呼び出す場合の両方が実施
され、それぞれの時間が計測されます。その結果、プロファイラのイベントに
隠されたオーバーヘッドが計算され、その値は浮動小数として返されます。た
とえば、 1.8 GHz の Intel Core i5 で macOS を使用、 Python の
time.process_time() をタイマとして使った場合、値はおよそ 4.04e-6 とな
ります。

この手順で使用しているオブジェクトはほぼ一定の結果を返します。 *非常に
* 早いコンピュータを使う場合、もしくはタイマの性能が貧弱な場合は、一定
の結果を得るために引数に 100000 や 1000000 といった大きな値を指定する
必要があるかもしれません。

一定の結果が得られたら、それを使う方法には3通りあります:

   import profile

   # 1. Apply computed bias to all Profile instances created hereafter.
   profile.Profile.bias = your_computed_bias

   # 2. Apply computed bias to a specific Profile instance.
   pr = profile.Profile()
   pr.bias = your_computed_bias

   # 3. Specify computed bias in instance constructor.
   pr = profile.Profile(bias=your_computed_bias)

選択肢がある場合は、補正値は小さめに設定した方が良いでしょう。プロファ
イルの結果に負の値が表われる"頻度が低く"なるはずです。


カスタムな時刻取得用関数を使う
==============================

プロファイラが時刻を取得する方法を変更したいなら (たとえば、実測時間や
プロセスの経過時間を使いたい場合)、時刻取得用の関数を "Profile" クラス
のコンストラクタに指定することができます:

   pr = profile.Profile(your_time_func)

この結果生成されるプロファイラは時刻取得に "your_time_func()" を呼び出
すようになります。 "profile.Profile" と "cProfile.Profile" のどちらを
使っているかにより、 "your_time_func" の戻り値は異なって解釈されます:

"profile.Profile"
   "your_time_func()" は単一の数値、あるいは ("os.times()" と同じよう
   に) その合計が累計時間を示すリストを返すようになっていなければなり
   ません。関数が1つの数値、あるいは長さ2の数値のリストを返すようにな
   っていれば、ディスパッチルーチンには特別な高速化バージョンが使われ
   ます。

   Be warned that you should calibrate the profiler class for the
   timer function that you choose (see キャリブレーション (補正)).
   For most machines, a timer that returns a lone integer value will
   provide the best results in terms of low overhead during profiling.
   ("os.times()" is *pretty* bad, as it returns a tuple of floating-
   point values).  If you want to substitute a better timer in the
   cleanest fashion, derive a class and hardwire a replacement
   dispatch method that best handles your timer call, along with the
   appropriate calibration constant.

"cProfile.Profile"
   "your_time_func()" は単一の数値を返すようになっていなければなりませ
   ん。単一の整数を返すのであれば、クラスコンストラクタの第二引数に単
   位時間当たりの実際の持続時間を渡せます。例えば
   "your_integer_time_func" が 1000 分の 1 秒単位で計測した時間を返す
   とすると、 "Profile" インスタンスを以下のように構築出来ます:

      pr = cProfile.Profile(your_integer_time_func, 0.001)

   As the "cProfile.Profile" class cannot be calibrated, custom timer
   functions should be used with care and should be as fast as
   possible.  For the best results with a custom timer, it might be
   necessary to hard-code it in the C source of the internal "_lsprof"
   module.

Python 3.3 で "time" に、プロセス時間や実時間の精密な計測に使える新し
い関数が追加されました。 例えば、 "time.perf_counter()" を参照してくだ
さい。
