9. The Python Debugger

The module pdb defines an interactive source code debugger for Python programs. It supports setting breakpoints and single stepping at the source line level, inspection of stack frames, source code listing, and evaluation of arbitrary Python code in the context of any stack frame. It also supports post-mortem debugging and can be called under program control.

The debugger is extensible --- it is actually defined as a class Pdb. This is currently undocumented but easily understood by reading the source. The extension interface uses the (also undocumented) modules bdb and cmd. A primitive windowing version of the debugger also exists --- this is module wdb, which requires STDWIN (see the chapter on STDWIN specific modules). The debugger's prompt is ``(Pdb) ''. Typical usage to run a program under control of the debugger is:

>>> import pdb
>>> import mymodule

>>> pdb.run('mymodule.test()')

> <string>(0)?()

(Pdb) continue

> <string>(1)?()

(Pdb) continue

NameError: 'spam'

> <string>(1)?()

(Pdb)

Typical usage to inspect a crashed program is:

>>> import pdb
>>> import mymodule

>>> mymodule.test()

Traceback (innermost last):

  File "<stdin>", line 1, in ?

  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)

The module defines the following functions; each enters the debugger in a slightly different way:

run (statement[, globals[, locals]]) -- function of module pdb: Execute the statement (given as a string) under debugger control. The debugger prompt appears before any code is executed; you can set breakpoints and type continue, or you can step through the statement using step or next (all these commands are explained below). The optional globals and locals arguments specify the environment in which the code is executed; by default the dictionary of the module __main__ is used. (See the explanation of the exec statement or the eval() built-in function.)

runeval (expression[, globals[, locals]]) -- function of module pdb: Evaluate the expression (given as a a string) under debugger control. When runeval() returns, it returns the value of the expression. Otherwise this function is similar to run().

runcall (function[, argument, ...]) -- function of module pdb: Call the function (a function or method object, not a string) with the given arguments. When runcall() returns, it returns whatever the function call returned. The debugger prompt appears as soon as the function is entered.

set_trace () -- function of module pdb: Enter the debugger at the calling stack frame. This is useful to hard-code a breakpoint at a given point in a program, even if the code is not otherwise being debugged (e.g. when an assertion fails).

post_mortem (traceback) -- function of module pdb: Enter post-mortem debugging of the given traceback object.

pm () -- function of module pdb: Enter post-mortem debugging of the traceback found in sys.last_traceback.

9. The Python Debugger

Menu