1 :mod:`bdb` --- Debugger framework

     2 =================================

     3 

     4 .. module:: bdb

     5    :synopsis: Debugger framework.

     6 

     7 The :mod:`bdb` module handles basic debugger functions, like setting breakpoints

     8 or managing execution via the debugger.

     9 

    10 The following exception is defined:

    11 

    12 .. exception:: BdbQuit

    13 

    14    Exception raised by the :class:`Bdb` class for quitting the debugger.

    15 

    16 

    17 The :mod:`bdb` module also defines two classes:

    18 

    19 .. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]])

    20 

    21    This class implements temporary breakpoints, ignore counts, disabling and

    22    (re-)enabling, and conditionals.

    23 

    24    Breakpoints are indexed by number through a list called :attr:`bpbynumber`

    25    and by ``(file, line)`` pairs through :attr:`bplist`.  The former points to a

    26    single instance of class :class:`Breakpoint`.  The latter points to a list of

    27    such instances since there may be more than one breakpoint per line.

    28 

    29    When creating a breakpoint, its associated filename should be in canonical

    30    form.  If a *funcname* is defined, a breakpoint hit will be counted when the

    31    first line of that function is executed.  A conditional breakpoint always

    32    counts a hit.

    33 

    34    :class:`Breakpoint` instances have the following methods:

    35 

    36    .. method:: deleteMe()

    37 

    38       Delete the breakpoint from the list associated to a file/line.  If it is

    39       the last breakpoint in that position, it also deletes the entry for the

    40       file/line.

    41 

    42 

    43    .. method:: enable()

    44 

    45       Mark the breakpoint as enabled.

    46 

    47 

    48    .. method:: disable()

    49 

    50       Mark the breakpoint as disabled.

    51 

    52 

    53    .. method:: pprint([out])

    54 

    55       Print all the information about the breakpoint:

    56 

    57       * The breakpoint number.

    58       * If it is temporary or not.

    59       * Its file,line position.

    60       * The condition that causes a break.

    61       * If it must be ignored the next N times.

    62       * The breakpoint hit count.

    63 

    64 

    65 .. class:: Bdb()

    66 

    67    The :class:`Bdb` acts as a generic Python debugger base class.

    68 

    69    This class takes care of the details of the trace facility; a derived class

    70    should implement user interaction.  The standard debugger class

    71    (:class:`pdb.Pdb`) is an example.

    72 

    73 

    74    The following methods of :class:`Bdb` normally don't need to be overridden.

    75 

    76    .. method:: canonic(filename)

    77 

    78       Auxiliary method for getting a filename in a canonical form, that is, as a

    79       case-normalized (on case-insensitive filesystems) absolute path, stripped

    80       of surrounding angle brackets.

    81 

    82    .. method:: reset()

    83 

    84       Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and

    85       :attr:`quitting` attributes with values ready to start debugging.

    86 

    87    .. method:: trace_dispatch(frame, event, arg)

    88 

    89       This function is installed as the trace function of debugged frames.  Its

    90       return value is the new trace function (in most cases, that is, itself).

    91 

    92       The default implementation decides how to dispatch a frame, depending on

    93       the type of event (passed as a string) that is about to be executed.

    94       *event* can be one of the following:

    95 

    96       * ``"line"``: A new line of code is going to be executed.

    97       * ``"call"``: A function is about to be called, or another code block

    98         entered.

    99       * ``"return"``: A function or other code block is about to return.

   100       * ``"exception"``: An exception has occurred.

   101       * ``"c_call"``: A C function is about to be called.

   102       * ``"c_return"``: A C function has returned.

   103       * ``"c_exception"``: A C function has thrown an exception.

   104 

   105       For the Python events, specialized functions (see below) are called.  For

   106       the C events, no action is taken.

   107 

   108       The *arg* parameter depends on the previous event.

   109 

   110       For more information on trace functions, see :ref:`debugger-hooks`.  For

   111       more information on code and frame objects, refer to :ref:`types`.

   112 

   113    .. method:: dispatch_line(frame)

   114 

   115       If the debugger should stop on the current line, invoke the

   116       :meth:`user_line` method (which should be overridden in subclasses).

   117       Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set

   118       (which can be set from :meth:`user_line`).  Return a reference to the

   119       :meth:`trace_dispatch` method for further tracing in that scope.

   120 

   121    .. method:: dispatch_call(frame, arg)

   122 

   123       If the debugger should stop on this function call, invoke the

   124       :meth:`user_call` method (which should be overridden in subclasses).

   125       Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set

   126       (which can be set from :meth:`user_call`).  Return a reference to the

   127       :meth:`trace_dispatch` method for further tracing in that scope.

   128 

   129    .. method:: dispatch_return(frame, arg)

   130 

   131       If the debugger should stop on this function return, invoke the

   132       :meth:`user_return` method (which should be overridden in subclasses).

   133       Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set

   134       (which can be set from :meth:`user_return`).  Return a reference to the

   135       :meth:`trace_dispatch` method for further tracing in that scope.

   136 

   137    .. method:: dispatch_exception(frame, arg)

   138 

   139       If the debugger should stop at this exception, invokes the

   140       :meth:`user_exception` method (which should be overridden in subclasses).

   141       Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set

   142       (which can be set from :meth:`user_exception`).  Return a reference to the

   143       :meth:`trace_dispatch` method for further tracing in that scope.

   144 

   145    Normally derived classes don't override the following methods, but they may

   146    if they want to redefine the definition of stopping and breakpoints.

   147 

   148    .. method:: stop_here(frame)

   149 

   150       This method checks if the *frame* is somewhere below :attr:`botframe` in

   151       the call stack.  :attr:`botframe` is the frame in which debugging started.

   152 

   153    .. method:: break_here(frame)

   154 

   155       This method checks if there is a breakpoint in the filename and line

   156       belonging to *frame* or, at least, in the current function.  If the

   157       breakpoint is a temporary one, this method deletes it.

   158 

   159    .. method:: break_anywhere(frame)

   160 

   161       This method checks if there is a breakpoint in the filename of the current

   162       frame.

   163 

   164    Derived classes should override these methods to gain control over debugger

   165    operation.

   166 

   167    .. method:: user_call(frame, argument_list)

   168 

   169       This method is called from :meth:`dispatch_call` when there is the

   170       possibility that a break might be necessary anywhere inside the called

   171       function.

   172 

   173    .. method:: user_line(frame)

   174 

   175       This method is called from :meth:`dispatch_line` when either

   176       :meth:`stop_here` or :meth:`break_here` yields True.

   177 

   178    .. method:: user_return(frame, return_value)

   179 

   180       This method is called from :meth:`dispatch_return` when :meth:`stop_here`

   181       yields True.

   182 

   183    .. method:: user_exception(frame, exc_info)

   184 

   185       This method is called from :meth:`dispatch_exception` when

   186       :meth:`stop_here` yields True.

   187 

   188    .. method:: do_clear(arg)

   189 

   190       Handle how a breakpoint must be removed when it is a temporary one.

   191 

   192       This method must be implemented by derived classes.

   193 

   194 

   195    Derived classes and clients can call the following methods to affect the

   196    stepping state.

   197 

   198    .. method:: set_step()

   199 

   200       Stop after one line of code.

   201 

   202    .. method:: set_next(frame)

   203 

   204       Stop on the next line in or below the given frame.

   205 

   206    .. method:: set_return(frame)

   207 

   208       Stop when returning from the given frame.

   209 

   210    .. method:: set_until(frame)

   211 

   212       Stop when the line with the line no greater than the current one is

   213       reached or when returning from current frame

   214 

   215    .. method:: set_trace([frame])

   216 

   217       Start debugging from *frame*.  If *frame* is not specified, debugging

   218       starts from caller's frame.

   219 

   220    .. method:: set_continue()

   221 

   222       Stop only at breakpoints or when finished.  If there are no breakpoints,

   223       set the system trace function to None.

   224 

   225    .. method:: set_quit()

   226 

   227       Set the :attr:`quitting` attribute to True.  This raises :exc:`BdbQuit` in

   228       the next call to one of the :meth:`dispatch_\*` methods.

   229 

   230 

   231    Derived classes and clients can call the following methods to manipulate

   232    breakpoints.  These methods return a string containing an error message if

   233    something went wrong, or ``None`` if all is well.

   234 

   235    .. method:: set_break(filename, lineno[, temporary=0[, cond[, funcname]]])

   236 

   237       Set a new breakpoint.  If the *lineno* line doesn't exist for the

   238       *filename* passed as argument, return an error message.  The *filename*

   239       should be in canonical form, as described in the :meth:`canonic` method.

   240 

   241    .. method:: clear_break(filename, lineno)

   242 

   243       Delete the breakpoints in *filename* and *lineno*.  If none were set, an

   244       error message is returned.

   245 

   246    .. method:: clear_bpbynumber(arg)

   247 

   248       Delete the breakpoint which has the index *arg* in the

   249       :attr:`Breakpoint.bpbynumber`.  If *arg* is not numeric or out of range,

   250       return an error message.

   251 

   252    .. method:: clear_all_file_breaks(filename)

   253 

   254       Delete all breakpoints in *filename*.  If none were set, an error message

   255       is returned.

   256 

   257    .. method:: clear_all_breaks()

   258 

   259       Delete all existing breakpoints.

   260 

   261    .. method:: get_break(filename, lineno)

   262 

   263       Check if there is a breakpoint for *lineno* of *filename*.

   264 

   265    .. method:: get_breaks(filename, lineno)

   266 

   267       Return all breakpoints for *lineno* in *filename*, or an empty list if

   268       none are set.

   269 

   270    .. method:: get_file_breaks(filename)

   271 

   272       Return all breakpoints in *filename*, or an empty list if none are set.

   273 

   274    .. method:: get_all_breaks()

   275 

   276       Return all breakpoints that are set.

   277 

   278 

   279    Derived classes and clients can call the following methods to get a data

   280    structure representing a stack trace.

   281 

   282    .. method:: get_stack(f, t)

   283 

   284       Get a list of records for a frame and all higher (calling) and lower

   285       frames, and the size of the higher part.

   286 

   287    .. method:: format_stack_entry(frame_lineno, [lprefix=': '])

   288 

   289       Return a string with information about a stack entry, identified by a

   290       ``(frame, lineno)`` tuple:

   291 

   292       * The canonical form of the filename which contains the frame.

   293       * The function name, or ``"<lambda>"``.

   294       * The input arguments.

   295       * The return value.

   296       * The line of code (if it exists).

   297 

   298 

   299    The following two methods can be called by clients to use a debugger to debug

   300    a :term:`statement`, given as a string.

   301 

   302    .. method:: run(cmd, [globals, [locals]])

   303 

   304       Debug a statement executed via the :keyword:`exec` statement.  *globals*

   305       defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.

   306 

   307    .. method:: runeval(expr, [globals, [locals]])

   308 

   309       Debug an expression executed via the :func:`eval` function.  *globals* and

   310       *locals* have the same meaning as in :meth:`run`.

   311 

   312    .. method:: runctx(cmd, globals, locals)

   313 

   314       For backwards compatibility.  Calls the :meth:`run` method.

   315 

   316    .. method:: runcall(func, *args, **kwds)

   317 

   318       Debug a single function call, and return its result.

   319 

   320 

   321 Finally, the module defines the following functions:

   322 

   323 .. function:: checkfuncname(b, frame)

   324 

   325    Check whether we should break here, depending on the way the breakpoint *b*

   326    was set.

   327    

   328    If it was set via line number, it checks if ``b.line`` is the same as the one

   329    in the frame also passed as argument.  If the breakpoint was set via function

   330    name, we have to check we are in the right frame (the right function) and if

   331    we are in its first executable line.

   332 

   333 .. function:: effective(file, line, frame)

   334 

   335    Determine if there is an effective (active) breakpoint at this line of code.

   336    Return breakpoint number or 0 if none.

   337 	

   338    Called only if we know there is a breakpoint at this location.  Returns the

   339    breakpoint that was triggered and a flag that indicates if it is ok to delete

   340    a temporary breakpoint.

   341 

   342 .. function:: set_trace()

   343 

   344    Starts debugging with a :class:`Bdb` instance from caller's frame.