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 .. versionchanged:: 3.1 136 Added the *skip* parameter. 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 <Bdb.set_quit>` 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:`quitting <Bdb.set_quit>` 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:`quitting <Bdb.set_quit>` 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:`quitting <Bdb.set_quit>` 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:`quitting <Bdb.set_quit>` 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 *argument_list* is not used anymore and will always be ``None``. 244 The argument is kept for backwards compatibility. 245 246 .. method:: user_line(frame) 247 248 Called from :meth:`dispatch_line` when either :meth:`stop_here` or 249 :meth:`break_here` returns ``True``. 250 251 .. method:: user_return(frame, return_value) 252 253 Called from :meth:`dispatch_return` when :meth:`stop_here` returns ``True``. 254 255 .. method:: user_exception(frame, exc_info) 256 257 Called from :meth:`dispatch_exception` when :meth:`stop_here` 258 returns ``True``. 259 260 .. method:: do_clear(arg) 261 262 Handle how a breakpoint must be removed when it is a temporary one. 263 264 This method must be implemented by derived classes. 265 266 267 Derived classes and clients can call the following methods to affect the 268 stepping state. 269 270 .. method:: set_step() 271 272 Stop after one line of code. 273 274 .. method:: set_next(frame) 275 276 Stop on the next line in or below the given frame. 277 278 .. method:: set_return(frame) 279 280 Stop when returning from the given frame. 281 282 .. method:: set_until(frame, lineno=None) 283 284 Stop when the line with the *lineno* greater than the current one is 285 reached or when returning from current frame. 286 287 .. method:: set_trace([frame]) 288 289 Start debugging from *frame*. If *frame* is not specified, debugging 290 starts from caller's frame. 291 292 .. versionchanged:: 3.13 293 :func:`set_trace` will enter the debugger immediately, rather than 294 on the next line of code to be executed. 295 296 .. method:: set_continue() 297 298 Stop only at breakpoints or when finished. If there are no breakpoints, 299 set the system trace function to ``None``. 300 301 .. method:: set_quit() 302 303 .. index:: single: quitting (bdb.Bdb attribute) 304 305 Set the :attr:`!quitting` attribute to ``True``. This raises :exc:`BdbQuit` in 306 the next call to one of the :meth:`!dispatch_\*` methods. 307 308 309 Derived classes and clients can call the following methods to manipulate 310 breakpoints. These methods return a string containing an error message if 311 something went wrong, or ``None`` if all is well. 312 313 .. method:: set_break(filename, lineno, temporary=False, cond=None, funcname=None) 314 315 Set a new breakpoint. If the *lineno* line doesn't exist for the 316 *filename* passed as argument, return an error message. The *filename* 317 should be in canonical form, as described in the :meth:`canonic` method. 318 319 .. method:: clear_break(filename, lineno) 320 321 Delete the breakpoints in *filename* and *lineno*. If none were set, 322 return an error message. 323 324 .. method:: clear_bpbynumber(arg) 325 326 Delete the breakpoint which has the index *arg* in the 327 :attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range, 328 return an error message. 329 330 .. method:: clear_all_file_breaks(filename) 331 332 Delete all breakpoints in *filename*. If none were set, return an error 333 message. 334 335 .. method:: clear_all_breaks() 336 337 Delete all existing breakpoints. If none were set, return an error 338 message. 339 340 .. method:: get_bpbynumber(arg) 341 342 Return a breakpoint specified by the given number. If *arg* is a string, 343 it will be converted to a number. If *arg* is a non-numeric string, if 344 the given breakpoint never existed or has been deleted, a 345 :exc:`ValueError` is raised. 346 347 .. versionadded:: 3.2 348 349 .. method:: get_break(filename, lineno) 350 351 Return ``True`` if there is a breakpoint for *lineno* in *filename*. 352 353 .. method:: get_breaks(filename, lineno) 354 355 Return all breakpoints for *lineno* in *filename*, or an empty list if 356 none are set. 357 358 .. method:: get_file_breaks(filename) 359 360 Return all breakpoints in *filename*, or an empty list if none are set. 361 362 .. method:: get_all_breaks() 363 364 Return all breakpoints that are set. 365 366 367 Derived classes and clients can call the following methods to get a data 368 structure representing a stack trace. 369 370 .. method:: get_stack(f, t) 371 372 Return a list of (frame, lineno) tuples in a stack trace, and a size. 373 374 The most recently called frame is last in the list. The size is the number 375 of frames below the frame where the debugger was invoked. 376 377 .. method:: format_stack_entry(frame_lineno, lprefix=': ') 378 379 Return a string with information about a stack entry, which is a 380 ``(frame, lineno)`` tuple. The return string contains: 381 382 * The canonical filename which contains the frame. 383 * The function name or ``"<lambda>"``. 384 * The input arguments. 385 * The return value. 386 * The line of code (if it exists). 387 388 389 The following two methods can be called by clients to use a debugger to debug 390 a :term:`statement`, given as a string. 391 392 .. method:: run(cmd, globals=None, locals=None) 393 394 Debug a statement executed via the :func:`exec` function. *globals* 395 defaults to :attr:`!__main__.__dict__`, *locals* defaults to *globals*. 396 397 .. method:: runeval(expr, globals=None, locals=None) 398 399 Debug an expression executed via the :func:`eval` function. *globals* and 400 *locals* have the same meaning as in :meth:`run`. 401 402 .. method:: runctx(cmd, globals, locals) 403 404 For backwards compatibility. Calls the :meth:`run` method. 405 406 .. method:: runcall(func, /, *args, **kwds) 407 408 Debug a single function call, and return its result. 409 410 411Finally, the module defines the following functions: 412 413.. function:: checkfuncname(b, frame) 414 415 Return ``True`` if we should break here, depending on the way the 416 :class:`Breakpoint` *b* was set. 417 418 If it was set via line number, it checks if 419 :attr:`b.line <bdb.Breakpoint.line>` is the same as the one in *frame*. 420 If the breakpoint was set via 421 :attr:`function name <bdb.Breakpoint.funcname>`, we have to check we are in 422 the right *frame* (the right function) and if we are on its first executable 423 line. 424 425.. function:: effective(file, line, frame) 426 427 Return ``(active breakpoint, delete temporary flag)`` or ``(None, None)`` as the 428 breakpoint to act upon. 429 430 The *active breakpoint* is the first entry in 431 :attr:`bplist <bdb.Breakpoint.bplist>` for the 432 (:attr:`file <bdb.Breakpoint.file>`, :attr:`line <bdb.Breakpoint.line>`) 433 (which must exist) that is :attr:`enabled <bdb.Breakpoint.enabled>`, for 434 which :func:`checkfuncname` is true, and that has neither a false 435 :attr:`condition <bdb.Breakpoint.cond>` nor positive 436 :attr:`ignore <bdb.Breakpoint.ignore>` count. The *flag*, meaning that a 437 temporary breakpoint should be deleted, is ``False`` only when the 438 :attr:`cond <bdb.Breakpoint.cond>` cannot be evaluated (in which case, 439 :attr:`ignore <bdb.Breakpoint.ignore>` count is ignored). 440 441 If no such entry exists, then ``(None, None)`` is returned. 442 443 444.. function:: set_trace() 445 446 Start debugging with a :class:`Bdb` instance from caller's frame. 447