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=False, 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 30 a single instance of class :class:`Breakpoint`. The latter points to a list 31 of such instances since there may be more than one breakpoint per line. 32 33 When creating a breakpoint, its associated :attr:`file name <file>` should 34 be in canonical form. If a :attr:`funcname` is defined, a breakpoint 35 :attr:`hit <hits>` will be counted when the first line of that function is 36 executed. A :attr:`conditional <cond>` breakpoint always counts a 37 :attr:`hit <hits>`. 38 39 :class:`Breakpoint` instances have the following methods: 40 41 .. method:: deleteMe() 42 43 Delete the breakpoint from the list associated to a file/line. If it is 44 the last breakpoint in that position, it also deletes the entry for the 45 file/line. 46 47 48 .. method:: enable() 49 50 Mark the breakpoint as enabled. 51 52 53 .. method:: disable() 54 55 Mark the breakpoint as disabled. 56 57 58 .. method:: bpformat() 59 60 Return a string with all the information about the breakpoint, nicely 61 formatted: 62 63 * Breakpoint number. 64 * Temporary status (del or keep). 65 * File/line position. 66 * Break condition. 67 * Number of times to ignore. 68 * Number of times hit. 69 70 .. versionadded:: 3.2 71 72 .. method:: bpprint(out=None) 73 74 Print the output of :meth:`bpformat` to the file *out*, or if it is 75 ``None``, to standard output. 76 77 :class:`Breakpoint` instances have the following attributes: 78 79 .. attribute:: file 80 81 File name of the :class:`Breakpoint`. 82 83 .. attribute:: line 84 85 Line number of the :class:`Breakpoint` within :attr:`file`. 86 87 .. attribute:: temporary 88 89 True if a :class:`Breakpoint` at (file, line) is temporary. 90 91 .. attribute:: cond 92 93 Condition for evaluating a :class:`Breakpoint` at (file, line). 94 95 .. attribute:: funcname 96 97 Function name that defines whether a :class:`Breakpoint` is hit upon 98 entering the function. 99 100 .. attribute:: enabled 101 102 True if :class:`Breakpoint` is enabled. 103 104 .. attribute:: bpbynumber 105 106 Numeric index for a single instance of a :class:`Breakpoint`. 107 108 .. attribute:: bplist 109 110 Dictionary of :class:`Breakpoint` instances indexed by 111 (:attr:`file`, :attr:`line`) tuples. 112 113 .. attribute:: ignore 114 115 Number of times to ignore a :class:`Breakpoint`. 116 117 .. attribute:: hits 118 119 Count of the number of times a :class:`Breakpoint` has been hit. 120 121.. class:: Bdb(skip=None) 122 123 The :class:`Bdb` class acts as a generic Python debugger base class. 124 125 This class takes care of the details of the trace facility; a derived class 126 should implement user interaction. The standard debugger class 127 (:class:`pdb.Pdb`) is an example. 128 129 The *skip* argument, if given, must be an iterable of glob-style 130 module name patterns. The debugger will not step into frames that 131 originate in a module that matches one of these patterns. Whether a 132 frame is considered to originate in a certain module is determined 133 by the ``__name__`` in the frame globals. 134 135 .. versionadded:: 3.1 136 The *skip* argument. 137 138 The following methods of :class:`Bdb` normally don't need to be overridden. 139 140 .. method:: canonic(filename) 141 142 Return canonical form of *filename*. 143 144 For real file names, the canonical form is an operating-system-dependent, 145 :func:`case-normalized <os.path.normcase>` :func:`absolute path 146 <os.path.abspath>`. A *filename* with angle brackets, such as ``"<stdin>"`` 147 generated in interactive mode, is returned unchanged. 148 149 .. method:: reset() 150 151 Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and 152 :attr:`quitting` attributes with values ready to start debugging. 153 154 .. method:: trace_dispatch(frame, event, arg) 155 156 This function is installed as the trace function of debugged frames. Its 157 return value is the new trace function (in most cases, that is, itself). 158 159 The default implementation decides how to dispatch a frame, depending on 160 the type of event (passed as a string) that is about to be executed. 161 *event* can be one of the following: 162 163 * ``"line"``: A new line of code is going to be executed. 164 * ``"call"``: A function is about to be called, or another code block 165 entered. 166 * ``"return"``: A function or other code block is about to return. 167 * ``"exception"``: An exception has occurred. 168 * ``"c_call"``: A C function is about to be called. 169 * ``"c_return"``: A C function has returned. 170 * ``"c_exception"``: A C function has raised an exception. 171 172 For the Python events, specialized functions (see below) are called. For 173 the C events, no action is taken. 174 175 The *arg* parameter depends on the previous event. 176 177 See the documentation for :func:`sys.settrace` for more information on the 178 trace function. For more information on code and frame objects, refer to 179 :ref:`types`. 180 181 .. method:: dispatch_line(frame) 182 183 If the debugger should stop on the current line, invoke the 184 :meth:`user_line` method (which should be overridden in subclasses). 185 Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set 186 (which can be set from :meth:`user_line`). Return a reference to the 187 :meth:`trace_dispatch` method for further tracing in that scope. 188 189 .. method:: dispatch_call(frame, arg) 190 191 If the debugger should stop on this function call, invoke the 192 :meth:`user_call` method (which should be overridden in subclasses). 193 Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set 194 (which can be set from :meth:`user_call`). Return a reference to the 195 :meth:`trace_dispatch` method for further tracing in that scope. 196 197 .. method:: dispatch_return(frame, arg) 198 199 If the debugger should stop on this function return, invoke the 200 :meth:`user_return` method (which should be overridden in subclasses). 201 Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set 202 (which can be set from :meth:`user_return`). Return a reference to the 203 :meth:`trace_dispatch` method for further tracing in that scope. 204 205 .. method:: dispatch_exception(frame, arg) 206 207 If the debugger should stop at this exception, invokes the 208 :meth:`user_exception` method (which should be overridden in subclasses). 209 Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set 210 (which can be set from :meth:`user_exception`). Return a reference to the 211 :meth:`trace_dispatch` method for further tracing in that scope. 212 213 Normally derived classes don't override the following methods, but they may 214 if they want to redefine the definition of stopping and breakpoints. 215 216 .. method:: is_skipped_line(module_name) 217 218 Return True if *module_name* matches any skip pattern. 219 220 .. method:: stop_here(frame) 221 222 Return True if *frame* is below the starting frame in the stack. 223 224 .. method:: break_here(frame) 225 226 Return True if there is an effective breakpoint for this line. 227 228 Check whether a line or function breakpoint exists and is in effect. Delete temporary 229 breakpoints based on information from :func:`effective`. 230 231 .. method:: break_anywhere(frame) 232 233 Return True if any breakpoint exists for *frame*'s filename. 234 235 Derived classes should override these methods to gain control over debugger 236 operation. 237 238 .. method:: user_call(frame, argument_list) 239 240 Called from :meth:`dispatch_call` if a break might stop inside the 241 called function. 242 243 .. method:: user_line(frame) 244 245 Called from :meth:`dispatch_line` when either :meth:`stop_here` or 246 :meth:`break_here` returns ``True``. 247 248 .. method:: user_return(frame, return_value) 249 250 Called from :meth:`dispatch_return` when :meth:`stop_here` returns ``True``. 251 252 .. method:: user_exception(frame, exc_info) 253 254 Called from :meth:`dispatch_exception` when :meth:`stop_here` 255 returns ``True``. 256 257 .. method:: do_clear(arg) 258 259 Handle how a breakpoint must be removed when it is a temporary one. 260 261 This method must be implemented by derived classes. 262 263 264 Derived classes and clients can call the following methods to affect the 265 stepping state. 266 267 .. method:: set_step() 268 269 Stop after one line of code. 270 271 .. method:: set_next(frame) 272 273 Stop on the next line in or below the given frame. 274 275 .. method:: set_return(frame) 276 277 Stop when returning from the given frame. 278 279 .. method:: set_until(frame, lineno=None) 280 281 Stop when the line with the *lineno* greater than the current one is 282 reached or when returning from current frame. 283 284 .. method:: set_trace([frame]) 285 286 Start debugging from *frame*. If *frame* is not specified, debugging 287 starts from caller's frame. 288 289 .. method:: set_continue() 290 291 Stop only at breakpoints or when finished. If there are no breakpoints, 292 set the system trace function to ``None``. 293 294 .. method:: set_quit() 295 296 Set the :attr:`quitting` attribute to ``True``. This raises :exc:`BdbQuit` in 297 the next call to one of the :meth:`dispatch_\*` methods. 298 299 300 Derived classes and clients can call the following methods to manipulate 301 breakpoints. These methods return a string containing an error message if 302 something went wrong, or ``None`` if all is well. 303 304 .. method:: set_break(filename, lineno, temporary=False, cond=None, funcname=None) 305 306 Set a new breakpoint. If the *lineno* line doesn't exist for the 307 *filename* passed as argument, return an error message. The *filename* 308 should be in canonical form, as described in the :meth:`canonic` method. 309 310 .. method:: clear_break(filename, lineno) 311 312 Delete the breakpoints in *filename* and *lineno*. If none were set, 313 return an error message. 314 315 .. method:: clear_bpbynumber(arg) 316 317 Delete the breakpoint which has the index *arg* in the 318 :attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range, 319 return an error message. 320 321 .. method:: clear_all_file_breaks(filename) 322 323 Delete all breakpoints in *filename*. If none were set, return an error 324 message. 325 326 .. method:: clear_all_breaks() 327 328 Delete all existing breakpoints. If none were set, return an error 329 message. 330 331 .. method:: get_bpbynumber(arg) 332 333 Return a breakpoint specified by the given number. If *arg* is a string, 334 it will be converted to a number. If *arg* is a non-numeric string, if 335 the given breakpoint never existed or has been deleted, a 336 :exc:`ValueError` is raised. 337 338 .. versionadded:: 3.2 339 340 .. method:: get_break(filename, lineno) 341 342 Return True if there is a breakpoint for *lineno* in *filename*. 343 344 .. method:: get_breaks(filename, lineno) 345 346 Return all breakpoints for *lineno* in *filename*, or an empty list if 347 none are set. 348 349 .. method:: get_file_breaks(filename) 350 351 Return all breakpoints in *filename*, or an empty list if none are set. 352 353 .. method:: get_all_breaks() 354 355 Return all breakpoints that are set. 356 357 358 Derived classes and clients can call the following methods to get a data 359 structure representing a stack trace. 360 361 .. method:: get_stack(f, t) 362 363 Return a list of (frame, lineno) tuples in a stack trace, and a size. 364 365 The most recently called frame is last in the list. The size is the number 366 of frames below the frame where the debugger was invoked. 367 368 .. method:: format_stack_entry(frame_lineno, lprefix=': ') 369 370 Return a string with information about a stack entry, which is a 371 ``(frame, lineno)`` tuple. The return string contains: 372 373 * The canonical filename which contains the frame. 374 * The function name or ``"<lambda>"``. 375 * The input arguments. 376 * The return value. 377 * The line of code (if it exists). 378 379 380 The following two methods can be called by clients to use a debugger to debug 381 a :term:`statement`, given as a string. 382 383 .. method:: run(cmd, globals=None, locals=None) 384 385 Debug a statement executed via the :func:`exec` function. *globals* 386 defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*. 387 388 .. method:: runeval(expr, globals=None, locals=None) 389 390 Debug an expression executed via the :func:`eval` function. *globals* and 391 *locals* have the same meaning as in :meth:`run`. 392 393 .. method:: runctx(cmd, globals, locals) 394 395 For backwards compatibility. Calls the :meth:`run` method. 396 397 .. method:: runcall(func, /, *args, **kwds) 398 399 Debug a single function call, and return its result. 400 401 402Finally, the module defines the following functions: 403 404.. function:: checkfuncname(b, frame) 405 406 Return True if we should break here, depending on the way the 407 :class:`Breakpoint` *b* was set. 408 409 If it was set via line number, it checks if 410 :attr:`b.line <bdb.Breakpoint.line>` is the same as the one in *frame*. 411 If the breakpoint was set via 412 :attr:`function name <bdb.Breakpoint.funcname>`, we have to check we are in 413 the right *frame* (the right function) and if we are on its first executable 414 line. 415 416.. function:: effective(file, line, frame) 417 418 Return ``(active breakpoint, delete temporary flag)`` or ``(None, None)`` as the 419 breakpoint to act upon. 420 421 The *active breakpoint* is the first entry in 422 :attr:`bplist <bdb.Breakpoint.bplist>` for the 423 (:attr:`file <bdb.Breakpoint.file>`, :attr:`line <bdb.Breakpoint.line>`) 424 (which must exist) that is :attr:`enabled <bdb.Breakpoint.enabled>`, for 425 which :func:`checkfuncname` is True, and that has neither a False 426 :attr:`condition <bdb.Breakpoint.cond>` nor positive 427 :attr:`ignore <bdb.Breakpoint.ignore>` count. The *flag*, meaning that a 428 temporary breakpoint should be deleted, is False only when the 429 :attr:`cond <bdb.Breakpoint.cond>` cannot be evaluated (in which case, 430 :attr:`ignore <bdb.Breakpoint.ignore>` count is ignored). 431 432 If no such entry exists, then (None, None) is returned. 433 434 435.. function:: set_trace() 436 437 Start debugging with a :class:`Bdb` instance from caller's frame. 438