bdb --- 偵錯器框架

原始碼：Lib/bdb.py

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

有定義以下例外：

exceptionbdb.BdbQuit

由Bdb 類別所引發的例外，用來退出偵錯器。

bdb 模組也定義了兩個類別：

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 實例有以下方法：

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.

在 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

如Breakpoint 有被啟用則為True。

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)

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.

在 3.1 版的變更:新增skip 引數。

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.

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 to標準型別階層.

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.

在 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.

在 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 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.

  • 函式名稱或"<lambda>"。

  • 輸入引數。

  • 回傳值。

  • 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.