1.3.7 Debugger Entry Functions

The pydb module defines the following functions, and each enters the debugger in a slightly different way:

debugger( [dbg_cmds=None, add_exception_hook=True, add_threaddbg=False, status='start'])

Enter the debugger at the statement which follows (in execution) the debugger() statement. This hard-codes a call to the debugger at a given point in a program, even if the code is not otherwise being debugged. For example you might want to do this when an assertion fails.

It is useful in a couple of other situations. First, there may be some problem in getting the debugger to stop at this particular place for whatever reason (like flakiness in the debugger). Alternatively, using the debugger and setting a breakpoint can slow down a program a bit. But if you use this instead, the code will run as though the debugger is not present.

When the debugger is quitting, this causes the program to be terminated. If you want the program to continue instead, use the debugger function.

You can run debugger commands by passing this as a list in parameter dbg_cmds.

Unless add_exception_hook is set to False, we install an exception hook to enter the debugger on any otherwise not handled exception.

If you want experimental thread debugging support, set add_threaddbg to True.

Setting the parameter status to the string 'new' will cause a new instance to be created which might wiping out other instances which might contain information like breakpoints or debugger settings.

If instead status is set to 'continue', an existing instance will resume. Omitting status or setting it to 'start' will start the debugger which might be a 'new' depending on whether or not an instance has been created.

If instead `status' is set to 'continue', an existing instance will resume. Omitting status or setting it to 'start' will start the debugger which might be a 'new' depending on whether or not an instance has been created.

exception_hook( type, value, tb, dbg_cmds=None, cmdfile=None)

An exception hook to call pydb's post-mortem debugger.

cmdfile is an optional debugger command file you want to source commands on.

dbg_cmds is a list of debugger commands you want to run.

To use add this to your Python program:

       import sys
       sys.excepthook = pydb.exception_hook

pm( [dbg_cmds=None]): Enter post-mortem debugging of the traceback found in sys.last_traceback. Note you may need to have sys imported prior to having the error raised to have sys.last_traceback set.
You can run debugger commands by passing this as a list as parameter dbg_cmds. For example if you want the display listsize to be 20 by default on entry pass ["set listsize 20",].

post_mortem( traceback [, dbg_cmds=None, cmdfile=None])

Enter post-mortem debugging of the given traceback object.

You can run debugger commands by passing this as a list as parameter dbg_cmds. For example if you want the display listsize to be 20 by default on entry pass ["set listsize 20",].

run( statement[, globals[, locals]])

Execute the statement (given as a string) under debugger control starting with the statement subsequent to the place that the this appears in your program.

The debugger prompt appears before any code is executed; you can set breakpoints and type "continue", or you can step through the statement using "step" or "next" See 1.2.5 and 1.2.5 for explanations of these commands. The optional globals and locals arguments specify the environment in which the code is executed; by default the dictionary of the module __main__ is used. (See the explanation of the exec statement or the eval() built-in function.)

Note that this is not at all like pydb's (or GDB's) run (see 1.2.9) debugger command. This function should be called from inside the program you are trying to debug.

runcall( function[, argument, ...]): Call the function (a function or method object, not a string) with the given arguments starting with the statement subsequent to the place that the this appears in your program..
When runcall() returns, it returns whatever the function call returned. The debugger prompt appears as soon as the function is entered.

runeval( expression[, globals[, locals]]): Evaluate the expression (given as a string) under debugger control starting with the statement subsequent to the place that the this appears in your program.
When runeval() returns, it returns the value of the expression. Otherwise this function is similar to run().

runl( arg1 [, arg2...])

This is a way to call the debugger on a Python script (usually not the same one as is currently running) from inside Python. In particular this is useful inside Python shells. The parameters form the options to the debugger as well as the Python script to debug and options to pass to that.

For example:

        import pydb
        pydb.runl("--threading", "--nx",
                  "myscript", "--my-first-option" "myfirstarg")

Here --threading and --nx go to the debugger and myscript is the name of the Python program to run which gets the remaining parameters, --my-first-option and myfirstarg.

The 'l', suffix to indicate a list parameter is analogous to the use in os.spawnl(), or os.execl().

If you want to debug the current Python script, use debugger() described below.

runv( args)

This is a way to call the debugger on a Python script (usually not the same one as is currently running) from inside Python. In particular this is useful inside Python shells. The single parameter is a list of the options to the debugger as well as the Python script to debug and options to pass to that.

runl(*args) is also the same as runv((args)).

For example:

        import pydb
        args=("--threading", "--nx",
              "myscript", "--my-first-option" "myfirstarg")
        pydb.runv(args)

Here --threading and --nx go to the debugger and myscript is the name of the Python program to run which gets the remaining parameters, --my-first-option and myfirstarg.

The 'v', suffix to indicate a variable number of parameters is analogous to the use in os.spawnv(), or os.execv().

If you want to debug the current Python script, use debugger() described below.

set_trace( [dbg_cmds=None, add_exception_hook=True, add_threaddbg=False, new_instance=False]): Another name for debugger. This is the older name and is kept for backward compatibility with pdb. Also it is analogous to the underlying command used in the sys of the same name.

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