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__" によって決定されます。
