pdbpp 0.10.3

这是什么？

本模块是标准库中 pdb 模块的一个扩展。它旨在与前辈完全兼容，同时引入了多项新功能，以使您的调试体验尽可能愉快。

pdb++ 的功能包括

• Python 表达式的彩色 Tab 完成功能（通过 fancycompleter）

• 可选的代码列表语法高亮显示（通过 pygments）

• 粘性模式

• 从交互式 (Pdb++) 提示符中使用的多个新命令

• 智能命令解析（提示：您在提示符中输入过 r 或 c 来打印某个变量的值吗？）

• 在 pdb 模块中提供额外的便利函数，您可以从程序中使用

pdb++ 意在替换 pdb。如果您发现一些意外的行为，请将其报告为错误。

安装

由于 pdb++ 不是一个有效的 pip 或 easy_install 标识符，因此该软件包被命名为 pdbpp

$ pip install pdbpp

-- OR --

$ easy_install pdbpp

pdb++ 还可通过 conda 获取

$ conda install -c conda-forge pdbpp

或者，您只需将 pdb.py 放置在您的 PYTHONPATH 中的任何位置。

使用

请注意，该模块名为 pdb.py，这样 pdb++ 将自动在所有执行 import pdb 的位置使用（例如，pytest --pdb 将为您提供 pdb++ 提示符）。

可以通过执行例如 import pdb; pdb.pdb.set_trace() 来获取旧的 pdb 模块。

新交互式命令

以下是从交互式 (Pdb++) 提示符中可以使用的新命令。

sticky [start end]

切换 粘性模式。在此模式下，每次当前位置更改时，屏幕都会重绘并显示整个函数。因此，在进行单步执行时，您可以轻松地跟踪执行流程。如果提供了 start 和 end，则启用粘性模式，并且仅显示该范围内的行（包括极端值）。

longlist (ll)

列出当前函数的源代码。与正常的 pdb list 命令不同，longlist 显示整个函数。当前行用 -> 标记。在死后调试的情况下，引发异常的行用 >> 标记。如果设置了 highlight 配置选项 且已安装 pygments，则源代码将高亮显示。

interact

启动一个交互式解释器，其全局命名空间包含当前作用域中找到的所有名称。

track EXPRESSION

显示一个图表，显示表达式引用的对象及其引用的对象。此命令需要可导入的 pypy 源代码。

display EXPRESSION

向显示列表中添加表达式；列表中的表达式在每个步骤中都会被评估，并在值改变时打印出来。警告：由于这些表达式会多次评估，请确保不要在显示列表中放置具有副作用的表达式。

取消显示 EXPRESSION:

从显示列表中删除 EXPRESSION。

源 EXPRESSION

显示给定函数/方法/类的源代码。

编辑 EXPRESSION

在正确位置打开编辑器以编辑给定的函数/方法/类。使用的编辑器由 配置选项 指定。

hf_unhide，hf_hide，hf_list

某些框架可能被标记为“隐藏”，例如使用 @pdb.hideframe 函数装饰器。默认情况下，隐藏的框架不会显示在堆栈跟踪中，并且无法使用 up 和 down 访问。您可以使用 hf_unhide 来告诉 pdb 忽略隐藏状态（即，将隐藏的框架视为正常的），并使用 hf_hide 再次隐藏它们。使用 hf_list 打印隐藏框架的列表。可以使用配置选项 enable_hidden_frames 来禁用对隐藏框架的一般处理。

智能命令解析

默认情况下，pdb 尽力将您在命令提示符中输入的内容解释为其内置命令之一。但是，如果您只想打印具有与命令相同名称的局部变量的值，这会变得不方便。例如。

(Pdb) list
  1
  2     def fn():
  3         c = 42
  4         import pdb;pdb.set_trace()
  5  ->     return c
(Pdb) c

在上面的示例中，而不是打印 42，pdb 将输入解释为命令 continue，然后您会丢失提示符。更糟糕的是，即使您输入例如 c.__class__，也会发生这种情况。

pdb++ 通过始终优先考虑作用域中的变量（如果存在）来修复这种不友好的（当然，从作者的角度来看）行为。如果您确实想执行相应的命令，可以在它前面加上 !!。因此，上面的示例变为

(Pdb++) list
  1
  2     def fn():
  3         c = 42
  4         import pdb;pdb.set_trace()
  5  ->     return c
(Pdb++) c
42
(Pdb++) !!c

请注意，“智能”行为仅在存在歧义时发生，即如果存在与命令具有相同名称的变量：在其他所有情况下，一切照常工作。

关于 list 命令本身，使用 list(… 是一个特殊情况，它被处理为 Python 内置

(Pdb++) list([1, 2])
[1, 2]

pdb 模块中的附加函数

与 pdb++ 一起提供的 pdb 模块包括标准库模块中的所有函数和类。如果您发现任何差异，请将其报告为错误。

此外，还有一些仅适用于 pdb++ 的新便利函数。

pdb.xpm()

eXtended Post Mortem：它与 pdb.post_mortem(sys.exc_info()[2]) 等效。如果用在 except 子句中，它将从引发异常的行开始启动 post-mortem pdb 提示符。

pdb.disable()

禁用 pdb.set_trace()：对它的任何后续调用都将被忽略。

pdb.enable()

重新启用 pdb.set_trace()，以防它被 pdb.disable() 禁用。

@pdb.hideframe

一个函数装饰器，告诉 pdb++ 隐藏与函数对应的框架。隐藏的框架在使用交互式命令（如 up、down 或 where）时不会显示，除非调用 hf_unhide。

@pdb.break_on_setattr(attrname, condition=always)

类装饰器：每当类的任何实例设置属性 attrname 时，都中断程序的执行。condition 是一个可调用对象，它接受 setattr 的目标对象和实际值；默认情况下，每次设置属性都会中断。例如：

@break_on_setattr('bar')
class Foo(object):
    pass
f = Foo()
f.bar = 42    # the program breaks here

即使类已经创建，也可以使用它，例如，当我们要在特定对象的某个属性设置时中断。

class Foo(object):
    pass
a = Foo()
b = Foo()

def break_if_a(obj, value):
    return obj is a

break_on_setattr('bar', condition=break_if_a)(Foo)
b.bar = 10   # no break
a.bar = 42   # the program breaks here

此功能也可以在 pdb.set_trace() 之后使用。

(Pdb++) import pdb
(Pdb++) pdb.break_on_setattr('tree_id')(obj.__class__)
(Pdb++) continue

配置和自定义

要自定义 pdb++，您可以在您的家目录中放置一个名为 .pdbrc.py 的文件。该文件必须包含一个名为 Config 的类，该类从 pdb.DefaultConfig 继承，并覆盖所需的值。

以下是可以自定义的选项列表，以及它们的默认值：

prompt = '(Pdb++) '

交互模式时显示的提示。

highlight = True

在显示函数的长列表或在 sticky模式 下时，突出显示行号和当前行。

encoding = 'utf-8'

文件编码。当字符串字面量或注释中包含国际字符时很有用。

sticky_by_default = False

确定 pdb++ 是否在 sticky 模式下启动。

line_number_color = Color.turquoise

用于行号的颜色。

filename_color = Color.yellow

打印堆栈条目时用于文件名的颜色。

current_line_color = "39;49;7"

用于突出显示当前行的 ANSI 转义序列的 SGR 参数。这是在 SGR 转义序列 \e[%sm 中设置的，其中 \e 是 ESC 字符，%s 是给定的值。有关信息，请参阅 SGR 参数。以下表示“重置所有颜色” (0)，设置前景色为 18 (48;5;18)，背景为 21。默认情况下使用默认前景色 (39) 和背景色 (49)，反向 (7)。

use_pygments = True

如果 pygments 已安装且 highlight == True，则在显示函数的长列表或在 sticky模式 下时，对源代码应用语法高亮。

bg = 'dark'

直接传递给 pygments.formatters.TerminalFormatter 构造函数。根据终端的背景颜色选择要使用的颜色方案。如果您有浅色背景颜色，请尝试将其设置为 'light'。

colorscheme = None

直接传递给 pygments.formatters.TerminalFormatter 构造函数。它期望一个字典，该字典将令牌类型映射到 (lightbg, darkbg) 颜色名称或 None（默认值：None = 使用内置颜色方案）。

editor = '${EDITOR:-vi}'

当使用 edit 命令时调用的命令。默认情况下，如果设置了 $EDITOR，则使用它，否则使用 vi。该命令必须支持标准表示法 COMMAND +n filename 以在行 n 处打开 filename。已知 emacs 和 vi 支持。

truncate_long_lines = True

截断超出终端宽度的行。

exec_if_unfocused = None

当启动 pdb 提示符且终端窗口未聚焦时执行的 shell 命令。例如，播放声音以提醒用户程序已停止执行。它需要 wmctrl 模块。

disable_pytest_capturing = False

旧版本的 pytest 在测试中执行 pdb.set_trace() 会导致崩溃，但标准输出会被捕获（即，没有使用 -s 选项，这是默认行为）。当此选项开启时，在显示交互式提示之前会自动禁用标准输出捕获。

enable_hidden_frames = True

某些帧默认可以隐藏。如果启用，可以使用 hf_unhide、hf_hide 和 hf_list 命令来控制它们的显示。

show_hidden_frames_count = True

如果 enable_hidden_frames 为 True，则此选项控制是否显示隐藏帧的数量。

def setup(self, pdb): pass

此方法在 Pdb 类初始化期间被调用。用于执行复杂的设置。

show_traceback_on_error = True

通过 Pdb.error 显示错误时的堆栈跟踪，这些错误来自 Pdb.default（即执行一个未识别的 pdb 命令），并且不是表达式本身的直接原因（例如，使用 doesnotexist 这样的命令导致的 NameError）。

如果禁用此选项，则仅打印 *** exception string，这通常缺少有用的上下文。

show_traceback_on_error_limit = None

当启用 show_traceback_on_error 时，此选项设置用于 traceback.format_exception 的限制。

编码规范

pdb++ 使用测试驱动开发，并尝试保持高测试覆盖率。

一般来说，每个提交都应该附带其自己的测试。如果是新功能，则应附带一个或多个测试用例来执行它。如果是错误修复，测试应在修复之前失败，修复之后通过。

目标是使未来的重构更容易：如果你想知道某一行代码为什么这样做，原则上你应该能够注释掉它并查看哪些测试会失败。

在特殊情况中，测试可能很难编写或无法编写：在这种情况下，可以进行不带测试的提交，但在提交信息中应非常精确地说明为什么难以编写测试以及如何手动重现错误行为。

在以下情况下，可以不编写测试：

• 拼写错误、文档和一般非编码提交

• 不添加任何功能的代码重构

• 修复已失败的测试的提交

• 静默警告的提交

• 仅涉及外观的改变，例如更改输出颜色