bdb — Debugger framework¶

Source code:Lib/bdb.py

Thebdb module handles basic debugger functions, like setting breakpointsor managing execution via the debugger.

The following exception is defined:

exceptionbdb.BdbQuit¶

Exception raised by theBdb class for quitting the debugger.

Thebdb module also defines two classes:

classbdb.Breakpoint(self,file,line,temporary=False,cond=None,funcname=None)¶

This class implements temporary breakpoints, ignore counts, disabling and(re-)enabling, and conditionals.

Breakpoints are indexed by number through a list calledbpbynumberand by(file,line) pairs throughbplist. The former points toa single instance of classBreakpoint. The latter points to a listof such instances since there may be more than one breakpoint per line.

When creating a breakpoint, its associatedfilename shouldbe in canonical form. If afuncname is defined, a breakpointhit will be counted when the first line of that function isexecuted. Aconditional breakpoint always counts ahit.

Breakpoint instances have the following methods:

deleteMe()¶

Delete the breakpoint from the list associated to a file/line. If it isthe last breakpoint in that position, it also deletes the entry for thefile/line.

enable()¶

Mark the breakpoint as enabled.

disable()¶

Mark the breakpoint as disabled.

bpformat()¶

Return a string with all the information about the breakpoint, nicelyformatted:

• Breakpoint number.

• Temporary status (del or keep).

• File/line position.

• Break condition.

• Number of times to ignore.

• Number of times hit.

Added in version 3.2.

bpprint(out=None)¶

Print the output ofbpformat() to the fileout, or if it isNone, to standard output.

Breakpoint instances have the following attributes:

file¶

File name of theBreakpoint.

line¶

Line number of theBreakpoint withinfile.

temporary¶

True if aBreakpoint at (file, line) is temporary.

cond¶

Condition for evaluating aBreakpoint at (file, line).

funcname¶

Function name that defines whether aBreakpoint is hit uponentering the function.

enabled¶

True ifBreakpoint is enabled.

bpbynumber¶

Numeric index for a single instance of aBreakpoint.

bplist¶

Dictionary ofBreakpoint instances indexed by(file,line) tuples.

ignore¶

Number of times to ignore aBreakpoint.

hits¶

Count of the number of times aBreakpoint has been hit.

classbdb.Bdb(skip=None,backend='settrace')¶

TheBdb class acts as a generic Python debugger base class.

This class takes care of the details of the trace facility; a derived classshould implement user interaction. The standard debugger class(pdb.Pdb) is an example.

Theskip argument, if given, must be an iterable of glob-stylemodule name patterns. The debugger will not step into frames thatoriginate in a module that matches one of these patterns. Whether aframe is considered to originate in a certain module is determinedby the__name__ in the frame globals.

Thebackend argument specifies the backend to use forBdb. Itcan be either'settrace' or'monitoring'.'settrace' usessys.settrace() which has the best backward compatibility. The'monitoring' backend uses the newsys.monitoring that wasintroduced in Python 3.12, which can be much more efficient because itcan disable unused events. We are trying to keep the exact interfacesfor both backends, but there are some differences. The debugger developersare encouraged to use the'monitoring' backend to achieve betterperformance.

Changed in version 3.1:Added theskip parameter.

Changed in version 3.14:Added thebackend parameter.

The following methods ofBdb normally don’t need to be overridden.

canonic(filename)¶

Return canonical form offilename.

For real file names, the canonical form is an operating-system-dependent,case-normalizedabsolutepath. Afilename with angle brackets, such as"<stdin>"generated in interactive mode, is returned unchanged.

start_trace(self)¶

Start tracing. For'settrace' backend, this method is equivalent tosys.settrace(self.trace_dispatch)

Added in version 3.14.

stop_trace(self)¶

Stop tracing. For'settrace' backend, this method is equivalent tosys.settrace(None)

Added in version 3.14.

reset()¶

Set thebotframe,stopframe,returnframe andquitting attributes with values ready to start debugging.

trace_dispatch(frame,event,arg)¶

This function is installed as the trace function of debugged frames. Itsreturn value is the new trace function (in most cases, that is, itself).

The default implementation decides how to dispatch a frame, depending onthe type of event (passed as a string) that is about to be executed.event can be one of the following:

• "line": A new line of code is going to be executed.

• "call": A function is about to be called, or another code blockentered.

• "return": A function or other code block is about to return.

• "exception": An exception has occurred.

• "c_call": A C function is about to be called.

• "c_return": A C function has returned.

• "c_exception": A C function has raised an exception.

For the Python events, specialized functions (see below) are called. Forthe C events, no action is taken.

Thearg parameter depends on the previous event.

See the documentation forsys.settrace() for more information on thetrace function. For more information on code and frame objects, refer toThe standard type hierarchy.

dispatch_line(frame)¶

If the debugger should stop on the current line, invoke theuser_line() method (which should be overridden in subclasses).Raise aBdbQuit exception if thequitting flag is set(which can be set fromuser_line()). Return a reference to thetrace_dispatch() method for further tracing in that scope.

dispatch_call(frame,arg)¶

If the debugger should stop on this function call, invoke theuser_call() method (which should be overridden in subclasses).Raise aBdbQuit exception if thequitting flag is set(which can be set fromuser_call()). Return a reference to thetrace_dispatch() method for further tracing in that scope.

dispatch_return(frame,arg)¶

If the debugger should stop on this function return, invoke theuser_return() method (which should be overridden in subclasses).Raise aBdbQuit exception if thequitting flag is set(which can be set fromuser_return()). Return a reference to thetrace_dispatch() method for further tracing in that scope.

dispatch_exception(frame,arg)¶

If the debugger should stop at this exception, invokes theuser_exception() method (which should be overridden in subclasses).Raise aBdbQuit exception if thequitting flag is set(which can be set fromuser_exception()). Return a reference to thetrace_dispatch() method for further tracing in that scope.

Normally derived classes don’t override the following methods, but they mayif they want to redefine the definition of stopping and breakpoints.

is_skipped_line(module_name)¶

ReturnTrue ifmodule_name matches any skip pattern.

stop_here(frame)¶

ReturnTrue ifframe is below the starting frame in the stack.

break_here(frame)¶

ReturnTrue if there is an effective breakpoint for this line.

Check whether a line or function breakpoint exists and is in effect. Delete temporarybreakpoints based on information fromeffective().

break_anywhere(frame)¶

ReturnTrue if any breakpoint exists forframe’s filename.

Derived classes should override these methods to gain control over debuggeroperation.

user_call(frame,argument_list)¶

Called fromdispatch_call() if a break might stop inside thecalled function.

argument_list is not used anymore and will always beNone.The argument is kept for backwards compatibility.

user_line(frame)¶

Called fromdispatch_line() when eitherstop_here() orbreak_here() returnsTrue.

user_return(frame,return_value)¶

Called fromdispatch_return() whenstop_here() returnsTrue.

user_exception(frame,exc_info)¶

Called fromdispatch_exception() whenstop_here()returnsTrue.

do_clear(arg)¶

Handle how a breakpoint must be removed when it is a temporary one.

This method must be implemented by derived classes.

Derived classes and clients can call the following methods to affect thestepping state.

set_step()¶

Stop after one line of code.

set_next(frame)¶

Stop on the next line in or below the given frame.

set_return(frame)¶

Stop when returning from the given frame.

set_until(frame,lineno=None)¶

Stop when the line with thelineno greater than the current one isreached or when returning from current frame.

set_trace([frame])¶

Start debugging fromframe. Ifframe is not specified, debuggingstarts from caller’s frame.

Changed in version 3.13:set_trace() will enter the debugger immediately, rather thanon the next line of code to be executed.

set_continue()¶

Stop only at breakpoints or when finished. If there are no breakpoints,set the system trace function toNone.

set_quit()¶

Set thequitting attribute toTrue. This raisesBdbQuit inthe next call to one of thedispatch_*() methods.

Derived classes and clients can call the following methods to manipulatebreakpoints. These methods return a string containing an error message ifsomething went wrong, orNone if all is well.

set_break(filename,lineno,temporary=False,cond=None,funcname=None)¶

Set a new breakpoint. If thelineno line doesn’t exist for thefilename passed as argument, return an error message. Thefilenameshould be in canonical form, as described in thecanonic() method.

clear_break(filename,lineno)¶

Delete the breakpoints infilename andlineno. If none were set,return an error message.

clear_bpbynumber(arg)¶

Delete the breakpoint which has the indexarg in theBreakpoint.bpbynumber. Ifarg is not numeric or out of range,return an error message.

clear_all_file_breaks(filename)¶

Delete all breakpoints infilename. If none were set, return an errormessage.

clear_all_breaks()¶

Delete all existing breakpoints. If none were set, return an errormessage.

get_bpbynumber(arg)¶

Return a breakpoint specified by the given number. Ifarg is a string,it will be converted to a number. Ifarg is a non-numeric string, ifthe given breakpoint never existed or has been deleted, aValueError is raised.

Added in version 3.2.

get_break(filename,lineno)¶

ReturnTrue if there is a breakpoint forlineno infilename.

get_breaks(filename,lineno)¶

Return all breakpoints forlineno infilename, or an empty list ifnone are set.

get_file_breaks(filename)¶

Return all breakpoints infilename, or an empty list if none are set.

get_all_breaks()¶

Return all breakpoints that are set.

Derived classes and clients can call the following methods to disable andrestart events to achieve better performance. These methods only workwhen using the'monitoring' backend.

disable_current_event()¶

Disable the current event until the next timerestart_events() iscalled. This is helpful when the debugger is not interested in the currentline.

Added in version 3.14.

restart_events()¶

Restart all the disabled events. This function is automatically called indispatch_* methods afteruser_* methods are called. If thedispatch_* methods are not overridden, the disabled events will berestarted after each user interaction.

Added in version 3.14.

Derived classes and clients can call the following methods to get a datastructure representing a stack trace.

get_stack(f,t)¶

Return a list of (frame, lineno) tuples in a stack trace, and a size.

The most recently called frame is last in the list. The size is the numberof frames below the frame where the debugger was invoked.

format_stack_entry(frame_lineno,lprefix=':')¶

Return a string with information about a stack entry, which is a(frame,lineno) tuple. The return string contains:

• The canonical filename which contains the frame.

• The function name or"<lambda>".

• The input arguments.

• The return value.

• The line of code (if it exists).

The following two methods can be called by clients to use a debugger to debugastatement, given as a string.

run(cmd,globals=None,locals=None)¶

Debug a statement executed via theexec() function.globalsdefaults to__main__.__dict__,locals defaults toglobals.

runeval(expr,globals=None,locals=None)¶

Debug an expression executed via theeval() function.globals andlocals have the same meaning as inrun().

runctx(cmd,globals,locals)¶

For backwards compatibility. Calls therun() method.

runcall(func,/,*args,**kwds)¶

Debug a single function call, and return its result.

Finally, the module defines the following functions:

bdb.checkfuncname(b,frame)¶

ReturnTrue if we should break here, depending on the way theBreakpointb was set.

If it was set via line number, it checks ifb.line is the same as the one inframe.If the breakpoint was set viafunctionname, we have to check we are inthe rightframe (the right function) and if we are on its first executableline.

bdb.effective(file,line,frame)¶

Return(activebreakpoint,deletetemporaryflag) or(None,None) as thebreakpoint to act upon.

Theactive breakpoint is the first entry inbplist for the(file,line)(which must exist) that isenabled, forwhichcheckfuncname() is true, and that has neither a falsecondition nor positiveignore count. Theflag, meaning that atemporary breakpoint should be deleted, isFalse only when thecond cannot be evaluated (in which case,ignore count is ignored).

If no such entry exists, then(None,None) is returned.

bdb.set_trace()¶

Start debugging with aBdb instance from caller’s frame.