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