
.. _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
   >>> 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)
   デバッガを終了します。実行しているプログラムは中断されます。
