Norm Matloff's Introduction to the Winpdb Python Debugging Tool (not just for Windows!)

UPDATE!

The original author of Winpdb, Nir Aides, no longer supports the package. It has been taken over by Philippe Fremy as Winpdb Reborn.

The software is now packaged as a Wheel (.whl) file, which is actually .zip. I recommend simply unzipping it and running it directly if you are not well-versed on pip, Python library directories and so on.

About Winpdb and RPDB2:

The Winpdb package, by Nir Aides, is an excellent Python debugger. It is especially nice because it can handle the debugging of threads- and curses-based code. It is a remote debugger, meaning that it connects through the network to a remote site (which can be the same machine at which it is invoked, which is typical).

RPDB2 is text-based, while Winpdb is a GUI front end to RPDB2.

RPDB2 and Winpdb run on Linux, Windows and Mac systems. Winpdb requires the wxPython package, which is also freely downloadable for both systems. (My tutorial here is somewhat Linux-centric, but for the most part applies to Windows as well.)

Where to obtain them:

You can get them from Winpdb home page. Download the Winpdb package, which includes RPDB2.

Installation:

If you just intend to use the non-GUI form, i.e. just use RPDB2, you don't need to install wxPython. Just go straight to RPDB2 section below.

Actually, you need not formally install. Just unpack as below, and then each time you debug your source file x.py, run the debugger, say residing in directory /a/b/c/ by typing

python /a/b/c/winpdb.py x.py arg0 arg1 ...

You could even make a shell alias for this.

To formally install:

Unpack the .gz Winpdb package that you download, and enter the newly-created directory. From a shell window, type

python setup.py install -f

If you get an installation error, you need to install wxPython. I recommend that you let your OS do the work for you. In Fedora Core Linux, for instance, type

yum install wxPython

from a shell window. With Ubuntu Linux, use

sudo apt-get install python-wxgtk2.8

(or a later version number).

If you get a runtime error when you try Winpdb like "No module named winpdb," then you either have a permissions or a path problem.

Using Winpdb:

Like any software, Winpdb has a lot of bells and whistles. Here I only cover the basics.

Winpdb startup:

Say you have a script x.py to debug, with command-line arguments arg0, arg1 etc. Then to start Winpdb, type

winpdb x.py arg0 arg1 ...

Winpdb windows:

There are windows labeled Namespace, Threads, Stack, Source, Console and Command. Note especially those last two, as they give you direct access to the underlying RPDB2 engine. You can directly issue RPDB2 text commands in the Command window, and see messages from RPDB2 in the Console.

Winpdb variable views:

Click on Locals, Globals, Stack etc. as usual.

If you click on the little arrows to the left of some items in the Namespace window, Winpdb will expand them for you, to enable easier viewing.

For example, if there is an object or class, this expansion will allow you to inspect the member variables. Or, if you have a long list and want to know the value of, say, element number 59, this will make it a lot easier.

Winpdb source line colors:

Breakpoints are highlighted in red, except when a breakpoint is a current line, which then is highlighted in light blue.

The current line is highlighted in medium blue.

If you click on a line number, it will be highlighted in royal blue.

Winpdb execution:

A separate terminal window will pop up, for your program's keyboard input and screen output.

When your program is first started, a temporary breakpoint will be placed at the first statement in your source file.

To resume execution after stopping at a line, hit the Go button. There are also Step and Next buttons with the usual meanings, and a Return button, which finishes the remaining code in the current function.

Note that when the debuggee is waiting for input, the Go button will become dim, and the Break button will become bright. The latter can be used to interrupt execution.

To restart the program altogether, hit File | Restart.

Winpdb breakpoint actions:

To set a breakpoint, click just to the right of the line number (not ON the line number, and not in the source code region) in the Source window. Repeating the action deletes the breakpoint.

To set a conditional breakpoint, issue the text command directly to RPDB2 in the Command window. See Using RPDB2 below.

To disable/re-enable a breakpoint, click in the line and click on the Toggle Breakpoint button.

To set a temporary breakpoint and resume execution, click IN the desired line (not on the line number or next to it), and click on the Run to Line button. (If this is in a thread, make sure the thread has already begun execution.)

To do group breakpoint actions, e.g. delete all breakpoints, click on Breakpoints.

Breakpoints are retained between sessions.

Winpdb actions upon an exception:

When an exception occurs, you can do the following to learn what happened:

You will be asked if you want an explanation. If you say yes, you will get one, though it may be a bit cryptic.

The line at which the exception occurred will be highlighted in the Source window.

You can explore the stack in the Stack window.

Actions which must be done via the Command window:

Some actions must be done by giving direct text commands to RPDB2 in the Command window, such as:

Setting conditional breakpoints (bp).

Executing code that you supply (exec).

This is useful for setting variables, to experiment during the debugging process. If say you want to change the variable q to 8, type
```
exec q = 8
```
into the Command window.

Printing out the values of expressions (eval).

For example, to print the value of x[3], type
```
eval x[2]
```
into the Command window.

python rpdb2.py x.py arg0 arg1 ...

Of course, modify the above to point to the location of rpdb2.py.

RPDB2 execution:

A separate terminal window will pop up, for your program's keyboard input and screen output.

When your program is first started, a temporary breakpoint will be placed at the first statement in your source file.

To resume execution after stopping at a line, issue the Go command, g. There are also the Step and Next commands, s and n, as usual, and Return, r, to continue execution until the current function exits.

To restart the program altogether, issue the Restart command, restart.

RPDB2 breakpoint actions:

To set a breakpoint, use bp, e.g.

bp 9   # break at line 9
bp g   # break at the function g()
bp 9, x > 2.5  # break at line 9 if x > 2.5
bp gy.py:88  # break at line 88 of the source file gy.py

To disable/re-enable a breakpoint, use bd and be.

To clear, i.e. delete, a breakpoint, use bc.

To set a temporary breakpoint, use g, e.g.

g 12  # put temp breakpoint on line 12, and resume execution

To list your breakpoints, type bl.

Breakpoints are retained between sessions.

Miscellaneous RPDB2 commands:

help, for list of all available commands

help command, for help on a specific command

l, to list source code lines

eval, to print out the value of any expression, e.g.
```
eval w
eval x+y
eval len(w)
```

exec, to execute any Python code, e.g.
```
exec i = 3
exec g(8)
```
thread, for list of all threads

thread thread_number, to change execution to the specified thread

stack, to view the stack, up and down to traverse it