Debugging (notes)

last update: 2018-05-05

Immersive Debugging

Essentially, there are two ways of debugging Python source code. You can either change the code for debugging purposes or start the program with a proper debugger. In either case, you should start by making an educated guess on where the problem is hidden. In the case of immersive debugging you can either add print function calls or use a debugger's set_trace method.

Using print Statements

Once you've identified a potentially problematic location, add

print(locals(), "\n")

before and after the statements you want to investigate. Frequently, you'll add the statements as the first line of a function and right before its return statement. Then, execute the program with input that is known to produce unexpected results. If the function arguments are wrong, your problem is higher up the call stack. If the return values are incorrect, the function is responsible for the problem. If neither is unexpected, you need to keep looking for the problem elsewhere. As an alternative to using print(.), you could also use a logging function configured to log output when in debugging mode. This has the advantage of making useful changes persistent instead of adding and removing print statements.

Using a Logger

TODO: write notes about logging and add a link there (if students desire a session wrt logging).

Dropping into a Debugging Session

For those preferring not to use print(.), a debugger is a great way of finding bugs in source code. The immersive approach of using a debugger is to add

import ipdb

# ...
# this is where you expect things to go wrong
ipdb.set_trace()

to your code. Once you execute your program and the set_trace() call is reached, the program execution is halted and an interactive debugger is started. In case you don't have ipdb installed you can replace ipdb with pdb.

Non-Immersive Debugging

Python can be debugged with a number of different debugging tools. The commandline-debugger available with any Python 3 installation is pdb3. However, I'd prefer ipdb3. To use it, execute the program from the commandline like you'd normally would. However, replace python3 with your commanline debugger:

ipdb3 filename.py [arg] ...

To get help for ipdb, use its built-in help system

ipdb> h

A useful hint for the command-line debugger is that pressing the enter key on an otherwise empty command-line will repeat the last command. If you don't like the command-line debugger but don't have an IDE providing an interface to pdb, you could use pudb3. It is a nice console based GUI debugger. It has the advantages of being small, fast and swiftly usable over ssh connections. It is quite easy to learn its basic usage. Once installed, it can be used like any console based debugger
pudb3 filename.py [arg] ...

Finally, you could use a debugger made available by your favorite Python IDE. However, don't underestimate the effort of learning to properly use an IDE. This means that you should not switch to an IDE when being in a hurry to complete a small task. On the plus side, it will almost always pay off to learn a proper IDE. Excellent open source alternatives include KDevelop and Eclipse, each with a plugin for Python 3 development.

Installation of Different Debuggers

ipdb

sudo apt install python3-ipdb

pudb

sudo apt install python3-pudb
In case your package manager's version of pudb is too old (there are quite many bugs in older versions) install it via pip
sudo pip3 install pudb

kdevelop

sudo apt install kdevelop kdevelop-python