
.. _debugger:

:mod:`pdb` --- Python デバッガ
==================================

.. module:: pdb
   :synopsis: 対話的インタプリタのためのPythonデバッガ。


.. index:: single: debugging

モジュール :mod:`pdb` はPythonプログラム用の対話的ソースコードデバッガを定義します。
(条件付き)ブレークポイントの設定やソース行レベルでのシングルステップ実行、
スタックフレームのインスペクション、ソースコードリスティングおよびいかなるスタックフレームのコンテキストにおける任意のPythonコードの評価をサポートしています。
事後解析デバッギングもサポートし、プログラムの制御下で呼び出すことができます。

.. index::
   single: Pdb (class in pdb)
   module: bdb
   module: cmd

デバッガは拡張可能です ---
実際にはクラス :class:`Pdb` として定義されています。
現在これについてのドキュメントはありませんが、ソースを読めば簡単に理解できます。
拡張インターフェースはモジュール :mod:`bdb` と :mod:`cmd` を使っています。

デバッガのプロンプトは ``(Pdb)`` です。
デバッガに制御された状態でプログラムを実行するための典型的な使い方は::

   >>> import pdb
   >>> import mymodule
   >>> pdb.run('mymodule.test()')
   > <string>(0)?()
   (Pdb) continue
   > <string>(1)?()
   (Pdb) continue
   NameError: 'spam'
   > <string>(1)?()
   (Pdb)

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

   python -m pdb myscript.py

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

.. versionadded:: 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)

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


.. function:: run(statement[, globals[, locals]])

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


.. function:: runeval(expression[, globals[, locals]])

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


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

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


.. function:: set_trace()

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


.. function:: post_mortem([traceback])

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


.. function:: pm()

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


.. _debugger-commands:

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

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

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

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

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

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

.. index::
   pair: .pdbrc; file
   triple: debugger; configuration; file

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

h(elp) [*command*]
   引数なしでは、利用できるコマンドの一覧をプリントします。
   引数として *command* がある場合は、そのコマンドについてのヘルプをプリントします。
   ``help pdb`` は完全ドキュメンテーションファイルを表示します。
   環境変数 :envvar:`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) [*bpnumber* [*bpnumber ...*]]
   スペースで区切られたブレークポイントナンバーのリストを与えると、
   それらのブレークポイントを解除します。
   引数なしの場合は、すべてのブレークポイントを解除します
   ( が、はじめに確認します ) 。

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

   .. versionadded:: 2.5

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

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

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

   .. versionadded:: 2.6

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

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

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

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

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

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

p *expression*
   現在のコンテキストにおいて *expression* を評価し、その値をプリントします。
   (注意: ``print`` も使うことができますが、デバッガコマンドではありません
   --- これは Python の :keyword:`print` 文を実行します。)

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

alias [*name* [command]]
   *name* という名前の *command* を実行するエイリアスを作成します。
   コマンドは引用符で囲まれていては *いけません* 。
   入れ替え可能なパラメータは ``%1`` 、 ``%2`` などで指し示され、
   さらに ``%*`` は全パラメータに置き換えられます。
   コマンドが与えられなければ、 *name* に対する現在のエイリアスを表示します。
   引数が与えられなければ、すべてのエイリアスがリストされます。

   エイリアスは入れ子になってもよく、
   pdb プロンプトで合法的にタイプできるどんなものでも含めることができます。
   内部 pdb コマンドをエイリアスによって上書きすることが *できます* 。
   そのとき、このようなコマンドはエイリアスが取り除かれるまで隠されます。
   エイリアス化はコマンド行の最初の語へ再帰的に適用されます。
   行の他のすべての語はそのままです。

   例として、二つの便利なエイリアスがあります
   (特に :file:`.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" の別名です。

   .. versionadded:: 2.6

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