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.

バージョン 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)

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

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

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

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

以下の 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.

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() メソッドの参照を返します。

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

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.

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 が指定されなかった場合、デバッグは呼び出し元のフレームから開始します。

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 が上げられます。

バージョン 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)

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)

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 が設定された方法に依存する方法で、この場所でブレークする必要があれば真を返します。

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