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=0, 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 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.
32
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
36   counts a hit.
37
38   :class:`Breakpoint` instances have the following methods:
39
40   .. method:: deleteMe()
41
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
44      file/line.
45
46
47   .. method:: enable()
48
49      Mark the breakpoint as enabled.
50
51
52   .. method:: disable()
53
54      Mark the breakpoint as disabled.
55
56
57   .. method:: bpformat()
58
59      Return a string with all the information about the breakpoint, nicely
60      formatted:
61
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.
68
69      .. versionadded:: 3.2
70
71   .. method:: bpprint(out=None)
72
73      Print the output of :meth:`bpformat` to the file *out*, or if it is
74      ``None``, to standard output.
75
76
77.. class:: Bdb(skip=None)
78
79   The :class:`Bdb` class acts as a generic Python debugger base class.
80
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.
84
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.
90
91   .. versionadded:: 3.1
92      The *skip* argument.
93
94   The following methods of :class:`Bdb` normally don't need to be overridden.
95
96   .. method:: canonic(filename)
97
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.
101
102   .. method:: reset()
103
104      Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
105      :attr:`quitting` attributes with values ready to start debugging.
106
107   .. method:: trace_dispatch(frame, event, arg)
108
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).
111
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:
115
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
118        entered.
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.
124
125      For the Python events, specialized functions (see below) are called.  For
126      the C events, no action is taken.
127
128      The *arg* parameter depends on the previous event.
129
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
132      :ref:`types`.
133
134   .. method:: dispatch_line(frame)
135
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.
141
142   .. method:: dispatch_call(frame, arg)
143
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.
149
150   .. method:: dispatch_return(frame, arg)
151
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.
157
158   .. method:: dispatch_exception(frame, arg)
159
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.
165
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.
168
169   .. method:: stop_here(frame)
170
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.
173
174   .. method:: break_here(frame)
175
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.
179
180   .. method:: break_anywhere(frame)
181
182      This method checks if there is a breakpoint in the filename of the current
183      frame.
184
185   Derived classes should override these methods to gain control over debugger
186   operation.
187
188   .. method:: user_call(frame, argument_list)
189
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
192      function.
193
194   .. method:: user_line(frame)
195
196      This method is called from :meth:`dispatch_line` when either
197      :meth:`stop_here` or :meth:`break_here` yields ``True``.
198
199   .. method:: user_return(frame, return_value)
200
201      This method is called from :meth:`dispatch_return` when :meth:`stop_here`
202      yields ``True``.
203
204   .. method:: user_exception(frame, exc_info)
205
206      This method is called from :meth:`dispatch_exception` when
207      :meth:`stop_here` yields ``True``.
208
209   .. method:: do_clear(arg)
210
211      Handle how a breakpoint must be removed when it is a temporary one.
212
213      This method must be implemented by derived classes.
214
215
216   Derived classes and clients can call the following methods to affect the
217   stepping state.
218
219   .. method:: set_step()
220
221      Stop after one line of code.
222
223   .. method:: set_next(frame)
224
225      Stop on the next line in or below the given frame.
226
227   .. method:: set_return(frame)
228
229      Stop when returning from the given frame.
230
231   .. method:: set_until(frame)
232
233      Stop when the line with the line no greater than the current one is
234      reached or when returning from current frame.
235
236   .. method:: set_trace([frame])
237
238      Start debugging from *frame*.  If *frame* is not specified, debugging
239      starts from caller's frame.
240
241   .. method:: set_continue()
242
243      Stop only at breakpoints or when finished.  If there are no breakpoints,
244      set the system trace function to ``None``.
245
246   .. method:: set_quit()
247
248      Set the :attr:`quitting` attribute to ``True``.  This raises :exc:`BdbQuit` in
249      the next call to one of the :meth:`dispatch_\*` methods.
250
251
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.
255
256   .. method:: set_break(filename, lineno, temporary=0, cond, funcname)
257
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.
261
262   .. method:: clear_break(filename, lineno)
263
264      Delete the breakpoints in *filename* and *lineno*.  If none were set, an
265      error message is returned.
266
267   .. method:: clear_bpbynumber(arg)
268
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.
272
273   .. method:: clear_all_file_breaks(filename)
274
275      Delete all breakpoints in *filename*.  If none were set, an error message
276      is returned.
277
278   .. method:: clear_all_breaks()
279
280      Delete all existing breakpoints.
281
282   .. method:: get_bpbynumber(arg)
283
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.
288
289      .. versionadded:: 3.2
290
291   .. method:: get_break(filename, lineno)
292
293      Check if there is a breakpoint for *lineno* of *filename*.
294
295   .. method:: get_breaks(filename, lineno)
296
297      Return all breakpoints for *lineno* in *filename*, or an empty list if
298      none are set.
299
300   .. method:: get_file_breaks(filename)
301
302      Return all breakpoints in *filename*, or an empty list if none are set.
303
304   .. method:: get_all_breaks()
305
306      Return all breakpoints that are set.
307
308
309   Derived classes and clients can call the following methods to get a data
310   structure representing a stack trace.
311
312   .. method:: get_stack(f, t)
313
314      Get a list of records for a frame and all higher (calling) and lower
315      frames, and the size of the higher part.
316
317   .. method:: format_stack_entry(frame_lineno, lprefix=': ')
318
319      Return a string with information about a stack entry, identified by a
320      ``(frame, lineno)`` tuple:
321
322      * The canonical form of the filename which contains the frame.
323      * The function name, or ``"<lambda>"``.
324      * The input arguments.
325      * The return value.
326      * The line of code (if it exists).
327
328
329   The following two methods can be called by clients to use a debugger to debug
330   a :term:`statement`, given as a string.
331
332   .. method:: run(cmd, globals=None, locals=None)
333
334      Debug a statement executed via the :func:`exec` function.  *globals*
335      defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
336
337   .. method:: runeval(expr, globals=None, locals=None)
338
339      Debug an expression executed via the :func:`eval` function.  *globals* and
340      *locals* have the same meaning as in :meth:`run`.
341
342   .. method:: runctx(cmd, globals, locals)
343
344      For backwards compatibility.  Calls the :meth:`run` method.
345
346   .. method:: runcall(func, *args, **kwds)
347
348      Debug a single function call, and return its result.
349
350
351Finally, the module defines the following functions:
352
353.. function:: checkfuncname(b, frame)
354
355   Check whether we should break here, depending on the way the breakpoint *b*
356   was set.
357
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.
362
363.. function:: effective(file, line, frame)
364
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
368   matching breakpoint.
369
370.. function:: set_trace()
371
372   Start debugging with a :class:`Bdb` instance from caller's frame.
373