Python debugging module Last changed: 2005-11-11 [11:17] Content: Information about my Python debugging module   Back to Personal Wiki Back to Python

Table of contents Debugging

Debugging

Python has nice capabilities for introspection which really helps when you want to debug a python script or program.

This debugging module demonstrates how you can get an informative debugging output from very simple debugging statements in the code.

The module source code can be downloaded here. It is also part of the webapp-config tool which has a live code repository here.

Basic usage

In order to use the module it must be placed somewhere in the PYTHONPATH. The code can then be imported using the following statement:

from debug import OUT

If it the file is located in a sub directory the name of the folder must be prepended (e.g. folder.debug). In addition the directory must be marked as a python package by adding an __init__.py file to the directory.

The imported OUT object can be used for debugging by adding a statement like this:

OUT.debug('What is happening here?')

It is obvious that this will probably print the given statement. But while such messages may be useful during debugging the main concern are the values of variables that are being used in the code.

It is not necessary to add them explicitly to the debug statement here since Python is capable of automatically extracting all variables from the caller of the debug function.

a = 1
b = 'Hello World'
OUT.debug('What is happening here?')

The example above would not only print the statement What is happening here? but in addition the values of variables a and b.

Here is a transcript of an example python session:

>>> from debug import OUT
>>> OUT.debug_on()
>>> OUT.color_off()
>>> a = 1
>>> b = 'Hello World'
>>> OUT.debug('What is happening here?')
    //---------------------------------------------------------------
    // Method: ?
    // ------------------> a:
    // 1
    // ------------------> b:
    // Hello World
    // ------------------> __builtins__:
    // <module '__builtin__' (built-in)>
    // ------------------> __name__:
    // __main__
    // ------------------> __doc__:
    // None
    // ------------------> OUT:
    // <debug.Message instance at 0xb7be784c>
    // What is happening here?

Since the example is executed within the scope of the python interpreter there are some additional parameters printed. So the output is somewhat too verbose but there are a number of methods available to control the amount of output.

Usage

The module provides two main methods of dealing with the amount of output:

• Either from within the python code
• or by using command line switches

Both have the same capabilities but it is more convenient to use the command line switches while debugging. Controlling debugging from within the code is usually only useful if the script or program does not accept any command line arguments.

Debug Control from within the code

To control the number debug statements that will actually yield output the following functions can be used from within the script.

OUT.debug_on():: This will set the debug level to the default value of 4.

OUT.set_debug_level(x):: Sets the debug level to x.

OUT.debug_off():: This will set the debug level to 0.

The debug level is a value ranging from 0 (no output) to 10 (maximal output). Every time you use the debug statement within your code you can specify the level at which this statement should still produce output:

OUT.debug('test', 7)

This statement would generate a message as long as the debugging level has been set to 7 or more.

OUT.set_debug_verbosity(x):: Set the verbosity of the debugging output. This does not influence the selection of statements actually displayed. It only varies the length and complexity of each message.

OUT.color_on():: Activates colored output.

OUT.color_off():: Turn colors off.

OUT.set_debug_methods(method_string):: A comma delimited string of method names to indicate the functions that should yield debug output.

OUT.set_debug_classes(classes_string):: A comma delimited string of class names to indicate the classes that should yield debug output.

OUT.set_debug_variables(variable_string):: A comma delimited string of variable names to indicate the variable values that should be included into the debug output.

OUT.class_variables_off():: Class variable will not be displayed in the debugging messages.

OUT.class_variables_on():: The values of class variables will be printed in addition to the local variables of the function.

Debug Control with command line arguments

Instead of calling the control functions from within the script code it is far more convenient to control the debugging features by using command line switches.

The only prerequisite for this is that the script or program needs to provide a handler for command line options, preferably the python optparse module. If that is the case one can use code similar to this in order to include the debugging options into the standard options provided by the program:

parser = OptionParser()
OUT.cli_opts(self.parser)

This will add the debugging option group to the parser. It is no problem to add more options before or after the cli_opts call.

To evaluate the switches used by the user of the program the debugging module provides a second method:

(options, args) = parser.parse_args()
OUT.cli_handle(options)

The following command line switches are provided:

• Necessary to switch debugging on.
• Set the level of debugging. The default level is 4. 0 selects no debugging statement, 10 selects all debugging statements.
• Set the verbosity of the debugging output to a value between 1 and 3. This does not remove or add any messages. It only varies the length/layout for each of the debug calls.
• A comma delimited list of method names. If you specify this option only debugging statements within functions that match one of the entries in the list will return any output.
• A comma delimited list of class names. If you specify this option only debugging statements within classes that have been named in the list will return any output.
• A comma delimited list of variable names. This list selects the variable values that will be printed with each debug statement.
• This flag will increase the amount of information for debugging statements within classes. For each debug statement the values of all class variables will also be included in the output. This option also works in conjunction with the --debug-variables option so you can keep the amount of output on a reasonable level.
• Deactivates the colors.

Additional functions

There are a number of additional output functions beside the main debugging function. These are short convenience function to return some (colored) output to the user.

The following are available:

OUT.notice(message)

Simply prints the given message

OUT.info(message)

Prints the given message and prepends a green asterisk.

OUT.status(message, status)

Prints the message and draws a little green [ok] or red [failed] box at the end of the line.

OUT.warn(message)

Prints the given message and prepends a yellow asterisk.

OUT.error(message)

Prints the given message and prepends a red asterisk.

OUT.die(message)

Prints the given message, prepends a red asterisk and exits.

Some of these functions (info, warn) allow to specify a level of significance like for the debug function.

Back to Personal Wiki

Back to Python