26.1. bdb — デバッガーフレームワーク

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

bdb モジュールは、ブレークポイントを設定したり、デバッガー経由で実行を管理するような、基本的なデバッガー機能を提供します。

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

exception bdb.BdbQuit

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

bdb モジュールは2つのクラスを定義しています:

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

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

ブレークポイントは bpbynumber という名前のリストで番号によりインデックスされ、 bplist により (file, line) の形でインデックスされます。 bpbynumber は Breakpoint クラスのインスタンスを指しています。一方 bplist は、同じ行に複数のブレークポイントが設定される場合があるので、インスタンスのリストを指しています。

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

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

deleteMe()

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

enable()

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

disable()

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

pprint([out])

このブレークポイントに関するすべての情報を表示します。

  • ブレークポイント番号。
  • テンポラリブレークポイントかどうか。
  • ファイル/行の位置。
  • ブレークする条件。
  • 次のN回無視されるか。
  • ヒットカウント。
class bdb.Bdb(skip=None)

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

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

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

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

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

canonic(filename)

標準化されたファイル名を取得するための補助関数。標準化されたファイル名とは、(大文字小文字を区別しないファイルシステムにおいて)大文字小文字を正規化し、絶対パスにしたものです。ファイル名が "<" と ">" で囲まれていた場合はそれを取り除いたものです。

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

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

stop_here(frame)

このメソッドは frame がコールスタック中で botframe よりも下にあるかチェックします。 botframe はデバッグを開始したフレームです。

break_here(frame)

このメソッドは、frame に属するファイル名と行に、あるいは、少なくとも現在の関数にブレークポイントがあるかどうかをチェックします。ブレークポイントがテンポラリブレークポイントだった場合、このメソッドはそのブレークポイントを削除します。

break_anywhere(frame)

このメソッドは、現在のフレームのファイル名の中にブレークポイントが存在するかどうかをチェックします。

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

user_call(frame, argument_list)

このメソッドは、呼ばれた関数の中でブレークする必要がある可能性がある場合に、 dispatch_call() から呼び出されます。

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)

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

set_trace([frame])

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

set_continue()

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

set_quit()

quitting 属性を True に設定します。これにより、次回の dispatch_*() メソッドのどれかの呼び出しで、 BdbQuit 例外を発生させます。

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

set_break(filename, lineno, temporary=0, 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_break(filename, lineno)

filename の lineno にブレークポイントが存在するかどうかをチェックします。

get_breaks(filename, lineno)

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

get_file_breaks(filename)

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

get_all_breaks()

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

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

get_stack(f, t)

与えられたフレームおよび上位(呼び出し側)と下位のすべてのフレームに対するレコードのリストと、上位フレームのサイズを得ます。

format_stack_entry(frame_lineno[, lprefix=': '])

(frame, lineno) で指定されたスタックエントリに関する次のような情報を持つ文字列を返します:

  • そのフレームを含むファイル名の標準形。
  • 関数名、もしくは "<lambda>"。
  • 入力された引数。
  • 戻り値。
  • (あれば)その行のコード。

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

run(cmd[, globals[, locals]])

exec 文を利用して文を実行しデバッグします。 globals はデフォルトでは __main__.__dict__ で、 locals はデフォルトでは globals です。

runeval(expr[, globals[, locals]])

eval() 関数を利用して式を実行しデバッグします。 globals と locals は run() と同じ意味です。

runctx(cmd, globals, locals)

後方互換性のためのメソッドです。 run() を使ってください。

runcall(func, *args, **kwds)

1つの関数呼び出しをデバッグし、その結果を返します。

最後に、このモジュールは以下の関数を提供しています:

bdb.checkfuncname(b, frame)

この場所でブレークする必要があるかどうかを、ブレークポイント b が設定された方法に依存する方法でチェックします。

ブレークポイントが行番号で設定されていた場合、この関数は b.line が、同じく引数として与えられた frame の中の行に一致するかどうかをチェックします。ブレークポイントが関数名で設定されていた場合、この関数は frame が指定された関数のものであるかどうかと、その関数の最初の行であるかどうかをチェックします。

bdb.effective(file, line, frame)

指定されたソースコード中の行に(有効な)ブレークポイントがあるかどうかを判断します。ブレークポイントと、テンポラリブレークポイントを削除して良いかどうかを示すフラグからなるタプルを返します。マッチするブレークポイントが存在しない場合は (None, None) を返します。

bdb.set_trace()

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