/Doc/library/bdb.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 345 lines · 214 code · 131 blank · 0 comment · 0 complexity · e5eb71c6be8919e0db95fee022a854f9 MD5 · raw file

  1. :mod:`bdb` --- Debugger framework
  2. =================================
  3. .. module:: bdb
  4. :synopsis: Debugger framework.
  5. The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
  6. or managing execution via the debugger.
  7. The following exception is defined:
  8. .. exception:: BdbQuit
  9. Exception raised by the :class:`Bdb` class for quitting the debugger.
  10. The :mod:`bdb` module also defines two classes:
  11. .. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]])
  12. This class implements temporary breakpoints, ignore counts, disabling and
  13. (re-)enabling, and conditionals.
  14. Breakpoints are indexed by number through a list called :attr:`bpbynumber`
  15. and by ``(file, line)`` pairs through :attr:`bplist`. The former points to a
  16. single instance of class :class:`Breakpoint`. The latter points to a list of
  17. such instances since there may be more than one breakpoint per line.
  18. When creating a breakpoint, its associated filename should be in canonical
  19. form. If a *funcname* is defined, a breakpoint hit will be counted when the
  20. first line of that function is executed. A conditional breakpoint always
  21. counts a hit.
  22. :class:`Breakpoint` instances have the following methods:
  23. .. method:: deleteMe()
  24. Delete the breakpoint from the list associated to a file/line. If it is
  25. the last breakpoint in that position, it also deletes the entry for the
  26. file/line.
  27. .. method:: enable()
  28. Mark the breakpoint as enabled.
  29. .. method:: disable()
  30. Mark the breakpoint as disabled.
  31. .. method:: pprint([out])
  32. Print all the information about the breakpoint:
  33. * The breakpoint number.
  34. * If it is temporary or not.
  35. * Its file,line position.
  36. * The condition that causes a break.
  37. * If it must be ignored the next N times.
  38. * The breakpoint hit count.
  39. .. class:: Bdb()
  40. The :class:`Bdb` acts as a generic Python debugger base class.
  41. This class takes care of the details of the trace facility; a derived class
  42. should implement user interaction. The standard debugger class
  43. (:class:`pdb.Pdb`) is an example.
  44. The following methods of :class:`Bdb` normally don't need to be overridden.
  45. .. method:: canonic(filename)
  46. Auxiliary method for getting a filename in a canonical form, that is, as a
  47. case-normalized (on case-insensitive filesystems) absolute path, stripped
  48. of surrounding angle brackets.
  49. .. method:: reset()
  50. Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
  51. :attr:`quitting` attributes with values ready to start debugging.
  52. .. method:: trace_dispatch(frame, event, arg)
  53. This function is installed as the trace function of debugged frames. Its
  54. return value is the new trace function (in most cases, that is, itself).
  55. The default implementation decides how to dispatch a frame, depending on
  56. the type of event (passed as a string) that is about to be executed.
  57. *event* can be one of the following:
  58. * ``"line"``: A new line of code is going to be executed.
  59. * ``"call"``: A function is about to be called, or another code block
  60. entered.
  61. * ``"return"``: A function or other code block is about to return.
  62. * ``"exception"``: An exception has occurred.
  63. * ``"c_call"``: A C function is about to be called.
  64. * ``"c_return"``: A C function has returned.
  65. * ``"c_exception"``: A C function has thrown an exception.
  66. For the Python events, specialized functions (see below) are called. For
  67. the C events, no action is taken.
  68. The *arg* parameter depends on the previous event.
  69. See the documentation for :func:`sys.settrace` for more information on the
  70. trace function. For more information on code and frame objects, refer to
  71. :ref:`types`.
  72. .. method:: dispatch_line(frame)
  73. If the debugger should stop on the current line, invoke the
  74. :meth:`user_line` method (which should be overridden in subclasses).
  75. Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
  76. (which can be set from :meth:`user_line`). Return a reference to the
  77. :meth:`trace_dispatch` method for further tracing in that scope.
  78. .. method:: dispatch_call(frame, arg)
  79. If the debugger should stop on this function call, invoke the
  80. :meth:`user_call` method (which should be overridden in subclasses).
  81. Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
  82. (which can be set from :meth:`user_call`). Return a reference to the
  83. :meth:`trace_dispatch` method for further tracing in that scope.
  84. .. method:: dispatch_return(frame, arg)
  85. If the debugger should stop on this function return, invoke the
  86. :meth:`user_return` method (which should be overridden in subclasses).
  87. Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
  88. (which can be set from :meth:`user_return`). Return a reference to the
  89. :meth:`trace_dispatch` method for further tracing in that scope.
  90. .. method:: dispatch_exception(frame, arg)
  91. If the debugger should stop at this exception, invokes the
  92. :meth:`user_exception` method (which should be overridden in subclasses).
  93. Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
  94. (which can be set from :meth:`user_exception`). Return a reference to the
  95. :meth:`trace_dispatch` method for further tracing in that scope.
  96. Normally derived classes don't override the following methods, but they may
  97. if they want to redefine the definition of stopping and breakpoints.
  98. .. method:: stop_here(frame)
  99. This method checks if the *frame* is somewhere below :attr:`botframe` in
  100. the call stack. :attr:`botframe` is the frame in which debugging started.
  101. .. method:: break_here(frame)
  102. This method checks if there is a breakpoint in the filename and line
  103. belonging to *frame* or, at least, in the current function. If the
  104. breakpoint is a temporary one, this method deletes it.
  105. .. method:: break_anywhere(frame)
  106. This method checks if there is a breakpoint in the filename of the current
  107. frame.
  108. Derived classes should override these methods to gain control over debugger
  109. operation.
  110. .. method:: user_call(frame, argument_list)
  111. This method is called from :meth:`dispatch_call` when there is the
  112. possibility that a break might be necessary anywhere inside the called
  113. function.
  114. .. method:: user_line(frame)
  115. This method is called from :meth:`dispatch_line` when either
  116. :meth:`stop_here` or :meth:`break_here` yields True.
  117. .. method:: user_return(frame, return_value)
  118. This method is called from :meth:`dispatch_return` when :meth:`stop_here`
  119. yields True.
  120. .. method:: user_exception(frame, exc_info)
  121. This method is called from :meth:`dispatch_exception` when
  122. :meth:`stop_here` yields True.
  123. .. method:: do_clear(arg)
  124. Handle how a breakpoint must be removed when it is a temporary one.
  125. This method must be implemented by derived classes.
  126. Derived classes and clients can call the following methods to affect the
  127. stepping state.
  128. .. method:: set_step()
  129. Stop after one line of code.
  130. .. method:: set_next(frame)
  131. Stop on the next line in or below the given frame.
  132. .. method:: set_return(frame)
  133. Stop when returning from the given frame.
  134. .. method:: set_until(frame)
  135. Stop when the line with the line no greater than the current one is
  136. reached or when returning from current frame
  137. .. method:: set_trace([frame])
  138. Start debugging from *frame*. If *frame* is not specified, debugging
  139. starts from caller's frame.
  140. .. method:: set_continue()
  141. Stop only at breakpoints or when finished. If there are no breakpoints,
  142. set the system trace function to None.
  143. .. method:: set_quit()
  144. Set the :attr:`quitting` attribute to True. This raises :exc:`BdbQuit` in
  145. the next call to one of the :meth:`dispatch_\*` methods.
  146. Derived classes and clients can call the following methods to manipulate
  147. breakpoints. These methods return a string containing an error message if
  148. something went wrong, or ``None`` if all is well.
  149. .. method:: set_break(filename, lineno[, temporary=0[, cond[, funcname]]])
  150. Set a new breakpoint. If the *lineno* line doesn't exist for the
  151. *filename* passed as argument, return an error message. The *filename*
  152. should be in canonical form, as described in the :meth:`canonic` method.
  153. .. method:: clear_break(filename, lineno)
  154. Delete the breakpoints in *filename* and *lineno*. If none were set, an
  155. error message is returned.
  156. .. method:: clear_bpbynumber(arg)
  157. Delete the breakpoint which has the index *arg* in the
  158. :attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range,
  159. return an error message.
  160. .. method:: clear_all_file_breaks(filename)
  161. Delete all breakpoints in *filename*. If none were set, an error message
  162. is returned.
  163. .. method:: clear_all_breaks()
  164. Delete all existing breakpoints.
  165. .. method:: get_break(filename, lineno)
  166. Check if there is a breakpoint for *lineno* of *filename*.
  167. .. method:: get_breaks(filename, lineno)
  168. Return all breakpoints for *lineno* in *filename*, or an empty list if
  169. none are set.
  170. .. method:: get_file_breaks(filename)
  171. Return all breakpoints in *filename*, or an empty list if none are set.
  172. .. method:: get_all_breaks()
  173. Return all breakpoints that are set.
  174. Derived classes and clients can call the following methods to get a data
  175. structure representing a stack trace.
  176. .. method:: get_stack(f, t)
  177. Get a list of records for a frame and all higher (calling) and lower
  178. frames, and the size of the higher part.
  179. .. method:: format_stack_entry(frame_lineno, [lprefix=': '])
  180. Return a string with information about a stack entry, identified by a
  181. ``(frame, lineno)`` tuple:
  182. * The canonical form of the filename which contains the frame.
  183. * The function name, or ``"<lambda>"``.
  184. * The input arguments.
  185. * The return value.
  186. * The line of code (if it exists).
  187. The following two methods can be called by clients to use a debugger to debug
  188. a :term:`statement`, given as a string.
  189. .. method:: run(cmd, [globals, [locals]])
  190. Debug a statement executed via the :keyword:`exec` statement. *globals*
  191. defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
  192. .. method:: runeval(expr, [globals, [locals]])
  193. Debug an expression executed via the :func:`eval` function. *globals* and
  194. *locals* have the same meaning as in :meth:`run`.
  195. .. method:: runctx(cmd, globals, locals)
  196. For backwards compatibility. Calls the :meth:`run` method.
  197. .. method:: runcall(func, *args, **kwds)
  198. Debug a single function call, and return its result.
  199. Finally, the module defines the following functions:
  200. .. function:: checkfuncname(b, frame)
  201. Check whether we should break here, depending on the way the breakpoint *b*
  202. was set.
  203. If it was set via line number, it checks if ``b.line`` is the same as the one
  204. in the frame also passed as argument. If the breakpoint was set via function
  205. name, we have to check we are in the right frame (the right function) and if
  206. we are in its first executable line.
  207. .. function:: effective(file, line, frame)
  208. Determine if there is an effective (active) breakpoint at this line of code.
  209. Return breakpoint number or 0 if none.
  210. Called only if we know there is a breakpoint at this location. Returns the
  211. breakpoint that was triggered and a flag that indicates if it is ok to delete
  212. a temporary breakpoint.
  213. .. function:: set_trace()
  214. Starts debugging with a :class:`Bdb` instance from caller's frame.