1:mod:`bdb` --- Debugger framework 2================================= 3 4.. module:: bdb 5 :synopsis: Debugger framework. 6 7**Source code:** :source:`Lib/bdb.py` 8 9-------------- 10 11The :mod:`bdb` module handles basic debugger functions, like setting breakpoints 12or managing execution via the debugger. 13 14The following exception is defined: 15 16.. exception:: BdbQuit 17 18 Exception raised by the :class:`Bdb` class for quitting the debugger. 19 20 21The :mod:`bdb` module also defines two classes: 22 23.. class:: Breakpoint(self, file, line, temporary=0, cond=None, funcname=None) 24 25 This class implements temporary breakpoints, ignore counts, disabling and 26 (re-)enabling, and conditionals. 27 28 Breakpoints are indexed by number through a list called :attr:`bpbynumber` 29 and by ``(file, line)`` pairs through :attr:`bplist`. The former points to a 30 single instance of class :class:`Breakpoint`. The latter points to a list of 31 such instances since there may be more than one breakpoint per line. 32 33 When creating a breakpoint, its associated filename should be in canonical 34 form. If a *funcname* is defined, a breakpoint hit will be counted when the 35 first line of that function is executed. A conditional breakpoint always 36 counts a hit. 37 38 :class:`Breakpoint` instances have the following methods: 39 40 .. method:: deleteMe() 41 42 Delete the breakpoint from the list associated to a file/line. If it is 43 the last breakpoint in that position, it also deletes the entry for the 44 file/line. 45 46 47 .. method:: enable() 48 49 Mark the breakpoint as enabled. 50 51 52 .. method:: disable() 53 54 Mark the breakpoint as disabled. 55 56 57 .. method:: pprint([out]) 58 59 Print all the information about the breakpoint: 60 61 * The breakpoint number. 62 * If it is temporary or not. 63 * Its file,line position. 64 * The condition that causes a break. 65 * If it must be ignored the next N times. 66 * The breakpoint hit count. 67 68 69.. class:: Bdb(skip=None) 70 71 The :class:`Bdb` class acts as a generic Python debugger base class. 72 73 This class takes care of the details of the trace facility; a derived class 74 should implement user interaction. The standard debugger class 75 (:class:`pdb.Pdb`) is an example. 76 77 The *skip* argument, if given, must be an iterable of glob-style 78 module name patterns. The debugger will not step into frames that 79 originate in a module that matches one of these patterns. Whether a 80 frame is considered to originate in a certain module is determined 81 by the ``__name__`` in the frame globals. 82 83 .. versionadded:: 2.7 84 The *skip* argument. 85 86 The following methods of :class:`Bdb` normally don't need to be overridden. 87 88 .. method:: canonic(filename) 89 90 Auxiliary method for getting a filename in a canonical form, that is, as a 91 case-normalized (on case-insensitive filesystems) absolute path, stripped 92 of surrounding angle brackets. 93 94 .. method:: reset() 95 96 Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and 97 :attr:`quitting` attributes with values ready to start debugging. 98 99 .. method:: trace_dispatch(frame, event, arg) 100 101 This function is installed as the trace function of debugged frames. Its 102 return value is the new trace function (in most cases, that is, itself). 103 104 The default implementation decides how to dispatch a frame, depending on 105 the type of event (passed as a string) that is about to be executed. 106 *event* can be one of the following: 107 108 * ``"line"``: A new line of code is going to be executed. 109 * ``"call"``: A function is about to be called, or another code block 110 entered. 111 * ``"return"``: A function or other code block is about to return. 112 * ``"exception"``: An exception has occurred. 113 * ``"c_call"``: A C function is about to be called. 114 * ``"c_return"``: A C function has returned. 115 * ``"c_exception"``: A C function has raised an exception. 116 117 For the Python events, specialized functions (see below) are called. For 118 the C events, no action is taken. 119 120 The *arg* parameter depends on the previous event. 121 122 See the documentation for :func:`sys.settrace` for more information on the 123 trace function. For more information on code and frame objects, refer to 124 :ref:`types`. 125 126 .. method:: dispatch_line(frame) 127 128 If the debugger should stop on the current line, invoke the 129 :meth:`user_line` method (which should be overridden in subclasses). 130 Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set 131 (which can be set from :meth:`user_line`). Return a reference to the 132 :meth:`trace_dispatch` method for further tracing in that scope. 133 134 .. method:: dispatch_call(frame, arg) 135 136 If the debugger should stop on this function call, invoke the 137 :meth:`user_call` method (which should be overridden in subclasses). 138 Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set 139 (which can be set from :meth:`user_call`). Return a reference to the 140 :meth:`trace_dispatch` method for further tracing in that scope. 141 142 .. method:: dispatch_return(frame, arg) 143 144 If the debugger should stop on this function return, invoke the 145 :meth:`user_return` method (which should be overridden in subclasses). 146 Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set 147 (which can be set from :meth:`user_return`). Return a reference to the 148 :meth:`trace_dispatch` method for further tracing in that scope. 149 150 .. method:: dispatch_exception(frame, arg) 151 152 If the debugger should stop at this exception, invokes the 153 :meth:`user_exception` method (which should be overridden in subclasses). 154 Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set 155 (which can be set from :meth:`user_exception`). Return a reference to the 156 :meth:`trace_dispatch` method for further tracing in that scope. 157 158 Normally derived classes don't override the following methods, but they may 159 if they want to redefine the definition of stopping and breakpoints. 160 161 .. method:: stop_here(frame) 162 163 This method checks if the *frame* is somewhere below :attr:`botframe` in 164 the call stack. :attr:`botframe` is the frame in which debugging started. 165 166 .. method:: break_here(frame) 167 168 This method checks if there is a breakpoint in the filename and line 169 belonging to *frame* or, at least, in the current function. If the 170 breakpoint is a temporary one, this method deletes it. 171 172 .. method:: break_anywhere(frame) 173 174 This method checks if there is a breakpoint in the filename of the current 175 frame. 176 177 Derived classes should override these methods to gain control over debugger 178 operation. 179 180 .. method:: user_call(frame, argument_list) 181 182 This method is called from :meth:`dispatch_call` when there is the 183 possibility that a break might be necessary anywhere inside the called 184 function. 185 186 .. method:: user_line(frame) 187 188 This method is called from :meth:`dispatch_line` when either 189 :meth:`stop_here` or :meth:`break_here` yields ``True``. 190 191 .. method:: user_return(frame, return_value) 192 193 This method is called from :meth:`dispatch_return` when :meth:`stop_here` 194 yields ``True``. 195 196 .. method:: user_exception(frame, exc_info) 197 198 This method is called from :meth:`dispatch_exception` when 199 :meth:`stop_here` yields ``True``. 200 201 .. method:: do_clear(arg) 202 203 Handle how a breakpoint must be removed when it is a temporary one. 204 205 This method must be implemented by derived classes. 206 207 208 Derived classes and clients can call the following methods to affect the 209 stepping state. 210 211 .. method:: set_step() 212 213 Stop after one line of code. 214 215 .. method:: set_next(frame) 216 217 Stop on the next line in or below the given frame. 218 219 .. method:: set_return(frame) 220 221 Stop when returning from the given frame. 222 223 .. method:: set_until(frame) 224 225 Stop when the line with the line no greater than the current one is 226 reached or when returning from current frame. 227 228 .. method:: set_trace([frame]) 229 230 Start debugging from *frame*. If *frame* is not specified, debugging 231 starts from caller's frame. 232 233 .. method:: set_continue() 234 235 Stop only at breakpoints or when finished. If there are no breakpoints, 236 set the system trace function to ``None``. 237 238 .. method:: set_quit() 239 240 Set the :attr:`quitting` attribute to ``True``. This raises :exc:`BdbQuit` in 241 the next call to one of the :meth:`dispatch_\*` methods. 242 243 244 Derived classes and clients can call the following methods to manipulate 245 breakpoints. These methods return a string containing an error message if 246 something went wrong, or ``None`` if all is well. 247 248 .. method:: set_break(filename, lineno, temporary=0, cond=None, funcname=None) 249 250 Set a new breakpoint. If the *lineno* line doesn't exist for the 251 *filename* passed as argument, return an error message. The *filename* 252 should be in canonical form, as described in the :meth:`canonic` method. 253 254 .. method:: clear_break(filename, lineno) 255 256 Delete the breakpoints in *filename* and *lineno*. If none were set, an 257 error message is returned. 258 259 .. method:: clear_bpbynumber(arg) 260 261 Delete the breakpoint which has the index *arg* in the 262 :attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range, 263 return an error message. 264 265 .. method:: clear_all_file_breaks(filename) 266 267 Delete all breakpoints in *filename*. If none were set, an error message 268 is returned. 269 270 .. method:: clear_all_breaks() 271 272 Delete all existing breakpoints. 273 274 .. method:: get_break(filename, lineno) 275 276 Check if there is a breakpoint for *lineno* of *filename*. 277 278 .. method:: get_breaks(filename, lineno) 279 280 Return all breakpoints for *lineno* in *filename*, or an empty list if 281 none are set. 282 283 .. method:: get_file_breaks(filename) 284 285 Return all breakpoints in *filename*, or an empty list if none are set. 286 287 .. method:: get_all_breaks() 288 289 Return all breakpoints that are set. 290 291 292 Derived classes and clients can call the following methods to get a data 293 structure representing a stack trace. 294 295 .. method:: get_stack(f, t) 296 297 Get a list of records for a frame and all higher (calling) and lower 298 frames, and the size of the higher part. 299 300 .. method:: format_stack_entry(frame_lineno, [lprefix=': ']) 301 302 Return a string with information about a stack entry, identified by a 303 ``(frame, lineno)`` tuple: 304 305 * The canonical form of the filename which contains the frame. 306 * The function name, or ``"<lambda>"``. 307 * The input arguments. 308 * The return value. 309 * The line of code (if it exists). 310 311 312 The following two methods can be called by clients to use a debugger to debug 313 a :term:`statement`, given as a string. 314 315 .. method:: run(cmd, [globals, [locals]]) 316 317 Debug a statement executed via the :keyword:`exec` statement. *globals* 318 defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*. 319 320 .. method:: runeval(expr, [globals, [locals]]) 321 322 Debug an expression executed via the :func:`eval` function. *globals* and 323 *locals* have the same meaning as in :meth:`run`. 324 325 .. method:: runctx(cmd, globals, locals) 326 327 For backwards compatibility. Calls the :meth:`run` method. 328 329 .. method:: runcall(func, *args, **kwds) 330 331 Debug a single function call, and return its result. 332 333 334Finally, the module defines the following functions: 335 336.. function:: checkfuncname(b, frame) 337 338 Check whether we should break here, depending on the way the breakpoint *b* 339 was set. 340 341 If it was set via line number, it checks if ``b.line`` is the same as the one 342 in the frame also passed as argument. If the breakpoint was set via function 343 name, we have to check we are in the right frame (the right function) and if 344 we are in its first executable line. 345 346.. function:: effective(file, line, frame) 347 348 Determine if there is an effective (active) breakpoint at this line of code. 349 Return a tuple of the breakpoint and a boolean that indicates if it is ok 350 to delete a temporary breakpoint. Return ``(None, None)`` if there is no 351 matching breakpoint. 352 353.. function:: set_trace() 354 355 Start debugging with a :class:`Bdb` instance from caller's frame. 356