bdb — 调试器框架

源代码： :source:`Lib/bdb.py`

bdb 模块处理基本的调试器功能，例如设置断点或通过调试器管理执行。

定义了以下异常：

exception bdb.BdbQuit: Bdb 类为退出调试器引发的异常。

bdb 模块还定义了两个类：

class bdb.Breakpoint(self, file, line, temporary=0, cond=None, funcname=None)

此类实现临时断点、忽略计数、禁用和（重新）启用以及条件。

断点通过名为 bpbynumber 的列表按编号进行索引，并通过 (file, line) 对通过 bplist 进行索引。前者指向类 Breakpoint 的单个实例。后者指向此类实例的列表，因为每行可能有多个断点。

创建断点时，其关联的文件名应采用规范格式。如果定义了 funcname，则在执行该函数的第一行时将计算断点命中。条件断点始终计为命中。

Breakpoint 实例有以下方法：

deleteMe(): 从与文件/行关联的列表中删除断点。如果它是该位置的最后一个断点，它还会删除文件/行的条目。

enable(): 将断点标记为已启用。

disable(): 将断点标记为禁用。

bpformat()

返回一个包含断点所有信息的字符串，格式很好：

断点编号。
如果是暂时的。
它的文件，行位置。
导致中断的条件。
如果它必须在接下来的 N 次被忽略。
断点命中数。

3.2 版中的新功能。

bpprint(out=None): 将 bpformat() 的输出打印到文件 out，如果是 None，则打印到标准输出。

class bdb.Bdb(skip=None)

Bdb 类充当通用 Python 调试器基类。

这个类负责跟踪设施的细节；派生类应该实现用户交互。标准调试器类 (pdb.Pdb) 就是一个例子。

skip 参数（如果给定）必须是全局样式模块名称模式的可迭代对象。调试器不会进入源自与这些模式之一匹配的模块的帧。帧是否被认为源自某个模块由帧全局变量中的 __name__ 决定。

3.1 版新功能： skip 参数。

Bdb 的以下方法通常不需要被覆盖。

canonic(filename): 以规范形式获取文件名的辅助方法，即作为大小写规范化（在不区分大小写的文件系统上）绝对路径，去掉周围的尖括号。

reset(): 将 botframe、stopframe、returnframe 和 quitting 属性设置为准备开始调试的值。

trace_dispatch(frame, event, arg)

此功能安装为调试帧的跟踪功能。它的返回值是新的跟踪函数（在大多数情况下，也就是它自己）。

默认实现决定如何分派帧，具体取决于即将执行的事件类型（作为字符串传递）。 event 可以是以下之一：

"line"：将要执行新的一行代码。
"call"：一个函数即将被调用，或者另一个代码块被输入。
"return"：函数或其他代码块即将返回。
"exception"：发生异常。
"c_call"：即将调用AC函数。
"c_return"：AC 功能已返回。
"c_exception"：AC 函数引发异常。

对于 Python 事件，会调用专门的函数（见下文）。对于 C 事件，不采取任何行动。

arg 参数取决于前一个事件。

有关跟踪功能的更多信息，请参阅 sys.settrace() 的文档。有关代码和框架对象的更多信息，请参阅标准类型层次结构。

dispatch_line(frame): 如果调试器应该在当前行停止，调用 user_line() 方法（应该在子类中覆盖）。如果设置了 Bdb.quitting 标志（可以从 user_line() 设置），则引发 BdbQuit 异常。返回对 trace_dispatch() 方法的引用，以便在该范围内进一步跟踪。

dispatch_call(frame, arg): 如果调试器应在此函数调用上停止，请调用 user_call() 方法（应在子类中覆盖）。如果设置了 Bdb.quitting 标志（可以从 user_call() 设置），则引发 BdbQuit 异常。返回对 trace_dispatch() 方法的引用，以便在该范围内进一步跟踪。

dispatch_return(frame, arg): 如果调试器应在此函数返回时停止，请调用 user_return() 方法（应在子类中覆盖）。如果设置了 Bdb.quitting 标志（可以从 user_return() 设置），则引发 BdbQuit 异常。返回对 trace_dispatch() 方法的引用，以便在该范围内进一步跟踪。

dispatch_exception(frame, arg): 如果调试器应在此异常处停止，则调用 user_exception() 方法（应在子类中覆盖）。如果设置了 Bdb.quitting 标志（可以从 user_exception() 设置），则引发 BdbQuit 异常。返回对 trace_dispatch() 方法的引用，以便在该范围内进一步跟踪。

通常派生类不会覆盖以下方法，但如果他们想重新定义停止和断点的定义，它们可能会覆盖。

stop_here(frame): 此方法检查帧是否在调用堆栈中的 botframe 以下某处。 botframe 是调试开始的帧。

break_here(frame): 此方法检查文件名和属于 frame 的行中或至少在当前函数中是否存在断点。如果断点是临时断点，则此方法将其删除。

break_anywhere(frame): 此方法检查当前帧的文件名中是否存在断点。

派生类应该覆盖这些方法以获得对调试器操作的控制。

user_call(frame, argument_list): 当在被调用函数内的任何地方可能需要中断时，从 dispatch_call() 调用此方法。

user_line(frame): 当 stop_here() 或 break_here() 产生 True 时，从 dispatch_line() 调用此方法。

user_return(frame, return_value): 当 stop_here() 产生 True 时，从 dispatch_return() 调用此方法。

user_exception(frame, exc_info): 当 stop_here() 产生 True 时，从 dispatch_exception() 调用此方法。

do_clear(arg)

处理当断点是临时断点时必须如何删除它。

此方法必须由派生类实现。

派生类和客户端可以调用以下方法来影响步进状态。

set_step(): 一行代码后停止。

set_next(frame): 停在给定帧中或下方的下一行。

set_return(frame): 从给定帧返回时停止。

set_until(frame): 当到达不大于当前行的行或从当前帧返回时停止。

set_trace([frame]): 从帧开始调试。如果未指定 frame，则调试从调用者的帧开始。

set_continue(): 仅在断点处或完成时停止。如果没有断点，将系统跟踪功能设置为None。

set_quit(): 将 quitting 属性设置为 True。这会在下一次调用 dispatch_*() 方法之一时引发 BdbQuit。

派生类和客户端可以调用以下方法来操作断点。如果出现问题，这些方法将返回一个包含错误消息的字符串，如果一切正常，则返回 None。

set_break(filename, lineno, temporary=0, cond, funcname): 设置一个新的断点。如果作为参数传递的 filename 不存在 lineno 行，则返回错误消息。 文件名 应采用规范形式，如 canonic() 方法中所述。

clear_break(filename, lineno): 删除 filename 和 lineno 中的断点。如果没有设置，则返回错误消息。

clear_bpbynumber(arg): 删除Breakpoint.bpbynumber中索引为arg的断点。如果 arg 不是数字或超出范围，则返回错误消息。

clear_all_file_breaks(filename): 删除 filename 中的所有断点。如果没有设置，则返回错误消息。

clear_all_breaks(): 删除所有现有断点。

get_bpbynumber(arg): 返回由给定数字指定的断点。如果 arg 是一个字符串，它将被转换为一个数字。如果 arg 是非数字字符串，如果给定的断点从未存在或已被删除，则会引发 ValueError。

3.2 版中的新功能。

get_break(filename, lineno): 检查 filename 的 lineno 是否有断点。

get_breaks(filename, lineno): 返回 filename 中 lineno 的所有断点，如果没有设置，则返回空列表。

get_file_breaks(filename): 返回 filename 中的所有断点，如果没有设置，则返回空列表。

get_all_breaks(): 返回所有设置的断点。

派生类和客户端可以调用以下方法来获取表示堆栈跟踪的数据结构。

get_stack(f, t): 获取帧和所有更高（调用）和更低帧的记录列表，以及更高部分的大小。

format_stack_entry(frame_lineno, lprefix=': ')

返回一个包含堆栈条目信息的字符串，由 (frame, lineno) 元组标识：

包含框架的文件名的规范形式。
函数名称，或 "<lambda>"。
输入参数。
返回值。
代码行（如果存在）。

客户端可以调用以下两种方法来使用调试器来调试以字符串形式给出的语句。

run(cmd, globals=None, locals=None): 调试通过 exec() 函数执行的语句。 globals 默认为 __main__.__dict__，locals 默认为 globals。

runeval(expr, globals=None, locals=None): 调试通过 eval() 函数执行的表达式。 globals 和 locals 与 run() 具有相同的含义。

runctx(cmd, globals, locals): 为了向后兼容。调用 run() 方法。

runcall(func, /, *args, **kwds): 调试单个函数调用，并返回其结果。

最后，该模块定义了以下函数：

bdb.checkfuncname(b, frame)

根据设置断点 b 的方式，检查我们是否应该在这里中断。

如果它是通过行号设置的，它会检查 b.line 是否与作为参数传递的帧中的相同。如果断点是通过函数名设置的，我们必须检查我们是否在正确的框架（正确的函数）中，以及我们是否在它的第一个可执行行中。

bdb.effective(file, line, frame): 确定在这行代码处是否存在有效（活动）断点。返回断点的元组和指示是否可以删除临时断点的布尔值。如果没有匹配的断点，则返回 (None, None)。

bdb.set_trace(): 使用调用者框架中的 Bdb 实例开始调试。

bdb — 调试器框架 — Python 文档

bdb — 调试器框架