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)
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_module(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
411 Finally, 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.