1
:mod:`bdb` --- Debugger framework
2
=================================
5
:synopsis: Debugger framework.
7
**Source code:** :source:`Lib/bdb.py`
11
The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
12
or managing execution via the debugger.
14
The following exception is defined:
16
.. exception:: BdbQuit
18
Exception raised by the :class:`Bdb` class for quitting the debugger.
21
The :mod:`bdb` module also defines two classes:
23
.. class:: Breakpoint(self, file, line, temporary=0, cond=None, funcname=None)
25
This class implements temporary breakpoints, ignore counts, disabling and
26
(re-)enabling, and conditionals.
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.
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
38
:class:`Breakpoint` instances have the following methods:
40
.. method:: deleteMe()
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
49
Mark the breakpoint as enabled.
54
Mark the breakpoint as disabled.
57
.. method:: bpformat()
59
Return a string with all the information about the breakpoint, nicely
62
* The breakpoint number.
63
* If it is temporary or not.
64
* Its file,line position.
65
* The condition that causes a break.
66
* If it must be ignored the next N times.
67
* The breakpoint hit count.
71
.. method:: bpprint(out=None)
73
Print the output of :meth:`bpformat` to the file *out*, or if it is
74
``None``, to standard output.
77
.. class:: Bdb(skip=None)
79
The :class:`Bdb` class acts as a generic Python debugger base class.
81
This class takes care of the details of the trace facility; a derived class
82
should implement user interaction. The standard debugger class
83
(:class:`pdb.Pdb`) is an example.
85
The *skip* argument, if given, must be an iterable of glob-style
86
module name patterns. The debugger will not step into frames that
87
originate in a module that matches one of these patterns. Whether a
88
frame is considered to originate in a certain module is determined
89
by the ``__name__`` in the frame globals.
94
The following methods of :class:`Bdb` normally don't need to be overridden.
96
.. method:: canonic(filename)
98
Auxiliary method for getting a filename in a canonical form, that is, as a
99
case-normalized (on case-insensitive filesystems) absolute path, stripped
100
of surrounding angle brackets.
104
Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
105
:attr:`quitting` attributes with values ready to start debugging.
107
.. method:: trace_dispatch(frame, event, arg)
109
This function is installed as the trace function of debugged frames. Its
110
return value is the new trace function (in most cases, that is, itself).
112
The default implementation decides how to dispatch a frame, depending on
113
the type of event (passed as a string) that is about to be executed.
114
*event* can be one of the following:
116
* ``"line"``: A new line of code is going to be executed.
117
* ``"call"``: A function is about to be called, or another code block
119
* ``"return"``: A function or other code block is about to return.
120
* ``"exception"``: An exception has occurred.
121
* ``"c_call"``: A C function is about to be called.
122
* ``"c_return"``: A C function has returned.
123
* ``"c_exception"``: A C function has raised an exception.
125
For the Python events, specialized functions (see below) are called. For
126
the C events, no action is taken.
128
The *arg* parameter depends on the previous event.
130
See the documentation for :func:`sys.settrace` for more information on the
131
trace function. For more information on code and frame objects, refer to
134
.. method:: dispatch_line(frame)
136
If the debugger should stop on the current line, invoke the
137
:meth:`user_line` 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_line`). Return a reference to the
140
:meth:`trace_dispatch` method for further tracing in that scope.
142
.. method:: dispatch_call(frame, arg)
144
If the debugger should stop on this function call, invoke the
145
:meth:`user_call` 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_call`). Return a reference to the
148
:meth:`trace_dispatch` method for further tracing in that scope.
150
.. method:: dispatch_return(frame, arg)
152
If the debugger should stop on this function return, invoke the
153
:meth:`user_return` 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_return`). Return a reference to the
156
:meth:`trace_dispatch` method for further tracing in that scope.
158
.. method:: dispatch_exception(frame, arg)
160
If the debugger should stop at this exception, invokes the
161
:meth:`user_exception` method (which should be overridden in subclasses).
162
Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
163
(which can be set from :meth:`user_exception`). Return a reference to the
164
:meth:`trace_dispatch` method for further tracing in that scope.
166
Normally derived classes don't override the following methods, but they may
167
if they want to redefine the definition of stopping and breakpoints.
169
.. method:: stop_here(frame)
171
This method checks if the *frame* is somewhere below :attr:`botframe` in
172
the call stack. :attr:`botframe` is the frame in which debugging started.
174
.. method:: break_here(frame)
176
This method checks if there is a breakpoint in the filename and line
177
belonging to *frame* or, at least, in the current function. If the
178
breakpoint is a temporary one, this method deletes it.
180
.. method:: break_anywhere(frame)
182
This method checks if there is a breakpoint in the filename of the current
185
Derived classes should override these methods to gain control over debugger
188
.. method:: user_call(frame, argument_list)
190
This method is called from :meth:`dispatch_call` when there is the
191
possibility that a break might be necessary anywhere inside the called
194
.. method:: user_line(frame)
196
This method is called from :meth:`dispatch_line` when either
197
:meth:`stop_here` or :meth:`break_here` yields ``True``.
199
.. method:: user_return(frame, return_value)
201
This method is called from :meth:`dispatch_return` when :meth:`stop_here`
204
.. method:: user_exception(frame, exc_info)
206
This method is called from :meth:`dispatch_exception` when
207
:meth:`stop_here` yields ``True``.
209
.. method:: do_clear(arg)
211
Handle how a breakpoint must be removed when it is a temporary one.
213
This method must be implemented by derived classes.
216
Derived classes and clients can call the following methods to affect the
219
.. method:: set_step()
221
Stop after one line of code.
223
.. method:: set_next(frame)
225
Stop on the next line in or below the given frame.
227
.. method:: set_return(frame)
229
Stop when returning from the given frame.
231
.. method:: set_until(frame)
233
Stop when the line with the line no greater than the current one is
234
reached or when returning from current frame.
236
.. method:: set_trace([frame])
238
Start debugging from *frame*. If *frame* is not specified, debugging
239
starts from caller's frame.
241
.. method:: set_continue()
243
Stop only at breakpoints or when finished. If there are no breakpoints,
244
set the system trace function to ``None``.
246
.. method:: set_quit()
248
Set the :attr:`quitting` attribute to ``True``. This raises :exc:`BdbQuit` in
249
the next call to one of the :meth:`dispatch_\*` methods.
252
Derived classes and clients can call the following methods to manipulate
253
breakpoints. These methods return a string containing an error message if
254
something went wrong, or ``None`` if all is well.
256
.. method:: set_break(filename, lineno, temporary=0, cond, funcname)
258
Set a new breakpoint. If the *lineno* line doesn't exist for the
259
*filename* passed as argument, return an error message. The *filename*
260
should be in canonical form, as described in the :meth:`canonic` method.
262
.. method:: clear_break(filename, lineno)
264
Delete the breakpoints in *filename* and *lineno*. If none were set, an
265
error message is returned.
267
.. method:: clear_bpbynumber(arg)
269
Delete the breakpoint which has the index *arg* in the
270
:attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range,
271
return an error message.
273
.. method:: clear_all_file_breaks(filename)
275
Delete all breakpoints in *filename*. If none were set, an error message
278
.. method:: clear_all_breaks()
280
Delete all existing breakpoints.
282
.. method:: get_bpbynumber(arg)
284
Return a breakpoint specified by the given number. If *arg* is a string,
285
it will be converted to a number. If *arg* is a non-numeric string, if
286
the given breakpoint never existed or has been deleted, a
287
:exc:`ValueError` is raised.
289
.. versionadded:: 3.2
291
.. method:: get_break(filename, lineno)
293
Check if there is a breakpoint for *lineno* of *filename*.
295
.. method:: get_breaks(filename, lineno)
297
Return all breakpoints for *lineno* in *filename*, or an empty list if
300
.. method:: get_file_breaks(filename)
302
Return all breakpoints in *filename*, or an empty list if none are set.
304
.. method:: get_all_breaks()
306
Return all breakpoints that are set.
309
Derived classes and clients can call the following methods to get a data
310
structure representing a stack trace.
312
.. method:: get_stack(f, t)
314
Get a list of records for a frame and all higher (calling) and lower
315
frames, and the size of the higher part.
317
.. method:: format_stack_entry(frame_lineno, lprefix=': ')
319
Return a string with information about a stack entry, identified by a
320
``(frame, lineno)`` tuple:
322
* The canonical form of the filename which contains the frame.
323
* The function name, or ``"<lambda>"``.
324
* The input arguments.
326
* The line of code (if it exists).
329
The following two methods can be called by clients to use a debugger to debug
330
a :term:`statement`, given as a string.
332
.. method:: run(cmd, globals=None, locals=None)
334
Debug a statement executed via the :func:`exec` function. *globals*
335
defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
337
.. method:: runeval(expr, globals=None, locals=None)
339
Debug an expression executed via the :func:`eval` function. *globals* and
340
*locals* have the same meaning as in :meth:`run`.
342
.. method:: runctx(cmd, globals, locals)
344
For backwards compatibility. Calls the :meth:`run` method.
346
.. method:: runcall(func, *args, **kwds)
348
Debug a single function call, and return its result.
351
Finally, the module defines the following functions:
353
.. function:: checkfuncname(b, frame)
355
Check whether we should break here, depending on the way the breakpoint *b*
358
If it was set via line number, it checks if ``b.line`` is the same as the one
359
in the frame also passed as argument. If the breakpoint was set via function
360
name, we have to check we are in the right frame (the right function) and if
361
we are in its first executable line.
363
.. function:: effective(file, line, frame)
365
Determine if there is an effective (active) breakpoint at this line of code.
366
Return a tuple of the breakpoint and a boolean that indicates if it is ok
367
to delete a temporary breakpoint. Return ``(None, None)`` if there is no
370
.. function:: set_trace()
372
Start debugging with a :class:`Bdb` instance from caller's frame.
added
removed
python-3.5.2-docs-html/_sources/library/bdb.txt
