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

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

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

"bdb" モジュールは、ブレークポイントの設定やデバッガーを通じた実行の管
理など、デバッガーの基本的な機能を扱います。

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

exception bdb.BdbQuit

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

"bdb" モジュールは、次の 2 つのクラスも定義しています。

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

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

   ブレークポイントは "bpbynumber" というリストでは番号を使って、
   "bplist" では "(file, line)" の組を使って参照します。 前者では一つ
   の "Breakpoint" インスタンスが得られます。 同じ行に複数のブレークポ
   イントを設定できるため、後者ではインスタンスのリストが得られます。

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

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

   deleteMe()

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

   enable()

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

   disable()

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

   bpformat()

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

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

      * 一時的なブレークポイントかどうか (del または keep)。

      * ファイルと行の位置。

      * 停止する条件。

      * 無視する回数。

      * ヒットした回数。

      Added in version 3.2.

   bpprint(out=None)

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

   "Breakpoint" インスタンスは以下の属性を持ちます:

   file

      "Breakpoint" のファイル名です。

   line

      "file" 内での "Breakpoint" の行番号です。

   temporary

      "(file, line)" の "Breakpoint" が一時的なものであれば "True" で
      す。

   cond

      "(file, line)" の "Breakpoint" を評価する条件です。

   funcname

      関数に入ったときに "Breakpoint" にヒットするかどうかを決める関数
      名です。

   enabled

      "Breakpoint" が有効なら "True" です。

   bpbynumber

      Numeric index for a single instance of a "Breakpoint".

   bplist

      Dictionary of "Breakpoint" instances indexed by ("file", "line")
      tuples.

   ignore

      "Breakpoint" を無視する回数です。

   hits

      "Breakpoint" にヒットした回数です。

class bdb.Bdb(skip=None, backend='settrace')

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

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

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

   *backend* 引数は "Bdb" が使うバックエンドを指定します。
   "'settrace'" または "'monitoring'" を指定できます。 "'settrace'" は
   "sys.settrace()" を使い、後方互換性が最も高いバックエンドです。
   "'monitoring'" は Python 3.12 で導入された "sys.monitoring" を使い
   ます。 使わないイベントを無効にできるため、大幅に効率がよくなる場合
   があります。 両方のバックエンドで同一のインターフェースを保つように
   していますが、いくつか違いがあります。 性能を高めるため、デバッガー
   の開発者には "'monitoring'" バックエンドの使用を推奨します。

   バージョン 3.1 で変更: *skip* パラメータが追加されました。

   バージョン 3.14 で変更: *backend* パラメーターが追加されました。

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

   canonic(filename)

      *filename* を正規化した形式で返します。

      実際のファイル名では、正規化された形式とは、OS に応じて "大文字
      ・小文字を正規化した" "絶対パス" です。 対話モードで生成される
      ""<stdin>"" のように山括弧で囲まれた *filename* は、そのまま返し
      ます。

   start_trace(self)

      トレースを開始します。 "'settrace'" バックエンドでは、
      "sys.settrace(self.trace_dispatch)" と同じです。

      Added in version 3.14.

   stop_trace(self)

      トレースを停止します。 "'settrace'" バックエンドでは、
      "sys.settrace(None)" と同じです。

      Added in version 3.14.

   reset()

      "botframe"、"stopframe"、"returnframe"、"quitting" 属性を、デバ
      ッグを開始できる値に設定します。

   trace_dispatch(frame, event, arg)

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

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

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

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

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

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

      各イベントに対応する専用の関数 (後述) を呼び出します。

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

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

   dispatch_line(frame)

      デバッガーが現在の行で停止するべきなら、"user_line()" メソッドを
      呼び出します (サブクラスでオーバーライドしてください)。
      "quitting" フラグが設定されていれば "BdbQuit" を送出します (この
      フラグは "user_line()" から設定できます)。 そのスコープ内のトレ
      ースを続けるために、"trace_dispatch()" メソッドへの参照を返しま
      す。

   dispatch_call(frame, arg)

      デバッガーがこの関数呼び出しで停止するべきなら、"user_call()" メ
      ソッドを呼び出します (サブクラスでオーバーライドしてください)。
      "quitting" フラグが設定されていれば "BdbQuit" を送出します (この
      フラグは "user_call()" から設定できます)。 そのスコープ内のトレ
      ースを続けるために、"trace_dispatch()" メソッドへの参照を返しま
      す。

   dispatch_return(frame, arg)

      デバッガーがこの関数からのリターンで停止するべきなら、
      "user_return()" メソッドを呼び出します (サブクラスでオーバーライ
      ドしてください)。 "quitting" フラグが設定されていれば "BdbQuit"
      を送出します (このフラグは "user_return()" から設定できます)。
      そのスコープ内のトレースを続けるために、"trace_dispatch()" メソ
      ッドへの参照を返します。

   dispatch_exception(frame, arg)

      デバッガーがこの例外で停止するべきなら、"user_exception()" メソ
      ッドを呼び出します (サブクラスでオーバーライドしてください)。
      "quitting" フラグが設定されていれば "BdbQuit" を送出します (この
      フラグは "user_exception()" から設定できます)。 そのスコープ内の
      トレースを続けるために、"trace_dispatch()" メソッドへの参照を返
      します。

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

   is_skipped_module(module_name)

      *module_name* がいずれかのスキップパターンにマッチすれば "True"
      を返します。

   stop_here(frame)

      Return "True" if *frame* is below the starting frame in the
      stack.

   break_here(frame)

      この行に実際に停止するブレークポイントがあれば "True" を返します
      。

      行または関数のブレークポイントが存在し、実際に停止するかどうかを
      確認します。 "effective()" の情報に基づいて、一時的なブレークポ
      イントを削除します。

   break_anywhere(frame)

      *frame* のファイル名に対してブレークポイントが 1 つでもあれば
      "True" を返します。

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

   user_call(frame, argument_list)

      呼び出された関数内で停止する可能性がある場合、"dispatch_call()"
      から呼び出されます。

      *argument_list* は現在使われておらず、常に "None" です。 後方互
      換性のために残されています。

   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, lineno=None)

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

   set_trace([frame])

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

      バージョン 3.13 で変更: "set_trace()" は、次のコード行が実行され
      るときではなく、即座にデバッガーに入るようになりました。

   set_continue()

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

   set_quit()

      "quitting" 属性を "True" に設定します。 これにより、次にいずれか
      の "dispatch_*()" メソッドを呼び出すと "BdbQuit" が送出されます
      。

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

   set_break(filename, lineno, temporary=False, cond=None, funcname=None)

      新しいブレークポイントを設定します。引数の *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" が上げられます。

      Added in version 3.2.

   get_break(filename, lineno)

      *filename* の *lineno* 行にブレークポイントがあれば "True" を返
      します。

   get_breaks(filename, lineno)

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

   get_file_breaks(filename)

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

   get_all_breaks()

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

   派生クラスやクライアントは、次のメソッドでイベントを無効にしたり再
   開したりして、性能を高められます。 これらのメソッドが機能するのは
   "'monitoring'" バックエンドを使う場合だけです。

   disable_current_event()

      次に "restart_events()" が呼び出されるまで、現在のイベントを無効
      にします。 デバッガーが現在の行を調べる必要がない場合に役立ちま
      す。

      Added in version 3.14.

   restart_events()

      無効にしたすべてのイベントを再開します。 この関数は "dispatch_*"
      メソッド内で、"user_*" メソッドの呼び出し後に自動的に呼び出され
      ます。 "dispatch_*" メソッドをオーバーライドしていなければ、ユー
      ザーとのやりとりのたびに、無効にしたイベントが再開されます。

      Added in version 3.14.

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

   get_stack(f, t)

      Return a list of (frame, lineno) tuples in a stack trace, and a
      size.

      The most recently called frame is last in the list. The size is
      the number of frames below the frame where the debugger was
      invoked.

   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)

   "Breakpoint" *b* の設定に基づき、この位置で停止するべきなら "True"
   を返します。

   行番号で設定されたブレークポイントでは、"b.line" と *frame* の行番
   号が同じかどうかを確認します。 "関数名" で設定された場合は、正しい
   *frame* (正しい関数) 内にいて、その関数の最初の実行可能な行にいるか
   どうかを確認する必要があります。

bdb.effective(file, line, frame)

   停止に使うブレークポイントとして "(active breakpoint, delete
   temporary flag)"、または "(None, None)" を返します。

   *active breakpoint* は、存在する ("file"、"line") に対応する
   "bplist" のうち、次の条件を満たす最初のエントリーです。 "有効" で、
   "checkfuncname()" が真を返し、"条件" が偽ではなく、"無視する回数"
   が正でもないことが条件です。 一時的なブレークポイントを削除すべきこ
   とを表す *flag* が "False" になるのは、"cond" を評価できない場合だ
   けです (この場合、"無視する回数" は考慮しません)。

   該当するエントリーがなければ "(None, None)" を返します。

bdb.set_trace()

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