Python Cookbook

Starting the Debugger Automatically After an Uncaught Exception

Credit: Thomas Heller

Problem

When running a script, Python normally responds to uncaught exceptions by printing a traceback and terminating execution, but you would prefer to automatically enter an interactive debugger in such cases when feasible.

Solution

By setting sys.excepthook, you can control what happens after uncaught exceptions:

# code snippet to be included in sitecustomize.py
# Needs Python 2.1 or later!
import sys

def info(type, value, tb):
   if hasattr(sys, 'ps1') or not sys.stderr.isatty(  ):
      # You are in interactive mode or don't have a tty-like
      # device, so call the default hook
      sys._ _excepthook_ _(type, value, tb)
   else:
      import traceback, pdb
      # You are NOT in interactive mode; print the exception...
      traceback.print_exception(type, value, tb)
      print
      # ...then start the debugger in post-mortem mode
      pdb.pm(  )

sys.excepthook = info

Discussion

When Python runs a script and an uncaught exception is raised, a traceback is printed to standard error, and the script is terminated. Python 2.1 has introduced sys.excepthook, which can be used to override the handling of uncaught exceptions. This lets you automatically start the debugger on an unexpected exception when Python is not running in interactive mode but a tty-like device is available.

The code in this recipe is meant to be included in sitecustomize.py, which is automatically imported by Python at startup. The debugger is started only when Python is run in noninteractive mode, and only when a tty-like device is available for interactive debugging. (Thus, it is not started for CGI scripts, daemons, and so on; to handle such cases, see Recipe 14.3.) If you do not have a sitecustomize.py file, create one and place it somewhere on your Python path (normally in the site-packages directory).

A nice further extension to this recipe would be to detect if a GUI IDE is in use, and in this case, trigger the IDE’s appropriate debugging environment rather than Python’s own core pdb, which is appropriate only for text-interactive use. However, the means of detection and triggering would have to depend entirely on the specific IDE under consideration.

See Also

Recipe 14.3; documentation on the _ _excepthook_ _ function in the sys module and the traceback, sitecustomize, and pdb modules in the Library Reference.