Docs4dev
Docs
python / 2.7.15 / all / library-pdb.html

26.2. pdb — Python 调试器

源代码： Lib/pdb.py

pdb模块为 Python 程序定义了一个交互式源代码调试器。它支持在源代码行级别设置(条件)断点和单步执行，检查堆栈框架，源代码列表以及在任何堆栈框架的上下文中评估任意 Python 代码。它还支持事后调试，可以在程序控制下调用。

调试器是可扩展的-实际上定义为类Pdb。目前尚无记录，但pass阅读源代码很容易理解。扩展接口使用模块bdb和cmd。

调试器的提示是(Pdb)。在调试器的控制下运行程序的典型用法是：

>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
> <string>(0)?()
(Pdb) continue
> <string>(1)?()
(Pdb) continue
NameError: 'spam'
> <string>(1)?()
(Pdb)

pdb.py也可以作为脚本调用来调试其他脚本。例如：

python -m pdb myscript.py

当作为脚本调用时，如果正在调试的程序异常退出，pdb 将自动进入事后调试。在事后调试之后(或在程序正常退出之后)，pdb 将重新启动该程序。自动重启会保留 pdb 的状态(例如断点)，并且在大多数情况下比在程序退出时退出调试器更为有用。

2.4 版的新Function：添加了重新启动验尸行为。

从正在运行的程序进入调试器的典型用法是插入

import pdb; pdb.set_trace()

在您想进入调试器的位置。然后，您可以单步执行此语句之后的代码，并使用c命令在没有调试器的情况下 continue 运行。

检查崩溃程序的典型用法是：

>>> import pdb
>>> import mymodule
>>> mymodule.test()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "./mymodule.py", line 4, in test
    test2()
  File "./mymodule.py", line 3, in test2
    print spam
NameError: spam
>>> pdb.pm()
> ./mymodule.py(3)test2()
-> print spam
(Pdb)

该模块定义了以下Function；每个都以略有不同的方式进入调试器：

  • pdb. run(* statement * [，* globals * [，* locals *]])

    • 在调试器控制下执行* statement (以字符串形式提供)。在执行任何代码之前，调试器提示会出现；您可以设置断点并键入continue，也可以使用step或next逐步执行该语句(下面将解释所有这些命令)。可选的 globals 和 locals *参数指定执行代码的环境；默认情况下，使用模块main的字典。 (请参见exec语句或eval()内置函数的说明。)

  • pdb. runeval(* expression * [，* globals * [，* locals *]])

    • 在调试器控制下评估* expression *(以字符串形式给出)。 runeval()返回时，它返回表达式的值。否则，此Function类似于run()。

  • pdb. runcall(* function * [，* argument ， ... *])

    • 使用给定的参数调用* function *(函数或方法对象，而不是字符串)。当runcall()返回时，它将返回所返回的函数调用。Importing Function后，调试器提示就会出现。

  • pdb. set_trace ( )

    • 在调用堆栈帧处 Importing 调试器。即使没有对代码进行调试(例如，assert 失败时)，这对于在程序中给定点硬编码断点也是很有用的。

  • pdb. post_mortem([* traceback *])

    • Importing 给定* traceback 对象的事后调试。如果没有给出 traceback *，它将使用当前正在处理的异常之一(如果要使用默认值，则必须处理异常)。

  • pdb. pm ( )

run*函数和set_trace()是用于实例化Pdb类并调用相同名称的方法的别名。如果要访问其他Function，则必须自己执行以下操作：

    • class * pdb. Pdb(* completekey ='tab'， stdin = None ， stdout = None ， skip = None *)
    • Pdb是调试器类。

  • completekey ， stdin 和 stdout *参数被传递给底层的cmd.Cmd类；看到那里的描述。

  • skip *参数(如果给定)必须是全局样式的模块名称模式的可迭代形式。调试器将不会进入源自与这些模式之一匹配的模块的框架。 [1]

使用* skip *启用跟踪的示例调用：

import pdb; pdb.Pdb(skip=['django.*']).set_trace()

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

  • run(* statement * [，* globals * [，* locals *]])
    • runeval(* expression * [，* globals * [，* locals *]])
    • runcall(* function * [，* argument ， ... *])
    • set_trace ( )
      • 有关上述Function的信息，请参阅文档。

26.3. 调试器命令

调试器可以识别以下命令。大多数命令可以缩写为一个或两个字母。例如h(elp)表示可以使用h或helpImporting 帮助命令(但不能 Importinghe或hel，也不能 ImportingH或Help或HELP)。命令的参数必须用空格(空格或制表符)分隔。可选参数用命令语法括在方括号([])中；禁止 Importing 方括号。命令语法中的其他选项由竖线(|)分隔。

Importing 空白行将重复最后 Importing 的命令。exception：如果最后一个命令是list命令，则会列出接下来的 11 行。

调试器无法识别的命令被假定为 Python 语句，并在被调试程序的上下文中执行。 Python 语句也可以带有感叹号(!)作为前缀。这是检查正在调试的程序的强大方法。甚至可以更改变量或调用函数。当此类语句中发生异常时，将打印异常名称，但调试器的状态不会更改。

可以在一行上 Importing 多个命令，并以;;分隔。 (不使用单个;，因为它是传递给 Python 解析器的一行中多个命令的分隔符.)没有智能可用于分隔命令。Importing 将在第一个;;对处拆分，即使它在带引号的字符串中间。

调试器支持别名。别名可以具有允许对被检查的上下文有一定程度的适应性的参数。

如果用户的主目录或当前目录中存在文件.pdbrc，则将其读入并执行，就像在调试器提示符下键入的一样。这对于别名特别有用。如果两个文件都存在，则首先读取主目录中的文件，并且本地文件可以覆盖其中定义的别名。

  • h(elp) [ command ]

    • 不带参数的情况下，显示可用命令的列表。以* command 作为参数，打印关于该命令的帮助。 help pdb显示完整的文档文件；如果定义了环境变量 PAGER，则会pass该命令pass管道传递文件。由于 command *参数必须是标识符，因此必须 Importinghelp exec以获得有关!命令的帮助。

  • w(here)

    • 打印堆栈跟踪，最新一帧在底部。箭头指示当前框架，该框架确定大多数命令的上下文。

  • d(own)

    • 将当前帧在堆栈跟踪中向下移动一级(到新的帧)。

  • u(p)

    • 将当前帧在堆栈跟踪中向上移动一级(到较旧的帧)。

  • b(reak)[[文件名：] * lineno * | Function [，条件]]

    • 使用* lineno 参数，在当前文件中在那里设置一个分隔符。使用 function *参数，在该函数中的第一个可执行语句处设置一个break。行号可以以文件名和冒号作为前缀，以在另一个文件(可能是尚未加载的文件)中指定一个断点。在sys.path上搜索文件。请注意，每个断点都分配有一个编号，所有其他断点命令都引用该编号。

如果存在第二个参数，则该表达式必须在接受断点之前计算为 true。

不带参数的情况下，列出所有break，包括每个断点，命中该断点的次数，当前忽略计数以及关联的条件(如果有)。

  • tbreak [[文件名：] * lineno * | Function [，条件]]

    • 临时断点，在第一次命中时会自动删除。参数与 break 相同。

  • cl(ear) [ filename:lineno | bpnumber [ bpnumber … ]]

    • 使用* filename：lineno *参数，清除此行上的所有断点。用空格分隔的断点列表，清除这些断点。不加 Arguments，清除所有break(但首先要求确认)。

  • disable [ bpnumber [ bpnumber … ]]

    • 禁用以空格分隔的断点编号列表形式给出的断点。禁用断点意味着它不会导致程序停止执行，但是与清除断点不同，它保留在断点列表中并且可以(重新)启用。

  • enable [ bpnumber [ bpnumber … ]]

    • 启用指定的断点。

  • 忽略* bpnumber * [* count *]

    • 设置给定断点号的忽略计数。如果Ellipsis count，则忽略计数将设置为 0.当忽略计数为零时，断点将变为活动状态。如果为非零值，则每次达到断点时该计数都会递减，并且不会禁用该断点，并且任何关联条件的评估结果为 true。

  • 条件* bpnumber * [条件]

    • 条件是必须遵守断点的表达式。如果不存在条件，则删除任何现有条件；即，将断点设为无条件。

  • commands [ bpnumber ]

    • 指定断点编号* bpnumber *的命令列表。命令本身出现在以下几行中。键入仅包含“ end”的行以终止命令。一个例子：
(Pdb) commands 1
(com) print some_variable
(com) end
(Pdb)

要从断点删除所有命令，请键入命令并立即以结尾结尾；也就是说，不要给出任何命令。

没有* bpnumber *参数，命令将引用最后一个断点集。

您可以使用断点命令重新启动程序。只需使用 continue 命令或 step 或任何其他恢复执行的命令。

指定任何恢复执行的命令(当前是 continue，上一步，下一个，返回，跳转，退出及其缩写)将终止命令列表(就像该命令紧随其后是结束一样)。这是因为任何时候恢复执行(即使是简单的下一步或步骤)，都可能会遇到另一个断点，该断点可能具有自己的命令列表，这导致要执行哪个列表有歧义。

如果在命令列表中使用“ silent”命令，则不会打印有关在断点处停止的常规消息。对于要打印特定消息然后 continue 的断点，这可能是理想的。如果没有其他命令可以打印任何内容，则看不到已达到断点的迹象。

2.5 版的新Function。

  • s(tep)

    • 执行当前行，在第一次可能的情况下停止(在调用的函数中或在当前函数的下一行中停止)。

  • n(ext)

    • continue 执行，直到到达当前函数的下一行或它返回为止。 (next和step之间的区别在于step停止在被调用函数内部，而next以(几乎)全速执行被调用函数，仅在当前函数的下一行停止。)

  • unt(il)

    • continue 执行直到行号大于当前行的行或从当前帧返回时为止。

2.6 版的新Function。

  • r(eturn)

    • continue 执行直到当前函数返回。

  • c(ont(inue))

    • continue 执行，仅在遇到断点时停止。

  • j(ump)* lineno *

    • 设置将要执行的下一行。仅在最底部的框架中可用。这使您可以跳回并再次执行代码，或跳到跳过不想运行的代码。

应该注意的是，并非所有跳转都是允许的-例如，不可能跳转到for循环的中间或finally子句的中间。

  • l(ist) [ first [, last ]]

    • 列出当前文件的源代码。不带参数的情况下，在当前行周围列出 11 行，或 continue 上一个列表。使用一个参数，在该行周围列出 11 行。用两个参数列出给定的范围；如果第二个参数小于第一个参数，则将其解释为一个计数。

  • a(rgs)

    • 打印当前函数的参数列表。

  • p 表达式

    • 在当前上下文中评估* expression *并打印其值。

Note

也可以使用print，但是它不是调试器命令-执行 Python print语句。

  • pp 表情

    • 与p命令相似，但表达式的值使用pprint模块进行了漂亮的打印。

  • alias [ name [command]]

    • 创建一个名为* name 的别名，该别名执行 command 。该命令不得用引号引起来。可以用%1，%2等表示可替换参数，而用所有参数替换%*。如果未给出命令，则显示 name *的当前别名。如果未提供任何参数，则会列出所有别名。

别名可以嵌套，并且可以包含可以在 pdb 提示符下合法键入的任何内容。请注意，内部 pdb 命令可以被别名覆盖。然后隐藏这样的命令，直到删除别名。别名以递归方式应用于命令行的第一个单词；该行中的所有其他单词都不要理会。

例如，以下是两个有用的别名(尤其是放在.pdbrc文件中时)：

#Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k]
#Print instance variables in self
alias ps pi self

  • 别名名称

    • 删除指定的别名。

  • [！] 语句

    • 在当前堆栈框架的上下文中执行(单行)语句。除非语句的第一个单词类似于调试器命令，否则可以Ellipsis感叹号。要设置全局变量，您可以在同一行上为赋值命令加上global命令作为前缀，例如：
(Pdb) global list_options; list_options = ['-l']
(Pdb)

  • run [ args …]

    • 重新启动调试的 Python 程序。如果提供了参数，则将其用“ shlex”拆分，并将结果用作新的 sys.argv。历史记录，断点，操作和调试器选项将保留。 “重新启动”是“运行”的别名。

2.6 版的新Function。

  • q(uit)

    • 从调试器退出。正在执行的程序被中止。

Footnotes

  • [1]
    • 帧是否被认为起源于某个模块由帧全局变量中的__name__确定。