bdb — Debugger framework调试器框架

Source code: Lib/bdb.py

---

The bdb module handles basic debugger functions, like setting breakpoints or managing execution via the debugger.bdb模块处理基本的调试器功能，例如设置断点或通过调试器管理执行。

The following exception is defined:定义了以下异常：

exceptionbdb.BdbQuit

Exception raised by the Bdb class for quitting the debugger.Bdb类为退出调试器而引发异常。

The bdb module also defines two classes:bdb模块还定义了两个类：

classbdb.Breakpoint(self, file, line, temporary=0, 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 called bpbynumber and by (file, line) pairs through bplist. 断点通过名为bpbynumber的列表按数字索引，通过bplist按(file, line)对索引。The former points to a single instance of class Breakpoint. 前者指向Breakpoint类的单个实例。The latter points to a list of such instances since there may be more than one breakpoint per line.后者指向此类实例的列表，因为每行可能有多个断点。

When creating a breakpoint, its associated filename should be in canonical form. 创建断点时，其关联文件名应为规范格式。If a funcname is defined, a breakpoint hit will be counted when the first line of that function is executed. 如果定义了funcname，则在执行该函数的第一行时将计算断点命中。A conditional breakpoint always counts a hit.条件断点总是计算命中次数。

Breakpoint instances have the following methods:实例具有以下方法：

deleteMe()

Delete the breakpoint from the list associated to a file/line. 从与文件/行关联的列表中删除断点。If it is the last breakpoint in that position, it also deletes the entry for the file/line.如果它是该位置的最后一个断点，它还会删除文件/行的条目。

enable()

Mark the breakpoint as enabled.将断点标记为已启用。

disable()

Mark the breakpoint as disabled.将断点标记为禁用。

bpformat()

Return a string with all the information about the breakpoint, nicely formatted:返回一个字符串，其中包含断点的所有信息，格式很好：

• The breakpoint number.断点编号。

• If it is temporary or not.如果它是暂时的或不是。

• Its file,line position.它的文件，行位置。

• The condition that causes a break.导致中断的条件。

• If it must be ignored the next N times.如果必须在接下来的N次中忽略它。

• The breakpoint hit count.断点命中计数。

New in version 3.2.版本3.2中新增。

bpprint(out=None)

Print the output of bpformat() to the file out, or if it is None, to standard output.将bpformat()的输出打印到文件out，如果为None，则打印到标准输出。

classbdb.Bdb(skip=None)

The Bdb class acts as a generic Python debugger base class.Bdb类充当通用Python调试器基类。

This class takes care of the details of the trace facility; a derived class should implement user interaction. 此类负责跟踪设施的详细信息；派生类应该实现用户交互。The standard debugger class (pdb.Pdb) is an example.标准调试器类（pdb.Pdb）就是一个示例。

The skip argument, if given, must be an iterable of glob-style module name patterns. 如果给定了skip参数，则该参数必须是glob样式模块名称模式的可迭代参数。The debugger will not step into frames that originate in a module that matches one of these patterns. 调试器不会单步执行源自与这些模式之一匹配的模块的帧。Whether a frame is considered to originate in a certain module is determined by the __name__ in the frame globals.帧是否被认为源自某个模块取决于帧全局中的__name__。

New in version 3.1.版本3.1中新增。The skip argument.skip参数。

The following methods of Bdb normally don’t need to be overridden.Bdb的以下方法通常不需要重写。

canonic(filename)

Auxiliary method for getting a filename in a canonical form, that is, as a case-normalized (on case-insensitive filesystems) absolute path, stripped of surrounding angle brackets.用于以规范形式获取文件名的辅助方法，即作为大小写规范化（不区分大小写的文件系统）绝对路径，去掉周围的尖括号。

reset()

Set the botframe, stopframe, returnframe and quitting attributes with values ready to start debugging.将botframe、stopframe、returnframe和quitting属性设置为可以开始调试的值。

trace_dispatch(frame, event, arg)

This function is installed as the trace function of debugged frames. 此函数安装为已调试帧的跟踪函数。Its return value is the new trace function (in most cases, that is, itself).它的返回值是新的跟踪函数（在大多数情况下，就是它本身）。

The default implementation decides how to dispatch a frame, depending on the type of event (passed as a string) that is about to be executed. 默认实现根据将要执行的事件类型（作为字符串传递）决定如何分派帧。event can be one of the following:event可以是以下之一：

• "line": A new line of code is going to be executed.：将执行一行新代码。

• "call": A function is about to be called, or another code block entered.：即将调用函数，或输入另一个代码块。

• "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函数。

• "c_return": A C function has returned.：返回了C函数。

• "c_exception": A C function has raised an exception.：C函数引发了异常。

For the Python events, specialized functions (see below) are called. 对于Python事件，调用专用函数（见下文）。For the C events, no action is taken.对于C事件，不采取任何操作。

The arg parameter depends on the previous event.arg参数取决于上一个事件。

See the documentation for sys.settrace() for more information on the trace function. 有关跟踪函数的详细信息，请参阅sys.settrace()的文档。For more information on code and frame objects, refer to The standard type hierarchy.有关代码和框架对象的详细信息，请参阅标准类型层次结构。

dispatch_line(frame)

If the debugger should stop on the current line, invoke the user_line() method (which should be overridden in subclasses). 如果调试器在当前行停止，请调用user_line()方法（应该在子类中重写）。Raise a BdbQuit exception if the Bdb.quitting flag is set (which can be set from user_line()). 如果设置了Bdb.quitting标志（可以从user_line()设置），则引发BdbQuit异常。Return a reference to the trace_dispatch() method for further tracing in that scope.返回对trace_dispatch()方法的引用，以便在该范围内进行进一步跟踪。

dispatch_call(frame, arg)

If the debugger should stop on this function call, invoke the user_call() method (which should be overridden in subclasses). 如果调试器在此函数调用时停止，请调用user_call()方法（应在子类中重写）。Raise a BdbQuit exception if the Bdb.quitting flag is set (which can be set from user_call()). 如果设置了Bdb.quitting标志（可以从user_call()设置），则引发BdbQuit异常。Return a reference to the trace_dispatch() method for further tracing in that scope.返回对trace_dispatch()方法的引用，以便在该范围内进行进一步跟踪。

dispatch_return(frame, arg)

If the debugger should stop on this function return, invoke the user_return() method (which should be overridden in subclasses). 如果调试器在此函数返回时停止，请调用user_return()方法（应在子类中重写）。Raise a BdbQuit exception if the Bdb.quitting flag is set (which can be set from user_return()). 如果设置了Bdb.quitting标志（可以通过user_return()设置），则引发BdbQuit异常。Return a reference to the trace_dispatch() method for further tracing in that scope.返回对trace_dispatch()方法的引用，以便在该范围内进行进一步跟踪。

dispatch_exception(frame, arg)

If the debugger should stop at this exception, invokes the user_exception() method (which should be overridden in subclasses). 如果调试器应停止此异常，则调用user_exception()方法（应在子类中重写）。Raise a BdbQuit exception if the Bdb.quitting flag is set (which can be set from user_exception()). 如果设置了Bdb.quitting标志（可以从user_exception()设置），则引发BdbQuit异常。Return a reference to the trace_dispatch() method for further tracing in that scope.返回对trace_dispatch()方法的引用，以便在该范围内进行进一步跟踪。

Normally derived classes don’t override the following methods, but they may if they want to redefine the definition of stopping and breakpoints.通常派生类不会重写以下方法，但如果它们想重新定义停止和断点的定义，则可以重写这些方法。

stop_here(frame)

This method checks if the frame is somewhere below botframe in the call stack. 此方法检查该frame是否位于调用堆栈中botframe之下的某个位置。botframe is the frame in which debugging started.botframe是调试开始的帧。

break_here(frame)

This method checks if there is a breakpoint in the filename and line belonging to frame or, at least, in the current function. 此方法检查文件名和属于frame的行中是否存在断点，或者至少在当前函数中存在断点。If the breakpoint is a temporary one, this method deletes it.如果断点是临时断点，此方法将删除它。

break_anywhere(frame)

This method checks if there is a breakpoint in the filename of the current frame.此方法检查当前帧的文件名中是否存在断点。

Derived classes should override these methods to gain control over debugger operation.派生类应重写这些方法以获得对调试器操作的控制。

user_call(frame, argument_list)

This method is called from dispatch_call() when there is the possibility that a break might be necessary anywhere inside the called function.当被调用函数内的任何地方都可能需要中断时，从dispatch_call()调用此方法。

user_line(frame)

This method is called from dispatch_line() when either stop_here() or break_here() yields True.当stop_here()或break_here()产生True时，从dispatch_line()调用此方法。

user_return(frame, return_value)

This method is called from dispatch_return() when stop_here() yields True.当stop_here()产生True时，从dispatch_return()调用此方法。

user_exception(frame, exc_info)

This method is called from dispatch_exception() when stop_here() yields True.当stop_here()产生True时，从dispatch_exception()调用此方法。

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 the stepping 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)

Stop when the line with the line no greater than the current one is reached or when returning from current frame.当到达行不大于当前行的行或从当前帧返回时停止。

set_trace([frame])

Start debugging from frame. 从frame开始调试。If frame is not specified, debugging starts from caller’s frame.如果未指定frame，调试将从调用方的帧开始。

set_continue()

Stop only at breakpoints or when finished. 仅在断点或完成时停止。If there are no breakpoints, set the system trace function to None.如果没有断点，请将系统跟踪函数设置为None。

set_quit()

Set the quitting attribute to True. 将quitting属性设置为True。This raises BdbQuit in the next call to one of the dispatch_*() methods.这将在下一次调用dispatch_*()方法时引发BdbQuit。

Derived classes and clients can call the following methods to manipulate breakpoints. 派生类和客户端可以调用以下方法来操作断点。These methods return a string containing an error message if something went wrong, or None if all is well.如果出现问题，这些方法将返回一个包含错误消息的字符串，如果一切正常，则返回None。

set_break(filename, lineno, temporary=0, cond, funcname)

Set a new breakpoint. 设置新断点。If the lineno line doesn’t exist for the filename passed as argument, return an error message. 如果作为参数传递的filename不存在lineno行，则返回错误消息。The filename should be in canonical form, as described in the canonic() method.filename应为规范格式，如canonic()方法中所述。

clear_break(filename, lineno)

Delete the breakpoints in filename and lineno. 删除filename和lineno中的断点。If none were set, an error message is returned.如果未设置，则返回错误消息。

clear_bpbynumber(arg)

Delete the breakpoint which has the index arg in the Breakpoint.bpbynumber. 删除Breakpoint.bpbynumber中具有索引arg的断点。If arg is not numeric or out of range, return an error message.如果arg不是数字或超出范围，则返回错误消息。

clear_all_file_breaks(filename)

Delete all breakpoints in filename. 删除filename中的所有断点。If none were set, an error message is returned.如果未设置，则返回错误消息。

clear_all_breaks()

Delete all existing breakpoints.删除所有现有断点。

get_bpbynumber(arg)

Return a breakpoint specified by the given number. 返回由给定数字指定的断点。If arg is a string, it will be converted to a number. 如果arg是字符串，它将被转换为数字。If arg is a non-numeric string, if the given breakpoint never existed or has been deleted, a ValueError is raised.如果arg是非数字字符串，如果给定的断点从未存在或已被删除，则会引发ValueError。

New in version 3.2.版本3.2中新增。

get_break(filename, lineno)

Check if there is a breakpoint for lineno of filename.检查filename的lineno是否存在断点。

get_breaks(filename, lineno)

Return all breakpoints for lineno in filename, or an empty list if none are set.返回filename中lineno的所有断点，如果未设置，则返回空列表。

get_file_breaks(filename)

Return all breakpoints in filename, or an empty list if none are set.返回filename中的所有断点，如果未设置断点，则返回空列表。

get_all_breaks()

Return all breakpoints that are set.返回设置的所有断点。

Derived classes and clients can call the following methods to get a data structure representing a stack trace.派生类和客户端可以调用以下方法来获取表示堆栈跟踪的数据结构。

get_stack(f, t)

Get a list of records for a frame and all higher (calling) and lower frames, and the size of the higher part.获取一个帧以及所有较高（调用）和较低帧的记录列表，以及较高部分的大小。

format_stack_entry(frame_lineno, lprefix=': ')

Return a string with information about a stack entry, identified by a (frame, lineno) tuple:返回包含堆栈项信息的字符串，由(frame, lineno)元组标识：

• The canonical form of the filename which contains the frame.包含框架的文件名的规范形式。

• The function name, or "<lambda>".函数名或"<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 debug a statement, given as a string.客户端可以调用以下两个方法来使用调试器调试以字符串形式给出的语句。

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

Debug a statement executed via the exec() function. 调试通过exec()函数执行的语句。globals defaults to __main__.__dict__, locals defaults to globals.globals变量默认为__main__.__dict__，locals默认为globals。

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

Debug an expression executed via the eval() function. 调试通过eval()函数执行的表达式。globals and locals have the same meaning as in run().globals变量和locals变量的含义与run()中的含义相同。

runctx(cmd, globals, locals)

For backwards compatibility. 向后兼容。Calls the run() method.调用run()方法。

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

Debug a single function call, and return its result.调试单个函数调用，并返回其结果。

Finally, the module defines the following functions:最后，模块定义了以下功能：

bdb.checkfuncname(b, frame)

Check whether we should break here, depending on the way the breakpoint b was set.检查是否应该在此处中断，这取决于断点b的设置方式。

If it was set via line number, it checks if b.line is the same as the one in the frame also passed as argument. 如果它是通过行号设置的，它将检查b.line是否与作为参数传递的帧中的b.line相同。If the breakpoint was set via function name, we have to check we are in the right frame (the right function) and if we are in its first executable line.如果断点是通过函数名设置的，我们必须检查是否在正确的框架（正确的函数）中，以及是否在其第一个可执行行中。

bdb.effective(file, line, frame)

Determine if there is an effective (active) breakpoint at this line of code. 确定此代码行是否存在有效（活动）断点。Return a tuple of the breakpoint and a boolean that indicates if it is ok to delete a temporary breakpoint. 返回断点的元组和指示是否可以删除临时断点的布尔值。Return (None, None) if there is no matching breakpoint.如果没有匹配的断点，则返回(None, None)。

bdb.set_trace()

Start debugging with a Bdb instance from caller’s frame.从调用者的框架中使用Bdb实例开始调试。