26.1. bdb —调试器框架

源代码： Lib/bdb.py

---

bdb模块处理基本的调试器Function，例如设置断点或pass调试器 Management 执行。

定义了以下异常：

• exception bdb. BdbQuit
  • Bdb类引发的用于退出调试器的异常。

bdb模块还定义了两个类：

• • class * bdb. Breakpoint(* self ， file ， line ， temporary = 0 ， cond = None ， funcname = None *)
  • 此类实现临时断点，忽略计数，禁用和(重新)启用以及有条件的。

断点pass编号passbpbynumber进行索引，而(file, line)对passbplist进行索引。前者指向类Breakpoint的单个实例。后者指向此类实例的列表，因为每行可能有多个断点。

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

Breakpoint个实例具有以下方法：

• deleteMe ( )

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

• enable ( )

  • 将断点标记为已启用。

• disable ( )

  • 将断点标记为禁用。

• pprint([* out *])

  • 打印有关断点的所有信息：

• 断点号。

• 是否是临时的。

• 它的文件，行位置。

• 导致break的条件。

• 如果以后必须忽略 N 次。

• 断点命中计数。

• • class * bdb. Bdb(* skip = None *)
  • Bdb类充当通用的 Python 调试器 Base Class。

此类负责跟踪工具的详细信息。派生类应实现用户交互。标准调试器类(pdb.Pdb)是一个示例。

• skip *参数(如果给定)必须是全局样式的模块名称模式的可迭代形式。调试器将不会进入源自与这些模式之一匹配的模块的框架。帧是否被认为起源于某个模块由帧全局变量中的__name__确定。

2.7 版的新Function：* skip *参数。

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

• canonic(文件名)

  • 以规范形式获取文件名的辅助方法，即作为大小写规范化(在不区分大小写的文件系统上)的绝对路径，去除了尖括号。

• reset ( )

  • 设置botframe，stopframe，returnframe和quitting属性的值以准备开始调试。

• trace_dispatch((* frame ， event ， arg *)

  • 此Function作为调试帧的跟踪Function安装。它的返回值是新的跟踪函数(在大多数情况下，即它本身)。

默认实现取决于将要执行的事件类型(作为字符串传递)决定如何调度帧。 * event *可以是以下之一：

• "line"：将执行新的代码行。

• "call"：即将调用一个Function，或 Importing 了另一个代码块。

• "return"：函数或其他代码块将要返回。

• "exception"：发生异常。

• "c_call"：即将调用 C 函数。

• "c_return"：C 函数已返回。

• "c_exception"：C 函数引发了异常。

对于 Python 事件，将调用专用函数(请参见下文)。对于 C 事件，不采取任何措施。

• arg *参数取决于上一个事件。

有关跟踪Function的更多信息，请参见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 *)

  • 此方法检查* frame *是否在调用堆栈中的botframe以下。 botframe是开始调试的框架。

• break_here(* frame *)

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

• break_anywhere(* frame *)

  • 此方法检查当前帧的文件名中是否有断点。

派生类应重写这些方法，以控制调试器的操作。

• user_call(* frame ， argument_list *)

  • 当有可能需要在被调用函数内的任何地方break时，从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 *)

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

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

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

• set_step ( )

  • 在一行代码之后停止。

• set_next(* frame *)

  • 在给定框架内或之下的下一行停止。

• set_return(* frame *)

  • 从给定的帧返回时停止。

• set_until(* frame *)

  • 当到达不超过当前行的行或从当前帧返回时停止。

• set_trace([帧])

  • 从* frame 开始调试。如果未指定 frame *，则调试将从调用方的框架开始。

• set_continue ( )

  • 仅在断点或完成时停止。如果没有断点，请将系统跟踪Function设置为None。

• set_quit ( )

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

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

• set_break(* filename ， lineno ， temporary = 0 ， cond = None ， funcname = None *)

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

• clear_break(* filename ， lineno *)

  • 删除* filename 和 lineno *中的断点。如果未设置，则返回错误消息。

• clear_bpbynumber(* arg *)

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

• clear_all_file_breaks(文件名)

  • 删除* filename *中的所有断点。如果未设置，则返回错误消息。

• clear_all_breaks ( )

  • 删除所有现有的断点。

• get_break(* filename ， lineno *)

  • 检查* filename 的 lineno *是否存在断点。

• get_breaks(* filename ， lineno *)

  • 返回* filename 中 lineno *的所有断点；如果未设置任何断点，则返回一个空列表。

• get_file_breaks(文件名)

  • 返回* filename *中的所有断点；如果未设置任何断点，则返回一个空列表。

• get_all_breaks ( )

  • 返回所有设置的断点。

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

• get_stack(* f ， t *)

  • 获取一个框架以及所有较高(调用)和较低框架的记录列表，以及较高部分的大小。

• format_stack_entry(* frame_lineno * [，* lprefix ='：'*])

  • 返回一个包含有关堆栈条目信息的字符串，该字符串由(frame, lineno)Tuples 标识：

• 包含框架的文件名的规范形式。

• 函数名称或"<lambda>"。

• Importing 参数。

• 返回值。

• 代码行(如果存在)。

Client 端可以调用以下两种方法来使用调试器调试以字符串形式给出的statement。

• run(* cmd * [，* globals * [，* locals *]])

  • 调试passexec语句执行的语句。 * globals 默认为__main__.__dict__， locals 默认为 globals *。

• runeval(* expr * [，* globals * [，* locals *]])

  • 调试passeval()函数执行的表达式。 * globals 和 locals *与run()中的含义相同。

• runctx(* cmd ， globals ， locals *)

  • 为了向后兼容。调用run()方法。

• runcall(* func *， *args ， * kwds *)

  • 调试单个函数调用，并返回其结果。

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

• bdb. checkfuncname(* b ， frame *)
  • 根据设置断点* b *的方式，检查是否应在此处break。

如果pass行号设置，它将检查b.line是否与也作为参数传递的帧中的_相同。如果断点是pass函数名设置的，则必须检查是否在正确的框架(正确的函数)中，以及是否在其第一行可执行文件中。

• bdb. effective(* file ， line ， frame *)

  • 确定在此代码行中是否存在有效的(活动)断点。返回一个断点 Tuples 和一个布尔值，该布尔值指示是否可以删除临时断点。如果没有匹配的断点，则返回(None, None)。

• bdb. set_trace ( )

  • 使用调用者框架中的Bdb实例开始调试。