1.3 The Debugger Module (`pydb`) and Class (`Pdb`)

The module pydb defines a source-code debugger for Python programs which is command-line oriented.

pydb.py can be invoked as a script to debug other scripts. For example:

python -m pydb myscript.py

As with pydb invocation (see 1.1), myscript.py must be fully qualified as a file, no path-searching is done to find it. Also it must be Python source, not compiled or optimized versions. Finally you may have to adjust PYTHONPATH if the module pydb is not found.

When invoked as a script, pydb will automatically enter post-mortem debugging if the program being debugged exits abnormally. After post-mortem debugging (or after normal exit of the program), pydb will restart the program. Automatic restarting preserves pydb's state (such as breakpoints) and in most cases is more useful than quitting the debugger upon the program's exit.

The debugger is extensible--it is defined as the class Pdb. When creating a new Pdb object, command completion is available if readline or pyreadline is available. In such circumstance, one can optionally specifying the key for command completion. The parameter name here is completekey an its default value is the tab key.

The Pdb extension interface of Gdb a gdb-like debugger command interface. This in turn inherits from Cmd and Bdb. The Bdb class is described in the next section.

Cmd handles command-line aspects (e.g. keyboard input, completion, help system, top-level command-invocation), while Bdb handles debugger aspects (e.g. breakpoints, stepping, call stack formatting). However Cmd and Bdb go through two more modules pycmd and pybdb which are extensions of cmd and bdb respectively. In general these extensions are used to paper over deficiencies or differences in operation that are needed.

All of the methods intended for outside use are documented. In fact the help documentation for commands comes from the document strings of the corresponding methods.

One group of methods that may be useful to subclass would be the output methods errmsg, msg, and msg_nocr. In early regression development, I subclassed these so that I could capture debugger output. It turned out, however, that I needed far too many tests and working this way would not scale.

class Pdb( completekey='tab', stdin=None, stdout=None, siglist=None): Right now this is basically the same thing as the Gdb class. In the future though we may break out more stand-alone aspects and put them here versus an embedded debugger which is what Gdb would be used for.
See the Gdb class documentation for more information and information on the meanings of the parameters.

class Gdb( completekey='tab', stdin=None, stdout=None, siglist=None)

This debugger class for Python that resembles the gdb (GNU debugger) command set. Really we just inherit everything from the Gdb class, but we keep the name Pdb to be compatible with the stock Python debugger's (pdb's) Pdb class.

Parameter completekey specifies the what to use for command completion. pass None if no command completion is desired.

Parameters stdin and stdout specify where debugger input and output are to come from.

Parameter siglist gives a list of signals to intercept and ignore. None means the default set. If you want no signals, use [].

See About this document... for information on suggesting changes.

1.3 The Debugger Module (pydb) and Class (Pdb)

1.3 The Debugger Module (`pydb`) and Class (`Pdb`)