The module pdb defines an interactive source code debugger for
Python programs. It supports setting
(conditional) 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)
pdb.py can also be invoked as
a script to debug other scripts. For example:
python /usr/local/lib/python1.4/pdb.py myscript.py
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]])
-
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]])
-
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, ...])
-
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 ()
-
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)
-
Enter post-mortem debugging of the given traceback object.
- pm ()
-
Enter post-mortem debugging of the traceback found in
sys.last_traceback.
guido@python.org