Debian Codegraph @

Doc/library/bdb.rst

raw
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
11 The :mod:`!bdb` module handles basic debugger functions, like setting breakpoints
12 or managing execution via the debugger.
13
14 The following exception is defined:
15
16 .. exception:: BdbQuit
17
18 Exception raised by the :class:`Bdb` class for quitting the debugger.
19
20
21 The :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, backend='settrace')
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 The *backend* argument specifies the backend to use for :class:`Bdb`. It
136 can be either ``'settrace'`` or ``'monitoring'``. ``'settrace'`` uses
137 :func:`sys.settrace` which has the best backward compatibility. The
138 ``'monitoring'`` backend uses the new :mod:`sys.monitoring` that was
139 introduced in Python 3.12, which can be much more efficient because it
140 can disable unused events. We are trying to keep the exact interfaces
141 for both backends, but there are some differences. The debugger developers
142 are encouraged to use the ``'monitoring'`` backend to achieve better
143 performance.
144
145 .. versionchanged:: 3.1
146 Added the *skip* parameter.
147
148 .. versionchanged:: 3.14
149 Added the *backend* parameter.
150
151 The following methods of :class:`Bdb` normally don't need to be overridden.
152
153 .. method:: canonic(filename)
154
155 Return canonical form of *filename*.
156
157 For real file names, the canonical form is an operating-system-dependent,
158 :func:`case-normalized <os.path.normcase>` :func:`absolute path
159 <os.path.abspath>`. A *filename* with angle brackets, such as ``"<stdin>"``
160 generated in interactive mode, is returned unchanged.
161
162 .. method:: start_trace(self)
163
164 Start tracing. For ``'settrace'`` backend, this method is equivalent to
165 ``sys.settrace(self.trace_dispatch)``
166
167 .. versionadded:: 3.14
168
169 .. method:: stop_trace(self)
170
171 Stop tracing. For ``'settrace'`` backend, this method is equivalent to
172 ``sys.settrace(None)``
173
174 .. versionadded:: 3.14
175
176 .. method:: reset()
177
178 Set the :attr:`!botframe`, :attr:`!stopframe`, :attr:`!returnframe` and
179 :attr:`quitting <Bdb.set_quit>` attributes with values ready to start debugging.
180
181 .. method:: trace_dispatch(frame, event, arg)
182
183 This function is installed as the trace function of debugged frames. Its
184 return value is the new trace function (in most cases, that is, itself).
185
186 The default implementation decides how to dispatch a frame, depending on
187 the type of event (passed as a string) that is about to be executed.
188 *event* can be one of the following:
189
190 * ``"line"``: A new line of code is going to be executed.
191 * ``"call"``: A function is about to be called, or another code block
192 entered.
193 * ``"return"``: A function or other code block is about to return.
194 * ``"exception"``: An exception has occurred.
195 * ``"c_call"``: A C function is about to be called.
196 * ``"c_return"``: A C function has returned.
197 * ``"c_exception"``: A C function has raised an exception.
198
199 For the Python events, specialized functions (see below) are called. For
200 the C events, no action is taken.
201
202 The *arg* parameter depends on the previous event.
203
204 See the documentation for :func:`sys.settrace` for more information on the
205 trace function. For more information on code and frame objects, refer to
206 :ref:`types`.
207
208 .. method:: dispatch_line(frame)
209
210 If the debugger should stop on the current line, invoke the
211 :meth:`user_line` method (which should be overridden in subclasses).
212 Raise a :exc:`BdbQuit` exception if the :attr:`quitting <Bdb.set_quit>` flag is set
213 (which can be set from :meth:`user_line`). Return a reference to the
214 :meth:`trace_dispatch` method for further tracing in that scope.
215
216 .. method:: dispatch_call(frame, arg)
217
218 If the debugger should stop on this function call, invoke the
219 :meth:`user_call` method (which should be overridden in subclasses).
220 Raise a :exc:`BdbQuit` exception if the :attr:`quitting <Bdb.set_quit>` flag is set
221 (which can be set from :meth:`user_call`). Return a reference to the
222 :meth:`trace_dispatch` method for further tracing in that scope.
223
224 .. method:: dispatch_return(frame, arg)
225
226 If the debugger should stop on this function return, invoke the
227 :meth:`user_return` method (which should be overridden in subclasses).
228 Raise a :exc:`BdbQuit` exception if the :attr:`quitting <Bdb.set_quit>` flag is set
229 (which can be set from :meth:`user_return`). Return a reference to the
230 :meth:`trace_dispatch` method for further tracing in that scope.
231
232 .. method:: dispatch_exception(frame, arg)
233
234 If the debugger should stop at this exception, invokes the
235 :meth:`user_exception` method (which should be overridden in subclasses).
236 Raise a :exc:`BdbQuit` exception if the :attr:`quitting <Bdb.set_quit>` flag is set
237 (which can be set from :meth:`user_exception`). Return a reference to the
238 :meth:`trace_dispatch` method for further tracing in that scope.
239
240 Normally derived classes don't override the following methods, but they may
241 if they want to redefine the definition of stopping and breakpoints.
242
243 .. method:: is_skipped_module(module_name)
244
245 Return ``True`` if *module_name* matches any skip pattern.
246
247 .. method:: stop_here(frame)
248
249 Return ``True`` if *frame* is below the starting frame in the stack.
250
251 .. method:: break_here(frame)
252
253 Return ``True`` if there is an effective breakpoint for this line.
254
255 Check whether a line or function breakpoint exists and is in effect. Delete temporary
256 breakpoints based on information from :func:`effective`.
257
258 .. method:: break_anywhere(frame)
259
260 Return ``True`` if any breakpoint exists for *frame*'s filename.
261
262 Derived classes should override these methods to gain control over debugger
263 operation.
264
265 .. method:: user_call(frame, argument_list)
266
267 Called from :meth:`dispatch_call` if a break might stop inside the
268 called function.
269
270 *argument_list* is not used anymore and will always be ``None``.
271 The argument is kept for backwards compatibility.
272
273 .. method:: user_line(frame)
274
275 Called from :meth:`dispatch_line` when either :meth:`stop_here` or
276 :meth:`break_here` returns ``True``.
277
278 .. method:: user_return(frame, return_value)
279
280 Called from :meth:`dispatch_return` when :meth:`stop_here` returns ``True``.
281
282 .. method:: user_exception(frame, exc_info)
283
284 Called from :meth:`dispatch_exception` when :meth:`stop_here`
285 returns ``True``.
286
287 .. method:: do_clear(arg)
288
289 Handle how a breakpoint must be removed when it is a temporary one.
290
291 This method must be implemented by derived classes.
292
293
294 Derived classes and clients can call the following methods to affect the
295 stepping state.
296
297 .. method:: set_step()
298
299 Stop after one line of code.
300
301 .. method:: set_next(frame)
302
303 Stop on the next line in or below the given frame.
304
305 .. method:: set_return(frame)
306
307 Stop when returning from the given frame.
308
309 .. method:: set_until(frame, lineno=None)
310
311 Stop when the line with the *lineno* greater than the current one is
312 reached or when returning from current frame.
313
314 .. method:: set_trace([frame])
315
316 Start debugging from *frame*. If *frame* is not specified, debugging
317 starts from caller's frame.
318
319 .. versionchanged:: 3.13
320 :func:`set_trace` will enter the debugger immediately, rather than
321 on the next line of code to be executed.
322
323 .. method:: set_continue()
324
325 Stop only at breakpoints or when finished. If there are no breakpoints,
326 set the system trace function to ``None``.
327
328 .. method:: set_quit()
329
330 .. index:: single: quitting (bdb.Bdb attribute)
331
332 Set the :attr:`!quitting` attribute to ``True``. This raises :exc:`BdbQuit` in
333 the next call to one of the :meth:`!dispatch_\*` methods.
334
335
336 Derived classes and clients can call the following methods to manipulate
337 breakpoints. These methods return a string containing an error message if
338 something went wrong, or ``None`` if all is well.
339
340 .. method:: set_break(filename, lineno, temporary=False, cond=None, funcname=None)
341
342 Set a new breakpoint. If the *lineno* line doesn't exist for the
343 *filename* passed as argument, return an error message. The *filename*
344 should be in canonical form, as described in the :meth:`canonic` method.
345
346 .. method:: clear_break(filename, lineno)
347
348 Delete the breakpoints in *filename* and *lineno*. If none were set,
349 return an error message.
350
351 .. method:: clear_bpbynumber(arg)
352
353 Delete the breakpoint which has the index *arg* in the
354 :attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range,
355 return an error message.
356
357 .. method:: clear_all_file_breaks(filename)
358
359 Delete all breakpoints in *filename*. If none were set, return an error
360 message.
361
362 .. method:: clear_all_breaks()
363
364 Delete all existing breakpoints. If none were set, return an error
365 message.
366
367 .. method:: get_bpbynumber(arg)
368
369 Return a breakpoint specified by the given number. If *arg* is a string,
370 it will be converted to a number. If *arg* is a non-numeric string, if
371 the given breakpoint never existed or has been deleted, a
372 :exc:`ValueError` is raised.
373
374 .. versionadded:: 3.2
375
376 .. method:: get_break(filename, lineno)
377
378 Return ``True`` if there is a breakpoint for *lineno* in *filename*.
379
380 .. method:: get_breaks(filename, lineno)
381
382 Return all breakpoints for *lineno* in *filename*, or an empty list if
383 none are set.
384
385 .. method:: get_file_breaks(filename)
386
387 Return all breakpoints in *filename*, or an empty list if none are set.
388
389 .. method:: get_all_breaks()
390
391 Return all breakpoints that are set.
392
393
394 Derived classes and clients can call the following methods to disable and
395 restart events to achieve better performance. These methods only work
396 when using the ``'monitoring'`` backend.
397
398 .. method:: disable_current_event()
399
400 Disable the current event until the next time :func:`restart_events` is
401 called. This is helpful when the debugger is not interested in the current
402 line.
403
404 .. versionadded:: 3.14
405
406 .. method:: restart_events()
407
408 Restart all the disabled events. This function is automatically called in
409 ``dispatch_*`` methods after ``user_*`` methods are called. If the
410 ``dispatch_*`` methods are not overridden, the disabled events will be
411 restarted after each user interaction.
412
413 .. versionadded:: 3.14
414
415
416 Derived classes and clients can call the following methods to get a data
417 structure representing a stack trace.
418
419 .. method:: get_stack(f, t)
420
421 Return a list of (frame, lineno) tuples in a stack trace, and a size.
422
423 The most recently called frame is last in the list. The size is the number
424 of frames below the frame where the debugger was invoked.
425
426 .. method:: format_stack_entry(frame_lineno, lprefix=': ')
427
428 Return a string with information about a stack entry, which is a
429 ``(frame, lineno)`` tuple. The return string contains:
430
431 * The canonical filename which contains the frame.
432 * The function name or ``"<lambda>"``.
433 * The input arguments.
434 * The return value.
435 * The line of code (if it exists).
436
437
438 The following two methods can be called by clients to use a debugger to debug
439 a :term:`statement`, given as a string.
440
441 .. method:: run(cmd, globals=None, locals=None)
442
443 Debug a statement executed via the :func:`exec` function. *globals*
444 defaults to :attr:`!__main__.__dict__`, *locals* defaults to *globals*.
445
446 .. method:: runeval(expr, globals=None, locals=None)
447
448 Debug an expression executed via the :func:`eval` function. *globals* and
449 *locals* have the same meaning as in :meth:`run`.
450
451 .. method:: runctx(cmd, globals, locals)
452
453 For backwards compatibility. Calls the :meth:`run` method.
454
455 .. method:: runcall(func, /, *args, **kwds)
456
457 Debug a single function call, and return its result.
458
459
460 Finally, the module defines the following functions:
461
462 .. function:: checkfuncname(b, frame)
463
464 Return ``True`` if we should break here, depending on the way the
465 :class:`Breakpoint` *b* was set.
466
467 If it was set via line number, it checks if
468 :attr:`b.line <bdb.Breakpoint.line>` is the same as the one in *frame*.
469 If the breakpoint was set via
470 :attr:`function name <bdb.Breakpoint.funcname>`, we have to check we are in
471 the right *frame* (the right function) and if we are on its first executable
472 line.
473
474 .. function:: effective(file, line, frame)
475
476 Return ``(active breakpoint, delete temporary flag)`` or ``(None, None)`` as the
477 breakpoint to act upon.
478
479 The *active breakpoint* is the first entry in
480 :attr:`bplist <bdb.Breakpoint.bplist>` for the
481 (:attr:`file <bdb.Breakpoint.file>`, :attr:`line <bdb.Breakpoint.line>`)
482 (which must exist) that is :attr:`enabled <bdb.Breakpoint.enabled>`, for
483 which :func:`checkfuncname` is true, and that has neither a false
484 :attr:`condition <bdb.Breakpoint.cond>` nor positive
485 :attr:`ignore <bdb.Breakpoint.ignore>` count. The *flag*, meaning that a
486 temporary breakpoint should be deleted, is ``False`` only when the
487 :attr:`cond <bdb.Breakpoint.cond>` cannot be evaluated (in which case,
488 :attr:`ignore <bdb.Breakpoint.ignore>` count is ignored).
489
490 If no such entry exists, then ``(None, None)`` is returned.
491
492
493 .. function:: set_trace()
494
495 Start debugging with a :class:`Bdb` instance from caller's frame.