next up previous
Next: Extensions for syntax processing Up: IPython An enhanced Interactive Previous: Embedding IPython


Using the Python debugger (pdb)

Running entire programs via pdb

pdb, the Python debugger, is a powerful interactive debugger which allows you to step through code, set breakpoints, watch variables, etc. IPython makes it very easy to start any script under the control of pdb, regardless of whether you have wrapped it into a `main()' function or not. For this, simply type `%run -d myscript' at an IPython prompt. See the %run command's documentation (via `%run?' or in Sec. 6.2) for more details, including how to control where pdb will stop execution first.

For more information on the use of the pdb debugger, read the included pdb.doc file (part of the standard Python distribution). On a stock Linux system it is located at /usr/lib/python2.3/pdb.doc, but the easiest way to read it is by using the help() function of the pdb module as follows (in an IPython prompt):

In [1]: import pdb 
In [2]:

This will load the pdb.doc document in a file viewer for you automatically.

Automatic invocation of pdb on exceptions

IPython, if started with the -pdb option (or if the option is set in your rc file) can call the Python pdb debugger every time your code triggers an uncaught exception6. This feature can also be toggled at any time with the %pdb magic command. This can be extremely useful in order to find the origin of subtle bugs, because pdb opens up at the point in your code which triggered the exception, and while your program is at this point `dead', all the data is still available and you can walk up and down the stack frame and understand the origin of the problem.

Furthermore, you can use these debugging facilities both with the embedded IPython mode and without IPython at all. For an embedded shell (see sec. 9), simply call the constructor with `-pdb' in the argument string and automatically pdb will be called if an uncaught exception is triggered by your code.

For stand-alone use of the feature in your programs which do not use IPython at all, put the following lines toward the top of your `main' routine:

import sys,IPython.ultraTB  
sys.excepthook = IPython.ultraTB.FormattedTB(mode=`Verbose', color_scheme=`Linux', call_pdb=1)

The mode keyword can be either `Verbose' or `Plain', giving either very detailed or normal tracebacks respectively. The color_scheme keyword can be one of `NoColor', `Linux' (default) or `LightBG'. These are the same options which can be set in IPython with -colors and -xmode.

This will give any of your programs detailed, colored tracebacks with automatic invocation of pdb.

next up previous
Next: Extensions for syntax processing Up: IPython An enhanced Interactive Previous: Embedding IPython
Fernando Perez 2005-04-12