モジュール pdb はPythonプログラム用の対話的ソースコードデバッガを 定義します。(条件付き)ブレークポイントの設定やソース行レベルでのシング ルステップ実行、スタックフレームのインスペクション、ソースコードリスティ ングおよびいかなるスタックフレームのコンテキストにおける任意のPythonコー ドの評価をサポートしています。事後解析デバッギングもサポートし、プログ ラムの制御下で呼び出すことができます。
デバッガは拡張可能です — 実際にはクラス Pdb として定義されています。現在これについての ドキュメントはありませんが、ソースを読めば簡単に理解できます。拡張イン ターフェースはモジュール bdb (ドキュメントなし)と cmd を 使っています。
デバッガのプロンプトは (Pdb) です。デバッガに制御された状態でプロ グラムを実行するための典型的な使い方は:
>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
> <string>(0)?()
(Pdb) continue
> <string>(1)?()
(Pdb) continue
NameError: 'spam'
> <string>(1)?()
(Pdb)
他のスクリプトをデバッグするために、 pdb.py をスクリプトとして 呼び出すこともできますせます。例えば:
python -m pdb myscript.py
スクリプトとして pdb を起動すると、デバッグ中のプログラムが異常終了し た時に pdb が自動的に事後デバッグモードに入ります。事後デバッグ後 (ま たはプログラムの正常終了後) には、 pdb はプログラムを再起動します。自 動再起動を行った場合、 pdb の状態 (ブレークポイントなど) はそのまま維 持されるので、たいていの場合、プログラム終了時にデバッガも終了させるよ りも便利なはずです。
バージョン 2.4 で追加: 事後デバッグ後の再起動機能が追加されました.
クラッシュしたプログラムを調べるための典型的な使い方は:
>>> import pdb
>>> import mymodule
>>> mymodule.test()
Traceback (most recent call last):
File "<stdin>", line 1, in ?
File "./mymodule.py", line 4, in test
test2()
File "./mymodule.py", line 3, in test2
print spam
NameError: spam
>>> pdb.pm()
> ./mymodule.py(3)test2()
-> print spam
(Pdb)
モジュールは以下の関数を定義しています。それぞれが少しづつ違った方法で デバッガに入ります:
デバッガに制御された状態で(文字列として与えられた) statement を実 行します。デバッガプロンプトはあらゆるコードが実行される前に現れま す。ブレークポイントを設定し、 continue とタイプできます。ある いは、文を step や next を使って一つづつ実行することができ ます (これらのコマンドはすべて下で説明します) 。オプションの globals と locals 引数はコードを実行する環境を指定します。デフォ ルトでは、モジュール __main__ の辞書が使われます。 (exec 文または eval() 組み込み関数の説明を参照して ください。)
デバッガの制御もとで(文字列として与えられる) expression を評価し ます。 runeval() がリターンしたとき、式の値を返します。その他 の点では、この関数は run() と同様です。
function (関数またはメソッドオブジェクト、文字列ではありません)を 与えられた引数とともに呼び出します。 runcall() がリターンし たとき、関数呼び出しが返したものは何でも返します。デバッガプロンプ トは関数に入るとすぐに現れます。
スタックフレームを呼び出したところでデバッガに入ります。たとえコー ドが別の方法でデバッグされている最中でなくても(例えば、アサーション が失敗するとき)、これはプログラムの所定の場所でブレークポイントをハー ドコードするために役に立ちます。
与えられた traceback オブジェクトの事後解析デバッギングに入ります。 もし traceback が与えられなければ、その時点で取り扱っている例外の うちのひとつを使います。 (デフォルト動作をさせるには、例外を取り扱っ ている最中である必要があります。)
sys.last_traceback のトレースバックの事後解析デバッギングに入り ます。
デバッガは以下のコマンドを認識します。ほとんどのコマンドは一文字または 二文字に省略することができます。例えば、 h(elp) が意味するのは、ヘ ルプコマンドを入力するために h か help のどちらか一方を使うこ とができるということです ( が、 he や hel は使えず、また H や Help 、 HELP も使えません ) 。コマンドの引数は空白 ( スペー スまたはタブ ) で区切られなければなりません。オプションの引数はコマン ド構文の角括弧 ([]) の中に入れなければなりません。角括弧をタイプし てはいけません。コマンド構文における選択肢は垂直バー (|) で区切ら れます。
空行を入力すると入力された直前のコマンドを繰り返します。例外: 直前のコ マンドが list コマンドならば、次の11行がリストされます。
デバッガが認識しないコマンドは Python 文とみなして、デバッグしているプ ログラムのコンテキストおいて実行されます。 Python 文は感嘆符 (!) を前に付けることもできます。これはデバッグ中のプログラムを調査する強力 な方法です。変数を変更したり関数を呼び出したりすることさえ可能です。こ のような文で例外が発生した場合には例外名がプリントされますが、デバッガ の状態は変化しません。
複数のコマンドを ;; で区切って一行で入力することができます。 (一つ だけの ; は使われません。なぜなら、 Python パーサへ渡される行内の 複数のコマンドのための分離記号だからです。) コマンドを分割するために何 も知的なことはしていません。たとえ引用文字列の途中であっても、入力は最 初の ;; 対で分割されます。
デバッガはエイリアスをサポートします。エイリアスはパラメータを持つこと ができ、調査中のコンテキストに対して人がある程度柔軟に対応できます。
ファイル .pdbrc はユーザのホームディレクトリか、またはカレント ディレクトリにあります。それはまるでデバッガのプロンプトでタイプしたか のように読み込まれて実行されます。これは特にエイリアスのために便利です。 両方のファイルが存在する場合、ホームディレクトリのものが最初に読まれ、 そこに定義されているエイリアスはローカルファイルにより上書きされること があります。
lineno 引数がある場合は、現在のファイルのその場所にブレークポイン トを設定します。 function 引数がある場合は、その関数の中の最初の 実行可能文にブレークポイントを設定します。別のファイル ( まだロード されていないかもしれないもの ) のブレークポイントを指定するために、 行番号はファイル名とコロンをともに先頭に付けられます。 ファイルは sys.path にそって検索されます。各ブレークポイントは 番号を割り当てられ、その番号を他のすべてのブレークポイントコマンド が参照することに注意してください。
第二引数を指定する場合、その値は式で、その評価値が真でなければブレー クポイントは有効になりません。
引数なしの場合は、それぞれのブレークポイントに対して、そのブレーク ポイントに行き当たった回数、現在の通過カウント ( ignore count ) と、 もしあれば関連条件を含めてすべてのブレークポイントをリストします。
ブレークポイントナンバー bpnumber にコマンドのリストを指定します。 コマンドそのものはその後の行に続けます。 ‘end’ だけからなる行を入力 することでコマンド群の終わりを示します。例を挙げます:
(Pdb) commands 1
(com) print some_variable
(com) end
(Pdb)
ブレークポイントからコマンドを取り除くには、 commands のあとに end だけを続けます。つまり、コマンドを一つも指定しないようにします。
bpnumber 引数が指定されない場合、最後にセットされたブレークポイン トを参照することになります。
ブレークポイントコマンドはプログラムを走らせ直すのに使えます。ただ continue コマンドや step、その他実行を再開するコマンドを使えば良い のです。
実行を再開するコマンド ( 現在のところ continue, step, next, return, jump, quit とそれらの省略形 ) によって、コマンドリストは終了するも のと見なされます ( コマンドにすぐ end が続いているかのように ) 。と いうのも実行を再開すれば ( それが単純な next や step であっても ) 別のブレークポイントに到達するかもしれないからです。 そのブレークポイントにさらにコマンドリストがあれば、どちらのリスト を実行すべきか状況が曖昧になります。
コマンドリストの中で ‘silent’ コマンドを使うと、ブレークポイントで 停止したという通常のメッセージはプリントされません。この振る舞いは 特定のメッセージを出して実行を続けるようなブレークポイントでは望ま しいものでしょう。他のコマンドが何も画面出力をしなければ、そのブレー クポイントに到達したというサインを見ないことになります。
バージョン 2.5 で追加.
行番号が現在行より大きくなるまで、もしくは、現在のフレームから戻る まで、実行を続けます。
バージョン 2.6 で追加.
次に実行する行を指定します。最も底のフレーム中でのみ実行可能です。 前に戻って実行したり、不要な部分をスキップして先の処理を実行する場 合に使用します。
ジャンプには制限があり、例えば for ループの中には飛び込 めませんし、 finally 節の外にも飛ぶ事ができません。
name という名前の command を実行するエイリアスを作成します。コ マンドは引用符で囲まれていては いけません 。入れ替え可能なパラメー タは %1 、 %2 などで指し示され、さらに %* は全パラメー タに置き換えられます。コマンドが与えられなければ、 name に対する 現在のエイリアスを表示します。引数が与えられなければ、すべてのエイ リアスがリストされます。
エイリアスは入れ子になってもよく、 pdb プロンプトで合法的にタイプで きるどんなものでも含めることができます。内部 pdb コマンドをエイリア スによって上書きすることが できます 。そのとき、このようなコマン ドはエイリアスが取り除かれるまで隠されます。エイリアス化はコマンド 行の最初の語へ再帰的に適用されます。行の他のすべての語はそのままで す。
例として、二つの便利なエイリアスがあります (特に .pdbrc ファ イルに置かれたときに):
#Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k]
#Print instance variables in self
alias ps pi self
現在のスタックフレームのコンテキストにおいて(一行の) statement を 実行します。文の最初の語がデバッガコマンドと共通でない場合は、感嘆 符を省略することができます。グローバル変数を設定するために、同じ行 に global コマンドとともに代入コマンドの前に付けることができま す。:
(Pdb) global list_options; list_options = ['-l']
(Pdb)
デバッグ中のプログラムを再実行します。もし引数が与えられると、 “shlex” で分割され、結果が新しい sys.argv として使われます。ヒスト リー、ブレークポイント、アクション、そして、デバッガーオプションは 引き継がれます。 “restart” は “run” の別名です。
バージョン 2.6 で追加.