26.2. pdb — Python デバッガ

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

モジュール 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 <module>
  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)

このモジュールは以下の関数を定義しています。それぞれが少しづつ違った方法でデバッガに入ります:

pdb.run(statement[, globals[, locals]])

デバッガに制御された状態で(文字列として与えられた) statement を実行します。デバッガプロンプトはあらゆるコードが実行される前に現れます。ブレークポイントを設定し、 continue とタイプできます。あるいは、文を step や next を使って一つづつ実行することができます (これらのコマンドはすべて下で説明します) 。オプションの globals と locals 引数はコードを実行する環境を指定します。デフォルトでは、モジュール __main__ の辞書が使われます。 (exec 文または eval() 組み込み関数の説明を参照してください。)

pdb.runeval(expression[, globals[, locals]])

デバッガの制御もとで(文字列として与えられる) expression を評価します。 runeval() がリターンしたとき、式の値を返します。その他の点では、この関数は run() と同様です。

pdb.runcall(function[, argument, ...])

function (関数またはメソッドオブジェクト、文字列ではありません) を与えられた引数とともに呼び出します。 runcall() から復帰するとき、関数呼び出しが返したものはなんでも返します。関数に入るとすぐにデバッガプロンプトが現れます。

pdb.set_trace()

スタックフレームを呼び出したところでデバッガに入ります。たとえコードが別の方法でデバッグされている最中でなくても (例えば、アサーションが失敗するとき)、これはプログラムの所定の場所でブレークポイントをハードコードするために役に立ちます。

pdb.post_mortem([traceback])

与えられた traceback オブジェクトの事後解析デバッギングに入ります。もし traceback が与えられなければ、その時点で取り扱っている例外のうちのひとつを使います。 (デフォルト動作をさせるには、例外を取り扱っている最中である必要があります。)

pdb.pm()

sys.last_traceback のトレースバックの事後解析デバッギングに入ります。

run* 関数と set_trace() は、 Pdb クラスをインスタンス化して同名のメソッドを実行することのエイリアス関数です。それ以上の機能を利用したい場合は、インスタンス化を自分で行わなければなりません:

class pdb.Pdb(completekey='tab', stdin=None, stdout=None, skip=None)

Pdb はデバッガクラスです。

completekey, stdin, stdout 引数は、基底にある cmd.Cmd クラスに渡されます。そちらの解説を参照してください。

skip 引数が指定された場合、 glob スタイルのモジュール名パターンの iterable (イテレート可能オブジェクト) でなければなりません。デバッガはこのパターンのどれかにマッチするモジュールに属するフレームにはステップインしません。 [1]

skip を使ってトレースする呼び出しの例:

import pdb; pdb.Pdb(skip=['django.*']).set_trace()

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

run(statement[, globals[, locals]])
runeval(expression[, globals[, locals]])
runcall(function[, argument, ...])
set_trace()

前述のこれら関数のドキュメントを参照してください。

26.3. デバッガコマンド

デバッガは以下のコマンドを認識します。ほとんどのコマンドは一文字または二文字に省略することができます。例えば、 h(elp) が意味するのは、ヘルプコマンドを入力するために h か help のどちらか一方を使うことができるということです ( が、 he や hel は使えず、また H や Help 、 HELP も使えません ) 。コマンドの引数は空白 ( スペースまたはタブ ) で区切られなければなりません。オプションの引数はコマンド構文の角括弧 ([]) の中に入れなければなりません。角括弧をタイプしてはいけません。コマンド構文における選択肢は垂直バー (|) で区切られます。

空行を入力すると入力された直前のコマンドを繰り返します。例外: 直前のコマンドが list コマンドならば、次の11行がリストされます。

デバッガが認識しないコマンドは Python 文とみなして、デバッグしているプログラムのコンテキストおいて実行されます。先頭にに感嘆符 (!) を付けることで Python 文であると明示することもできます。これはデバッグ中のプログラムを調査する強力な方法です。変数を変更したり関数を呼び出したりすることも可能です。このような文で例外が発生した場合には例外名が出力されますが、デバッガの状態は変化しません。

複数のコマンドを ;; で区切って一行で入力することができます。 (一つだけの ; は使われません。なぜなら、 Python パーサへ渡される行内の複数のコマンドのための分離記号だからです。) コマンドを分割するために何も知的なことはしていません。たとえ引用文字列の途中であっても、入力は最初の ;; 対で分割されます。

デバッガはエイリアスをサポートします。エイリアスはパラメータを持つことができ、調査中のコンテキストに対して人がある程度柔軟に対応できます。

ファイル .pdbrc はユーザのホームディレクトリか、またはカレントディレクトリにあります。それはまるでデバッガのプロンプトでタイプしたかのように読み込まれて実行されます。これは特にエイリアスのために便利です。両方のファイルが存在する場合、ホームディレクトリのものが最初に読まれ、そこに定義されているエイリアスはローカルファイルにより上書きされることがあります。

h(elp) [command]
引数なしでは、利用できるコマンドの一覧をプリントします。引数として command がある場合は、そのコマンドについてのヘルプをプリントします。 help pdb は完全ドキュメンテーションファイルを表示します。環境変数 PAGER が定義されているならば、代わりにファイルはそのコマンドへパイプされます。 command 引数が識別子でなければならないので、 ! コマンドについてのヘルプを得るためには help exec と入力しなければなりません。
w(here)
スタックの底にある最も新しいフレームと一緒にスタックトレースをプリントします。矢印はカレントフレームを指し、それがほとんどのコマンドのコンテキストを決定します。
d(own)
( より新しいフレームに向かって ) スタックトレース内でカレントフレームを1レベル下げます。
u(p)
( より古いフレームに向かって ) スタックトレース内でカレントフレームを1レベル上げます。
b(reak) [[filename:]lineno | function[, condition]]

lineno 引数がある場合は、現在のファイルのその場所にブレークポイントを設定します。 function 引数がある場合は、その関数の中の最初の実行可能文にブレークポイントを設定します。別のファイル ( まだロードされていないかもしれないもの ) のブレークポイントを指定するために、行番号はファイル名とコロンをともに先頭に付けられます。ファイルは sys.path にそって検索されます。各ブレークポイントは番号を割り当てられ、その番号を他のすべてのブレークポイントコマンドが参照することに注意してください。

第二引数を指定する場合、その値は式で、その評価値が真でなければブレークポイントは有効になりません。

引数なしの場合は、それぞれのブレークポイントに対して、そのブレークポイントに行き当たった回数、現在の通過カウント ( ignore count ) と、もしあれば関連条件を含めてすべてのブレークポイントをリストします。

tbreak [[filename:]lineno | function[, condition]]
一時的なブレークポイントで、最初にそこに達したときに自動的に取り除かれます。引数は break と同じです。
cl(ear) [filename:lineno | bpnumber [bpnumber …]]
filename:lineno 引数を与えると、その行にある全てのブレークポイントを解除します。スペースで区切られたブレークポイントナンバーのリストを与えると、それらのブレークポイントを解除します。引数なしの場合は、すべてのブレークポイントを解除します ( が、はじめに確認します ) 。
disable [bpnumber [bpnumber …]]
スペースで区切られたブレークポイントナンバーのリストとして与えられるブレークポイントを無効にします。ブレークポイントを無効にすると、プログラムの実行を止めることができなくなりますが、ブレークポイントの解除と違いブレークポイントのリストに残ったままになり、 (再び)有効にすることができます。
enable [bpnumber [bpnumber …]]
指定したブレークポイントを有効にします。
ignore bpnumber [count]
与えられたブレークポイントナンバーに通過カウントを設定します。 count が省略されると、通過カウントは 0 に設定されます。通過カウントがゼロになったとき、ブレークポイントが機能する状態になります。ゼロでないときは、そのブレークポイントが無効にされず、どんな関連条件も真に評価されていて、ブレークポイントに来るたびに count が減らされます。
condition bpnumber [condition]
condition はブレークポイントが取り上げられる前に真と評価されなければならない式です。 condition がない場合は、どんな既存の条件も取り除かれます。すなわち、ブレークポイントは無条件になります。
commands [bpnumber]

ブレークポイントナンバー 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 で追加.

s(tep)
現在の行を実行し、最初に実行可能なものがあらわれたときに (呼び出された関数の中か、現在の関数の次の行で) 停止します。
n(ext)
現在の関数の次の行に達するか、あるいは関数が返るまで実行を継続します。 ( next と step の差は step が呼び出された関数の内部で停止するのに対し、 next は呼び出された関数を ( ほぼ ) 全速力で実行し、現在の関数内の次の行で停止するだけです。)
unt(il)

行番号が現在行より大きくなるまで、もしくは、現在のフレームから戻るまで、実行を続けます。

バージョン 2.6 で追加.

r(eturn)
現在の関数が返るまで実行を継続します。
c(ont(inue))
ブレークポイントに出会うまで、実行を継続します。
j(ump) lineno

次に実行する行を指定します。最も底のフレーム中でのみ実行可能です。前に戻って実行したり、不要な部分をスキップして先の処理を実行する場合に使用します。

ジャンプには制限があり、例えば for ループの中には飛び込めませんし、 finally 節の外にも飛ぶ事ができません。

l(ist) [first[, last]]
現在のファイルのソースコードをリスト表示します。引数なしの場合は、現在の行の周囲を11行リストするか、または前のリストの続きを表示します。引数が一つある場合は、その行の周囲を11行表示します。引数が二つの場合は、与えられた範囲をリスト表示します。第二引数が第一引数より小さいときは、カウントと解釈されます。
a(rgs)
現在の関数の引数リストをプリントします。
p expression

現在のコンテキストにおいて expression を評価し、その値をプリントします。

注釈

print も使うことができますが、デバッガコマンドではありません — これは Python の print 文を実行します。

pp expression
pprint モジュールを使って例外の値が整形されることを除いて p コマンドと同様です。
alias [name [command]]

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
unalias name
指定したエイリアスを削除します。
[!]statement

現在のスタックフレームのコンテキストにおいて(一行の) statement を実行します。文の最初の語がデバッガコマンドと共通でない場合は、感嘆符を省略することができます。グローバル変数を設定するために、同じ行に global コマンドとともに代入コマンドの前に付けることができます。:

(Pdb) global list_options; list_options = ['-l']
(Pdb)
run [args …]

デバッグ中のプログラムを再実行します。もし引数が与えられると、 "shlex" で分割され、結果が新しい sys.argv として使われます。ヒストリー、ブレークポイント、アクション、そして、デバッガオプションは引き継がれます。 "restart" は "run" の別名です。

バージョン 2.6 で追加.

q(uit)
デバッガを終了します。実行しているプログラムは中断されます。

脚注

[1]フレームが属するモジュールは、そのフレームのグローバルの __name__ によって決定されます。