"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)

バージョン 3.3 で変更: "readline" モジュールによるコマンドおよびコマン
ド引数のタブ補完が利用できます。たとえば、"p" コマンドの引数では現在の
グローバルおよびローカル名が候補として表示されます。

他のスクリプトをデバッグするために、 "pdb.py" をスクリプトとして呼び出
すこともできます。例えば:

   python3 -m pdb myscript.py

スクリプトとして pdb を起動すると、デバッグ中のプログラムが異常終了し
たときに pdb が自動的に事後デバッグモードに入ります。事後デバッグ後 (
またはプログラムの正常終了後)、pdb はプログラムを再起動します。自動再
起動を行った場合、pdb の状態 (ブレークポイントなど) はそのまま維持され
るので、たいていの場合、プログラム終了時にデバッガーも終了させるよりも
便利なはずです。

バージョン 3.2 で追加: "pdb.py" は "-c" オプションを受け付けるようにな
りました。このオプションで ".pdbrc" ファイルが与えられると、ファイル内
のコマンドを実行します。デバッガコマンド を参照してください。

バージョン 3.7 で追加: "pdb.py" now accepts a "-m" option that execute
modules similar to the way "python3 -m" does. As with a script, the
debugger will pause execution just before the first line of the
module.

実行するプログラムをデバッガで分析する典型的な使い方は:

   import pdb; pdb.set_trace()

これでコードの中のその後に続く文をステップ実行できます。そして
"continue" コマンドでデバッガーを停止し処理を続行できます。

バージョン 3.7 で追加: The built-in "breakpoint()", when called with
defaults, can be used instead of "import pdb; pdb.set_trace()".

クラッシュしたプログラムを調べるための典型的な使い方は以下のようになり
ます:

   >>> 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=None, locals=None)

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

pdb.runeval(expression, globals=None, locals=None)

   デバッガーに制御された状態で (文字列またはコードオブジェクトとして
   与えられる) *expression* を評価します。"runeval()" から復帰するとき
   、式の値を返します。その他の点では、この関数は "run()" と同様です。

pdb.runcall(function, *args, **kwds)

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

pdb.set_trace(*, header=None)

   Enter the debugger at the calling stack frame.  This is useful to
   hard-code a breakpoint at a given point in a program, even if the
   code is not otherwise being debugged (e.g. when an assertion
   fails).  If given, *header* is printed to the console just before
   debugging begins.

   バージョン 3.7 で変更: *header* キーワード専用引数。

pdb.post_mortem(traceback=None)

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

pdb.pm()

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

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

class pdb.Pdb(completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True)

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

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

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

   デフォルトでは、Pdb は "continue" コマンドが投入されると、(ユーザー
   がコンソールから "Ctrl-C" を押したときに送られる) SIGINT シグナル用
   ハンドラーを設定します。これにより "Ctrl-C" を押すことで再度デバッ
   ガーを起動することができます。Pdb に SIGINT ハンドラーを変更させた
   くない場合は *nosigint* を true に設定してください。

   *readrc* 引数はデフォルトでは真で、 Pdb が .pdbrc ファイルをファイ
   ルシステムから読み込むかどうかを制御します。

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

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

   引数無しで 監査イベント "pdb.Pdb" を送出します。

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

   バージョン 3.2 で追加: *nosigint* 引数が追加されました。以前は Pdb
   が SIGINT ハンドラーを設定することはありませんでした。

   バージョン 3.6 で変更: *readrc* 引数。

   run(statement, globals=None, locals=None)
   runeval(expression, globals=None, locals=None)
   runcall(function, *args, **kwds)
   set_trace()

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


デバッガコマンド
================

デバッガーに認識されるコマンドは以下に一覧されています。たいていのコマ
ンドは以下のように 1、2 文字に省略できます。例えば "h(elp)" は "h" か
"help" がで help コマンドを呼び出すことを意味します (ただし "he",
"hel", "H", "Help", "HELP" は使用できません)。コマンドの引数はホワイト
スペース (スペースかタブ) で区切ってください。コマンド構文として任意の
引数は大括弧 ("[]") で括られています (実際に大括弧はタイプしないでくだ
さい)。いくつかから選択できる引数は縦線 ("|") で分割されて記述されてい
ます。

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

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

デバッガーは エイリアス をサポートしています。エイリアスはデバッグ中の
コンテキストに適用可能な一定レベルのパラメータを保持することができます
。

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

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

バージョン 3.2 で変更: ".pdbrc" に "continue" や "next" のようなデバッ
グを続行するコマンドが使用できるようになりました。以前はこのようなコマ
ンドは無視されていました。

h(elp) [command]

   引数を指定しない場合、利用できるコマンドの一覧が表示されます。引数
   として *command* が与えられた場合、そのコマンドのヘルプが表示されま
   す。"help pdb" で完全なドキュメント ("pdb" モジュールの doctring)
   が表示されます。*command* 引数は識別子でなければならないため、"!"
   コマンドのヘルプを表示するには "help exec" と入力します。

w(here)

   スタックの底にある最も新しいフレームと一緒にスタックトレースをプリ
   ントします。矢印はカレントフレームを指し、それがほとんどのコマンド
   のコンテキストを決定します。

d(own) [count]

   スタックフレーム内で現在のフレームを *count* レベル (デフォルトは
   1) 新しいフレーム方向に移動します。

u(p) [count]

   スタックフレーム内で現在のフレームを *count* レベル (デフォルトは
   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 ...]]

   ブレークポイント番号 *bpnumber* のブレークポイントを無効にします。
   ブレークポイントを無効にすると、プログラムの実行を止めることができ
   なくなりますが、ブレークポイントの解除と違いブレークポイントのリス
   トに残っており、(再び) 有効にできます。

enable [bpnumber [bpnumber ...]]

   指定したブレークポイントを有効にします。

ignore bpnumber [count]

   与えられたブレークポイントナンバーに通過カウントを設定します。count
   が省略されると、通過カウントは 0 に設定されます。通過カウントがゼロ
   になったとき、ブレークポイントが機能する状態になります。ゼロでない
   ときは、そのブレークポイントが無効にされず、どんな関連条件も真に評
   価されていて、ブレークポイントに来るたびに count が減らされます。

condition bpnumber [condition]

   ブレークポイントに新しい *condition* を設定します。*condition* はブ
   レークポイントを制御する条件式で、この式が真を返す場合のみブレーク
   ポイントが有効になります。*condition* を指定しないと既存の条件が除
   去されます; ブレークポイントは常に有効になります。

commands [bpnumber]

   ブレークポイントナンバー *bpnumber* にコマンドのリストを指定します
   。コマンドそのものはその後の行に続けます。"end" だけからなる行を入
   力することでコマンド群の終わりを示します。例を挙げます:

      (Pdb) commands 1
      (com) p some_variable
      (com) end
      (Pdb)

   ブレークポイントからコマンドを取り除くには、 "commands" のあとに
   "end" だけを続けます。つまり、コマンドを一つも指定しないようにしま
   す。

   *bpnumber* 引数を指定しない場合、"commands" は最後にセットしたブレ
   ークポイントを参照します。

   ブレークポイントコマンドはプログラムを走らせ直すのに使えます。単に
   "continue" コマンドや >>:pdb:`step`<<、その他実行を再開するコマンド
   を使えば良いのです。

   実行を再開するコマンド (現在のところ >>:pdb:`continue`<<,
   >>:pdb:`step`<<, >>:pdb:`next`<<, >>:pdb:`return`<<,
   >>:pdb:`jump`<<, >>:pdb:`quit`<< とそれらの省略形) によって、コマン
   ドリストは終了するものと見なされます (コマンドにすぐ end が続いてい
   るかのように)。というのも実行を再開すれば (それが単純な next や
   step であっても) 別のブレークポイントに到達するかもしれないからです
   。そのブレークポイントにさらにコマンドリストがあれば、どちらのリス
   トを実行すべきか状況が曖昧になります。

   コマンドリストの中で 'silent' コマンドを使うと、ブレークポイントで
   停止したという通常のメッセージはプリントされません。この振る舞いは
   特定のメッセージを出して実行を続けるようなブレークポイントでは望ま
   しいものでしょう。他のコマンドが何も画面出力をしなければ、そのブレ
   ークポイントに到達したというサインを見ないことになります。

s(tep)

   現在の行を実行し、最初に実行可能なものがあらわれたときに (呼び出さ
   れた関数の中か、現在の関数の次の行で) 停止します。

n(ext)

   現在の関数の次の行に達するか、あるいは関数が返るまで実行を継続しま
   す。 ("next" と "step" の差は "step" が呼び出された関数の内部で停止
   するのに対し、 "next" は呼び出された関数を (ほぼ) 全速力で実行し、
   現在の関数内の次の行で停止するだけです。)

unt(il) [lineno]

   引数なしだと、現在の行から 1 行先まで実行します。

   行数を指定すると、指定行数かそれ以上に達するまで実行します。どちら
   にしても現在のフレームが返ってきた時点で停止します。

   バージョン 3.2 で変更: 明示的に行数指定ができるようになりました。

r(eturn)

   現在の関数が返るまで実行を継続します。

c(ont(inue))

   ブレークポイントに出会うまで、実行を継続します。

j(ump) lineno

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

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

l(ist) [first[, last]]

   現在のファイルのソースコードを表示します。引数を指定しないと、現在
   の行の前後 11 行分を表示するか、直前の表示を続行します。引数に "."
   を指定すると、現在の行の前後 11 行分を表示します。数値を 1 個指定す
   ると、その行番号の前後 11 行分を表示します。数値を 2 個指定すると、
   開始行と最終行として表示します; 2 個めの引数が 1 個め未満だった場合
   、1 個目を開始行、2 個めを開始行からの行数とみなします。

   現在のフレーム内の現在の行は "->" で表示されます。例外をデバッグ中
   の場合、例外が発生または伝搬した行は、それが現在の行とは異なるとき
   ">>" で表示されます。

   バージョン 3.2 で追加: ">>" マーカー。

ll | longlist

   現在の関数またはフレームの全ソースコードを表示します。注目する行は
   "list" と同じようにマーカーがつきます。

   バージョン 3.2 で追加.

a(rgs)

   現在の関数の引数リストをプリントします。

p expression

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

   注釈:

     "print()" も使えますが、これはデバッガーコマンドではありません
     --- これは Python の関数 "print()" が実行されます。

pp expression

   "p" コマンドに似ていますが、式の値以外は "pprint" モジュールを使用
   して "pretty-print" されます。

whatis expression

   式の型を表示します。

source expression

   与えられたオブジェクトのソースコードの取得を試み、可能であれば表示
   します。

   バージョン 3.2 で追加.

display [expression]

   式の値が変更されていれば表示します。毎回実行は現在のフレームで停止
   します。

   式を指定しない場合、現在のフレームのすべての式を表示します。

   バージョン 3.2 で追加.

undisplay [expression]

   現在のフレーム内で式をこれ以上表示しないようにします。式を指定しな
   い場合、現在のフレームで display 指定されている式を全てクリアします
   。

   バージョン 3.2 で追加.

interact

   対話型インタープリターを ("code" モジュールを使って) 開始します。グ
   ローバル名前空間には現在のスコープで見つかったすべてのグローバルお
   よびローカル名が含まれます。

   バージョン 3.2 で追加.

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 ...]
restart [args ...]

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

q(uit)

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

debug code

   Enter a recursive debugger that steps through the code argument
   (which is an arbitrary expression or statement to be executed in
   the current environment).

retval

   Print the return value for the last return of a function.

-[ 脚注 ]-

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