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": 例外が発生しました。

For all the events, specialized functions (see below) are called.

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 クラスのインスタンスを使って、呼び出し元のフレームからデバッグを開始します。