# `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)` の形でインデックスされます。 `bpbynumber` は `Breakpoint` クラスのインスタンスを指しています。一方 `bplist` は、同じ行に複数のブレークポイントが設定される場合があるので、インスタンスのリストを指しています。

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

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

  deleteMe()

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

  enable()

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

  disable()

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

  bpformat()

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

    - Breakpoint number.

    - Temporary status (del or keep).

    - File/line position.

    - Break condition.

    - Number of times to ignore.

    - Number of times hit.

    Added in version 3.2.

  bpprint(out=None)

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

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

  file

    File name of the `Breakpoint`.

  line

    Line number of the `Breakpoint` within `file`.

  temporary

    `True` if a `Breakpoint` at (file, line) is temporary.

  cond

    Condition for evaluating a `Breakpoint` at (file, line).

  funcname

    Function name that defines whether a `Breakpoint` is hit upon entering the function.

  enabled

    `True` if `Breakpoint` is enabled.

  bpbynumber

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

  bplist

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

  ignore

    Number of times to ignore a `Breakpoint`.

  hits

    Count of the number of times a `Breakpoint` has been hit.

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

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

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

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

  The backend argument specifies the backend to use for `Bdb`. It can be either `'settrace'` or `'monitoring'`. `'settrace'` uses `sys.settrace()` which has the best backward compatibility. The `'monitoring'` backend uses the new `sys.monitoring` that was introduced in Python 3.12, which can be much more efficient because it can disable unused events. We are trying to keep the exact interfaces for both backends, but there are some differences. The debugger developers are encouraged to use the `'monitoring'` backend to achieve better performance.

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

  バージョン 3.14 で変更: Added the backend parameter.

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

  canonic(filename)

    Return canonical form of filename.

    For real file names, the canonical form is an operating-system-dependent, `case-normalized` `absolute path`. A filename with angle brackets, such as `"<stdin>"` generated in interactive mode, is returned unchanged.

  start_trace(self)

    Start tracing. For `'settrace'` backend, this method is equivalent to `sys.settrace(self.trace_dispatch)`

    Added in version 3.14.

  stop_trace(self)

    Stop tracing. For `'settrace'` backend, this method is equivalent to `sys.settrace(None)`

    Added in version 3.14.

  reset()

    Set the `botframe`, `stopframe`, `returnframe` and `quitting` attributes with values ready to start debugging.

  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)

    If the debugger should stop on the current line, invoke the `user_line()` method (which should be overridden in subclasses). Raise a `BdbQuit` exception if the `quitting` flag is set (which can be set from `user_line()`). Return a reference to the `trace_dispatch()` method for further tracing in that scope.

  dispatch_call(frame, arg)

    If the debugger should stop on this function call, invoke the `user_call()` method (which should be overridden in subclasses). Raise a `BdbQuit` exception if the `quitting` flag is set (which can be set from `user_call()`). Return a reference to the `trace_dispatch()` method for further tracing in that scope.

  dispatch_return(frame, arg)

    If the debugger should stop on this function return, invoke the `user_return()` method (which should be overridden in subclasses). Raise a `BdbQuit` exception if the `quitting` flag is set (which can be set from `user_return()`). Return a reference to the `trace_dispatch()` method for further tracing in that scope.

  dispatch_exception(frame, arg)

    If the debugger should stop at this exception, invokes the `user_exception()` method (which should be overridden in subclasses). Raise a `BdbQuit` exception if the `quitting` flag is set (which can be set from `user_exception()`). Return a reference to the `trace_dispatch()` method for further tracing in that scope.

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

  is_skipped_line(module_name)

    Return `True` if module_name matches any skip pattern.

  stop_here(frame)

    Return `True` if frame is below the starting frame in the stack.

  break_here(frame)

    Return `True` if there is an effective breakpoint for this line.

    Check whether a line or function breakpoint exists and is in effect. Delete temporary breakpoints based on information from `effective()`.

  break_anywhere(frame)

    Return `True` if any breakpoint exists for frame's filename.

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

  user_call(frame, argument_list)

    Called from `dispatch_call()` if a break might stop inside the called function.

    argument_list is not used anymore and will always be `None`. The argument is kept for backwards compatibility.

  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()` will enter the debugger immediately, rather than on the next line of code to be executed.

  set_continue()

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

  set_quit()

    Set the `quitting` attribute to `True`. This raises `BdbQuit` in the next call to one of the `dispatch_*()` methods.

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

    Return `True` if there is a breakpoint for lineno in filename.

  get_breaks(filename, lineno)

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

  get_file_breaks(filename)

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

  get_all_breaks()

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

  Derived classes and clients can call the following methods to disable and restart events to achieve better performance. These methods only work when using the `'monitoring'` backend.

  disable_current_event()

    Disable the current event until the next time `restart_events()` is called. This is helpful when the debugger is not interested in the current line.

    Added in version 3.14.

  restart_events()

    Restart all the disabled events. This function is automatically called in `dispatch_*` methods after `user_*` methods are called. If the `dispatch_*` methods are not overridden, the disabled events will be restarted after each user interaction.

    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=': ')

    Return a string with information about a stack entry, which is a `(frame, lineno)` tuple. The return string contains:

    - The canonical filename which contains the frame.

    - 関数名もしくは `"<lambda>"`。

    - 入力された引数。

    - 戻り値。

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

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

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

    Debug a statement executed via the `exec()` function. globals defaults to `__main__.__dict__`, locals defaults to 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)

  Return `True` if we should break here, depending on the way the `Breakpoint` b was set.

  If it was set via line number, it checks if `b.line` is the same as the one in frame. If the breakpoint was set via `function name`, we have to check we are in the right frame (the right function) and if we are on its first executable line.

bdb.effective(file, line, frame)

  Return `(active breakpoint, delete temporary flag)` or `(None, None)` as the breakpoint to act upon.

  The active breakpoint is the first entry in `bplist` for the (`file`, `line`) (which must exist) that is `enabled`, for which `checkfuncname()` is true, and that has neither a false `condition` nor positive `ignore` count. The flag, meaning that a temporary breakpoint should be deleted, is `False` only when the `cond` cannot be evaluated (in which case, `ignore` count is ignored).

  If no such entry exists, then `(None, None)` is returned.

bdb.set_trace()

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