モジュール 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; pdb.set_trace()
をデバッガで分析したい場所に挿入することです。そうすることで、コードの中の以下に続く文をステップ実行できます、そして、 c コマンドでデバッガを走らせることなく続けることもできます。
クラッシュしたプログラムを調べるための典型的な使い方は:
>>> 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 で追加.