"bdb" --- デバッガーフレームワーク
**********************************

**ソースコード:** Lib/bdb.py

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

"bdb" モジュールは、ブレークポイントを設定したり、デバッガー経由で実行
を管理するような、基本的なデバッガー機能を提供します。

以下の例外が定義されています:

exception bdb.BdbQuit

   "Bdb" クラスが、デバッガーを終了させるために投げる例外。

"bdb" モジュールは2つのクラスを定義しています:

class bdb.Breakpoint(self, file, line, temporary=0, cond=None, funcname=None)

   このクラスはテンポラリブレークポイント、無視するカウント、無効化と
   再有効化、条件付きブレークポイントを実装しています。

   ブレークポイントは "bpbynumber" という名前のリストで番号によりイン
   デックスされ、 "bplist" により "(file, line)" の形でインデックスさ
   れます。 "bpbynumber" は "Breakpoint" クラスのインスタンスを指して
   います。一方 "bplist" は、同じ行に複数のブレークポイントが設定され
   る場合があるので、インスタンスのリストを指しています。

   ブレークポイントを作るとき、設定されるファイル名は正規化されていな
   ければなりません。*funcname* が設定されたとき、ブレークポイントはそ
   の関数の最初の行が実行されたときにヒットカウントにカウントされます
   。条件付ブレークポイントは毎回カウントされます。

   "Breakpoint" インスタンスは以下のメソッドを持ちます:

   deleteMe()

      このブレークポイントをファイル/行に関連付けられたリストから削除
      します。このブレークポイントがその行に設定された最後のブレークポ
      イントだった場合、そのファイル/行に対するエントリ自体を削除しま
      す。

   enable()

      このブレークポイントを有効にします。

   disable()

      このブレークポイントを無効にします。

   bpformat()

      ブレークポイントに関する情報を持つ文字列をフォーマットして返しま
      す:

      * ブレークポイント番号。

      * テンポラリブレークポイントかどうか。

      * ファイル/行の位置。

      * ブレークする条件。

      * 次のN回無視されるか。

      * ヒットカウント。

      バージョン 3.2 で追加.

   bpprint(out=None)

      ファイル *out* に、またはそれが "None" の場合は標準出力に、
      "bpformat()" の出力を表示する。

class bdb.Bdb(skip=None)

   "Bdb" クラスは一般的なPythonデバッガーの基本クラスとして振舞います
   。

   このクラスはトレース機能の詳細を扱います。ユーザーとのインタラクシ
   ョンは、派生クラスが実装するべきです。標準ライブラリのデバッガクラ
   ス ("pdb.Pdb") がその利用例です。

   *skip* 引数は、もし与えられたならグロブ形式のモジュール名パターンの
   iterable でなければなりません。デバッガはこれらのパターンのどれかに
   マッチするモジュールで発生したフレームにステップインしなくなります
   。フレームが特定のモジュールで発生したかどうかは、フレームのグロー
   バル変数の "__name__" によって決定されます。

   バージョン 3.1 で追加: *skip* 引数が追加されました。

   以下の "Bdb" のメソッドは、通常オーバーライドする必要はありません。

   canonic(filename)

      標準化されたファイル名を取得するための補助関数。標準化されたファ
      イル名とは、(大文字小文字を区別しないファイルシステムにおいて)大
      文字小文字を正規化し、絶対パスにしたものです。ファイル名が "<"
      と ">" で囲まれていた場合はそれを取り除いたものです。

   reset()

      "botframe", "stopframe", "returnframe", "quitting" 属性を、デバ
      ッグを始められる状態に設定します。

   trace_dispatch(frame, event, arg)

      この関数は、デバッグされているフレームのトレース関数としてインス
      トールされます。戻り値は新しいトレース関数(殆どの場合はこの関数
      自身)です。

      デフォルトの実装は、実行しようとしている *event* (文字列として渡
      されます) の種類に基づいてフレームのディスパッチ方法を決定します
      。*event* は次のうちのどれかです:

      * ""line"": 新しい行を実行しようとしています。

      * ""call"": 関数が呼び出されているか、別のコードブロックに入りま
        す。

      * ""return"": 関数か別のコードブロックからreturnしようとしていま
        す。

      * ""exception"": 例外が発生しました。

      * ""c_call"": C関数を呼び出そうとしています。

      * ""c_return"": C関数からreturnしました。

      * ""c_exception"": C関数が例外を発生させました。

      Pythonのイベントに対しては、以下の専用の関数群が呼ばれます。Cの
      イベントに対しては何もしません。

      *arg* 引数は以前のイベントに依存します。

      トレース関数についてのより詳しい情報は、 "sys.settrace()" のドキ
      ュメントを参照してください。コードとフレームオブジェクトについて
      のより詳しい情報は、 標準型の階層 を参照してください。

   dispatch_line(frame)

      デバッガーが現在の行で止まるべきであれば、 "user_line()" メソッ
      ド (サブクラスでオーバーライドされる)を呼び出します。
      "Bdb.quitting" フラグ("user_line()" から設定できます)が設定され
      ていた場合、 "BdbQuit" 例外を発生させます。このスコープのこれか
      らのトレースのために、 "trace_dispatch()" メソッドの参照を返しま
      す。

   dispatch_call(frame, arg)

      デバッガーがこの関数呼び出しで止まるべきであれば、 "user_call()"
      メソッド (サブクラスでオーバーライドされる)を呼び出します。
      "Bdb.quitting" フラグ("user_call()" から設定できます)が設定され
      ていた場合、 "BdbQuit" 例外を発生させます。このスコープのこれか
      らのトレースのために、 "trace_dispatch()" メソッドの参照を返しま
      す。

   dispatch_return(frame, arg)

      デバッガーがこの関数からのリターンで止まるべきであれば、
      "user_return()" メソッド (サブクラスでオーバーライドされる)を呼
      び出します。 "Bdb.quitting" フラグ("user_return()" から設定でき
      ます)が設定されていた場合、 "BdbQuit" 例外を発生させます。このス
      コープのこれからのトレースのために、 "trace_dispatch()" メソッド
      の参照を返します。

   dispatch_exception(frame, arg)

      デバッガーがこの例外発生で止まるべきであれば、
      "user_exception()" メソッド (サブクラスでオーバーライドされる)を
      呼び出します。 "Bdb.quitting" フラグ("user_exception()" から設定
      できます)が設定されていた場合、 "BdbQuit" 例外を発生させます。こ
      のスコープのこれからのトレースのために、 "trace_dispatch()" メソ
      ッドの参照を返します。

   通常、継承クラスは以下のメソッド群をオーバーライドしません。しかし
   、停止やブレークポイント機能を再定義したい場合には、オーバーライド
   することもあります。

   stop_here(frame)

      このメソッドは *frame* がコールスタック中で "botframe" よりも下
      にあるかチェックします。 "botframe" はデバッグを開始したフレーム
      です。

   break_here(frame)

      このメソッドは、*frame* に属するファイル名と行に、あるいは、少な
      くとも現在の関数にブレークポイントがあるかどうかをチェックします
      。ブレークポイントがテンポラリブレークポイントだった場合、このメ
      ソッドはそのブレークポイントを削除します。

   break_anywhere(frame)

      このメソッドは、現在のフレームのファイル名の中にブレークポイント
      が存在するかどうかをチェックします。

   継承クラスはデバッガー操作をするために以下のメソッド群をオーバーラ
   イドするべきです。

   user_call(frame, argument_list)

      このメソッドは、呼ばれた関数の中でブレークする必要がある可能性が
      ある場合に、 "dispatch_call()" から呼び出されます。

   user_line(frame)

      このメソッドは、 "stop_here()" か "break_here()" が "True" を返
      したときに、 "dispatch_line()" から呼び出されます。

   user_return(frame, return_value)

      このメソッドは、 "stop_here()" が "True" を返したときに、
      "dispatch_return()" から呼び出されます。

   user_exception(frame, exc_info)

      このメソッドは、 "stop_here()" が "True" を返したときに、
      "dispatch_exception()" から呼び出されます。

   do_clear(arg)

      ブレークポイントがテンポラリブレークポイントだったときに、それを
      どう削除するかを決定します。

      継承クラスはこのメソッドを実装しなければなりません。

   継承クラスとクライアントは、ステップ状態に影響を及ぼすために以下の
   メソッドを呼び出すことができます。

   set_step()

      コードの次の行でストップします。

   set_next(frame)

      与えられたフレームかそれより下(のフレーム)にある、次の行でストッ
      プします。

   set_return(frame)

      指定されたフレームから抜けるときにストップします。

   set_until(frame)

      現在の行番号よりも大きい行番号に到達したとき、あるいは、現在のフ
      レームから戻るときにストップします。

   set_trace([frame])

      *frame* からデバッグを開始します。*frame* が指定されなかった場合
      、デバッグは呼び出し元のフレームから開始します。

   set_continue()

      ブレークポイントに到達するか終了したときにストップします。もしブ
      レークポイントが1つも無い場合、システムのトレース関数を "None"
      に設定します。

   set_quit()

      "quitting" 属性を "True" に設定します。これにより、次回の
      "dispatch_*()" メソッドのどれかの呼び出しで、 "BdbQuit" 例外を発
      生させます。

   継承クラスとクライアントは以下のメソッドをブレークポイント操作に利
   用できます。これらのメソッドは、何か悪いことがあればエラーメッセー
   ジを含む文字列を返し、すべてが順調であれば "None" を返します。

   set_break(filename, lineno, temporary=0, cond, funcname)

      新しいブレークポイントを設定します。引数の *lineno* 行が
      *filename* に存在しない場合、エラーメッセージを返します。
      *filename* は、 "canonic()" メソッドで説明されているような、標準
      形である必要があります。

   clear_break(filename, lineno)

      *filename* の *lineno* 行にあるブレークポイントを削除します。も
      しブレークポイントが無かった場合、エラーメッセージを返します。

   clear_bpbynumber(arg)

      "Breakpoint.bpbynumber" の中で *arg* のインデックスを持つブレー
      クポイントを削除します。 *arg* が数値でないか範囲外の場合、エラ
      ーメッセージを返します。

   clear_all_file_breaks(filename)

      *filename* に含まれるすべてのブレークポイントを削除します。もし
      ブレークポイントが無い場合、エラーメッセージを返します。

   clear_all_breaks()

      すべてのブレークポイントを削除します。

   get_bpbynumber(arg)

      与えられた数値によって指定されるブレークポイントを返します。
      *arg* が文字列なら数値に変換されます。 *arg* が非数値の文字列で
      ある場合、指定されたブレークポイントが存在しないか削除された場合
      、 "ValueError" が上げられます。

      バージョン 3.2 で追加.

   get_break(filename, lineno)

      *filename* の *lineno* にブレークポイントが存在するかどうかをチ
      ェックします。

   get_breaks(filename, lineno)

      *filename* の *lineno* にあるすべてのブレークポイントを返します
      。ブレークポイントが存在しない場合は空のリストを返します。

   get_file_breaks(filename)

      *filename* の中のすべてのブレークポイントを返します。ブレークポ
      イントが存在しない場合は空のリストを返します。

   get_all_breaks()

      セットされているすべてのブレークポイントを返します。

   継承クラスとクライアントは以下のメソッドを呼んでスタックトレースを
   表現するデータ構造を取得することができます。

   get_stack(f, t)

      与えられたフレームおよび上位(呼び出し側)と下位のすべてのフレーム
      に対するレコードのリストと、上位フレームのサイズを得ます。

   format_stack_entry(frame_lineno, lprefix=': ')

      "(frame, lineno)" で指定されたスタックエントリに関する次のような
      情報を持つ文字列を返します:

      * そのフレームを含むファイル名の標準形。

      * 関数名、もしくは ""<lambda>""。

      * 入力された引数。

      * 戻り値。

      * (あれば)その行のコード。

   以下の2つのメソッドは、文字列として渡された *文* をデバッグするもの
   で、クライアントから利用されます。

   run(cmd, globals=None, locals=None)

      "exec()" 関数を利用して文を実行しデバッグします。 *globals* はデ
      フォルトでは "__main__.__dict__" で、 *locals* はデフォルトでは
      *globals* です。

   runeval(expr, globals=None, locals=None)

      "eval()" 関数を利用して式を実行しデバッグします。 *globals* と
      *locals* は "run()" と同じ意味です。

   runctx(cmd, globals, locals)

      後方互換性のためのメソッドです。 "run()" を使ってください。

   runcall(func, *args, **kwds)

      1つの関数呼び出しをデバッグし、その結果を返します。

最後に、このモジュールは以下の関数を提供しています:

bdb.checkfuncname(b, frame)

   この場所でブレークする必要があるかどうかを、ブレークポイント *b* が
   設定された方法に依存する方法でチェックします。

   ブレークポイントが行番号で設定されていた場合、この関数は "b.line"
   が、同じく引数として与えられた *frame* の中の行に一致するかどうかを
   チェックします。ブレークポイントが関数名で設定されていた場合、この
   関数は *frame* が指定された関数のものであるかどうかと、その関数の最
   初の行であるかどうかをチェックします。

bdb.effective(file, line, frame)

   指定されたソースコード中の行に(有効な)ブレークポイントがあるかどう
   かを判断します。ブレークポイントと、テンポラリブレークポイントを削
   除して良いかどうかを示すフラグからなるタプルを返します。マッチする
   ブレークポイントが存在しない場合は "(None, None)" を返します。

bdb.set_trace()

   "Bdb" クラスのインスタンスを使って、呼び出し元のフレームからデバッ
   グを開始します。
