"bdb" --- Debugger framework
****************************

**ソースコード:** Lib/bdb.py

======================================================================

"bdb" モジュールは、ブレークポイントを設定したり、デバッガー経由で実行
を管理するような、基本的なデバッガー機能を提供します。

以下の例外が定義されています:

exception bdb.BdbQuit

   "Bdb" クラスが、デバッガーを終了させるために投げる例外。

"bdb" モジュールは2つのクラスを定義しています:

class bdb.Breakpoint(self, file, line, temporary=False, cond=None, funcname=None)

   このクラスはテンポラリブレークポイント、無視するカウント、無効化と
   再有効化、条件付きブレークポイントを実装しています。

   ブレークポイントは "bpbynumber" という名前のリストで番号によりイン
   デックスされ、 "bplist" により "(file, line)" の形でインデックスさ
   れます。 "bpbynumber" は "Breakpoint" クラスのインスタンスを指して
   います。一方 "bplist" は、同じ行に複数のブレークポイントが設定され
   る場合があるので、インスタンスのリストを指しています。

   ブレークポイントを作るとき、関連付けられる "ファイル名" は正規化さ
   れていなければなりません。"funcname" が定義されると、ブレークポイン
   トの "ヒット" はその関数の最初の行が実行されたときにカウントされま
   す。"条件付き" ブレークポイントは毎回 "ヒット" をカウントします。

   "Breakpoint" インスタンスは以下のメソッドを持ちます:

   deleteMe()

      このブレークポイントをファイル/行に関連付けられたリストから削除
      します。このブレークポイントがその行に設定された最後のブレークポ
      イントだった場合、そのファイル/行に対するエントリ自体を削除しま
      す。

   enable()

      このブレークポイントを有効にします。

   disable()

      このブレークポイントを無効にします。

   bpformat()

      ブレークポイントに関する情報を持つ文字列をフォーマットして返しま
      す:

      * Breakpoint number.

      * Temporary status (del or keep).

      * File/line position.

      * Break condition.

      * Number of times to ignore.

      * Number of times hit.

      バージョン 3.2 で追加.

   bpprint(out=None)

      ファイル *out* に、またはそれが "None" の場合は標準出力に、
      "bpformat()" の出力を表示する。

   "Breakpoint" インスタンスは以下の属性を持ちます:

   file

      File name of the "Breakpoint".

   line

      Line number of the "Breakpoint" within "file".

   temporary

      True if a "Breakpoint" at (file, line) is temporary.

   cond

      Condition for evaluating a "Breakpoint" at (file, line).

   funcname

      Function name that defines whether a "Breakpoint" is hit upon
      entering the function.

   enabled

      True if "Breakpoint" is enabled.

   bpbynumber

      Numeric index for a single instance of a "Breakpoint".

   bplist

      Dictionary of "Breakpoint" instances indexed by ("file", "line")
      tuples.

   ignore

      Number of times to ignore a "Breakpoint".

   hits

      Count of the number of times a "Breakpoint" has been hit.

class bdb.Bdb(skip=None)

   "Bdb" クラスは一般的なPythonデバッガーの基本クラスとして振舞います
   。

   このクラスはトレース機能の詳細を扱います。ユーザーとのインタラクシ
   ョンは、派生クラスが実装するべきです。標準ライブラリのデバッガクラ
   ス ("pdb.Pdb") がその利用例です。

   *skip* 引数は、もし与えられたならグロブ形式のモジュール名パターンの
   iterable でなければなりません。デバッガはこれらのパターンのどれかに
   マッチするモジュールで発生したフレームにステップインしなくなります
   。フレームが特定のモジュールで発生したかどうかは、フレームのグロー
   バル変数の "__name__" によって決定されます。

   バージョン 3.1 で変更: *skip* パラメータが追加されました。

   以下の "Bdb" のメソッドは、通常オーバーライドする必要はありません。

   canonic(filename)

      Return canonical form of *filename*.

      For real file names, the canonical form is an operating-system-
      dependent, "case-normalized" "absolute path". A *filename* with
      angle brackets, such as ""<stdin>"" generated in interactive
      mode, is returned unchanged.

   reset()

      Set the "botframe", "stopframe", "returnframe" and "quitting"
      attributes with values ready to start debugging.

   trace_dispatch(frame, event, arg)

      この関数は、デバッグされているフレームのトレース関数としてインス
      トールされます。戻り値は新しいトレース関数(殆どの場合はこの関数
      自身)です。

      デフォルトの実装は、実行しようとしている *event* (文字列として渡
      されます) の種類に基づいてフレームのディスパッチ方法を決定します
      。*event* は次のうちのどれかです:

      * ""line"": 新しい行を実行しようとしています。

      * ""call"": 関数が呼び出されているか、別のコードブロックに入りま
        す。

      * ""return"": 関数か別のコードブロックからreturnしようとしていま
        す。

      * ""exception"": 例外が発生しました。

      * ""c_call"": C関数を呼び出そうとしています。

      * ""c_return"": C関数からreturnしました。

      * ""c_exception"": C関数が例外を発生させました。

      Pythonのイベントに対しては、以下の専用の関数群が呼ばれます。Cの
      イベントに対しては何もしません。

      *arg* 引数は以前のイベントに依存します。

      トレース関数についてのより詳しい情報は、 "sys.settrace()" のドキ
      ュメントを参照してください。コードとフレームオブジェクトについて
      のより詳しい情報は、 標準型の階層 を参照してください。

   dispatch_line(frame)

      If the debugger should stop on the current line, invoke the
      "user_line()" method (which should be overridden in subclasses).
      Raise a "BdbQuit" exception if the "quitting" flag is set (which
      can be set from "user_line()").  Return a reference to the
      "trace_dispatch()" method for further tracing in that scope.

   dispatch_call(frame, arg)

      If the debugger should stop on this function call, invoke the
      "user_call()" method (which should be overridden in subclasses).
      Raise a "BdbQuit" exception if the "quitting" flag is set (which
      can be set from "user_call()").  Return a reference to the
      "trace_dispatch()" method for further tracing in that scope.

   dispatch_return(frame, arg)

      If the debugger should stop on this function return, invoke the
      "user_return()" method (which should be overridden in
      subclasses). Raise a "BdbQuit" exception if the "quitting" flag
      is set (which can be set from "user_return()").  Return a
      reference to the "trace_dispatch()" method for further tracing
      in that scope.

   dispatch_exception(frame, arg)

      If the debugger should stop at this exception, invokes the
      "user_exception()" method (which should be overridden in
      subclasses). Raise a "BdbQuit" exception if the "quitting" flag
      is set (which can be set from "user_exception()").  Return a
      reference to the "trace_dispatch()" method for further tracing
      in that scope.

   通常、継承クラスは以下のメソッド群をオーバーライドしません。しかし
   、停止やブレークポイント機能を再定義したい場合には、オーバーライド
   することもあります。

   is_skipped_line(module_name)

      Return True if *module_name* matches any skip pattern.

   stop_here(frame)

      Return True if *frame* is below the starting frame in the stack.

   break_here(frame)

      Return True if there is an effective breakpoint for this line.

      Check whether a line or function breakpoint exists and is in
      effect.  Delete temporary breakpoints based on information from
      "effective()".

   break_anywhere(frame)

      Return True if any breakpoint exists for *frame*'s filename.

   継承クラスはデバッガー操作をするために以下のメソッド群をオーバーラ
   イドするべきです。

   user_call(frame, argument_list)

      Called from "dispatch_call()" if a break might stop inside the
      called function.

   user_line(frame)

      "stop_here()" か "break_here()" が "True" を返したときに、
      "dispatch_line()" から呼び出されます。

   user_return(frame, return_value)

      "stop_here()" が "True" を返したときに、 "dispatch_return()" か
      ら呼び出されます。

   user_exception(frame, exc_info)

      "stop_here()" が "True" を返したときに、 "dispatch_exception()"
      から呼び出されます。

   do_clear(arg)

      ブレークポイントがテンポラリブレークポイントだったときに、それを
      どう削除するかを決定します。

      継承クラスはこのメソッドを実装しなければなりません。

   継承クラスとクライアントは、ステップ状態に影響を及ぼすために以下の
   メソッドを呼び出すことができます。

   set_step()

      コードの次の行でストップします。

   set_next(frame)

      与えられたフレームかそれより下(のフレーム)にある、次の行でストッ
      プします。

   set_return(frame)

      指定されたフレームから抜けるときにストップします。

   set_until(frame, lineno=None)

      現在の行番号よりも大きい *lineno* に到達したとき、あるいは、現在
      のフレームから戻るときにストップします。

   set_trace([frame])

      *frame* からデバッグを開始します。*frame* が指定されなかった場合
      、デバッグは呼び出し元のフレームから開始します。

   set_continue()

      ブレークポイントに到達するか終了したときにストップします。もしブ
      レークポイントが1つも無い場合、システムのトレース関数を "None"
      に設定します。

   set_quit()

      Set the "quitting" attribute to "True".  This raises "BdbQuit"
      in the next call to one of the "dispatch_*()" methods.

   継承クラスとクライアントは以下のメソッドをブレークポイント操作に利
   用できます。これらのメソッドは、何か悪いことがあればエラーメッセー
   ジを含む文字列を返し、すべてが順調であれば "None" を返します。

   set_break(filename, lineno, temporary=False, cond=None, funcname=None)

      新しいブレークポイントを設定します。引数の *lineno* 行が
      *filename* に存在しない場合、エラーメッセージを返します。
      *filename* は、 "canonic()" メソッドで説明されているような、標準
      形である必要があります。

   clear_break(filename, lineno)

      *filename* の *lineno* 行にあるブレークポイントを削除します。も
      しブレークポイントが無かった場合、エラーメッセージを返します。

   clear_bpbynumber(arg)

      "Breakpoint.bpbynumber" の中で *arg* のインデックスを持つブレー
      クポイントを削除します。 *arg* が数値でないか範囲外の場合、エラ
      ーメッセージを返します。

   clear_all_file_breaks(filename)

      *filename* にあるすべてのブレークポイントを削除します。もしブレ
      ークポイントが無かった場合、エラーメッセージを返します。

   clear_all_breaks()

      存在するすべてのブレークポイントを削除します。もしブレークポイン
      トが無かった場合、エラーメッセージを返します。

   get_bpbynumber(arg)

      与えられた数値によって指定されるブレークポイントを返します。
      *arg* が文字列なら数値に変換されます。 *arg* が非数値の文字列で
      ある場合、指定されたブレークポイントが存在しないか削除された場合
      、 "ValueError" が上げられます。

      バージョン 3.2 で追加.

   get_break(filename, lineno)

      Return True if there is a breakpoint for *lineno* in *filename*.

   get_breaks(filename, lineno)

      *filename* の *lineno* にあるすべてのブレークポイントを返します
      。ブレークポイントが存在しない場合は空のリストを返します。

   get_file_breaks(filename)

      *filename* の中のすべてのブレークポイントを返します。ブレークポ
      イントが存在しない場合は空のリストを返します。

   get_all_breaks()

      セットされているすべてのブレークポイントを返します。

   継承クラスとクライアントは以下のメソッドを呼んでスタックトレースを
   表現するデータ構造を取得することができます。

   get_stack(f, t)

      Return a list of (frame, lineno) tuples in a stack trace, and a
      size.

      The most recently called frame is last in the list. The size is
      the number of frames below the frame where the debugger was
      invoked.

   format_stack_entry(frame_lineno, lprefix=': ')

      Return a string with information about a stack entry, which is a
      "(frame, lineno)" tuple.  The return string contains:

      * The canonical filename which contains the frame.

      * 関数名もしくは ""<lambda>""。

      * 入力された引数。

      * 戻り値。

      * (あれば)その行のコード。

   以下の2つのメソッドは、文字列として渡された *文* をデバッグするもの
   で、クライアントから利用されます。

   run(cmd, globals=None, locals=None)

      Debug a statement executed via the "exec()" function.  *globals*
      defaults to "__main__.__dict__", *locals* defaults to *globals*.

   runeval(expr, globals=None, locals=None)

      "eval()" 関数を利用して式を実行しデバッグします。 *globals* と
      *locals* は "run()" と同じ意味です。

   runctx(cmd, globals, locals)

      後方互換性のためのメソッドです。 "run()" を使ってください。

   runcall(func, /, *args, **kwds)

      1つの関数呼び出しをデバッグし、その結果を返します。

最後に、このモジュールは以下の関数を提供しています:

bdb.checkfuncname(b, frame)

   Return True if we should break here, depending on the way the
   "Breakpoint" *b* was set.

   If it was set via line number, it checks if "b.line" is the same as
   the one in *frame*. If the breakpoint was set via "function name",
   we have to check we are in the right *frame* (the right function)
   and if we are on its first executable line.

bdb.effective(file, line, frame)

   Return "(active breakpoint, delete temporary flag)" or "(None,
   None)" as the breakpoint to act upon.

   The *active breakpoint* is the first entry in "bplist" for the
   ("file", "line") (which must exist) that is "enabled", for which
   "checkfuncname()" is True, and that has neither a False "condition"
   nor positive "ignore" count.  The *flag*, meaning that a temporary
   breakpoint should be deleted, is False only when the "cond" cannot
   be evaluated (in which case, "ignore" count is ignored).

   If no such entry exists, then (None, None) is returned.

bdb.set_trace()

   "Bdb" クラスのインスタンスを使って、呼び出し元のフレームからデバッ
   グを開始します。
