Using the Python debugger (pdb)

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 exception⁶. This feature can also be turned on and off 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.

If you want more information on the use of the pdb debugger, read the included pdb.doc file (part of the standard Python distribution). On a stock Mandrake Linux system it is located at /usr/lib/python2.2/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]: pdb.help()

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