1.6.1 Basic Usage

The easiest way of catching and handling errors in Python is to use a try:.. except:.. block around all your code as shown below:

try:
    raise Exception('This error will be caught')
except:
    print "An error occured"

If you want to produce more detailed error reports you can do something like this:

try:
    raise Exception('This error will be caught and nicely displayed')
except:
    import web.error
    print web.error.info(output='traceback', format='text')

If no parameters are specified in the web.error.info() function the result returned is a full HTML debug representation of the error similar to that produced by the cgitb module.

Often a more convenient way to catch errors is by using the web.error.handle() method. If an error is raised it will be automatically handled. The default behaviour is to print a Content-type header followed by HTML information about the error suitable for display in a web browser. This can be done as follows:

import web.error
web.error.handle()

raise Exception('This error will be caught and nicely displayed for a web browser')

Python allows you to put both lines of code on one line to make things look neater if you use a ; so in some of the following samples the error handling initialising will look like this:

import web.error; web.error.handle()

Agian a full HTML page giving the tracback of the error is displayed together with the HTTP header for display in a browser.

#!/usr/bin/env python

# show python where the web modules are
import sys; sys.path.append('../'); sys.path.append('../../../')

import web.error; web.error.handle()
raise Exception('This is a test exception')

You can specify the information displayed by the web.error.handle() function by passing any parameters that can be passed to the web.error.info() function, but if you do this you should also specify the handler you wish to use. The example below prints a text representation of the code which caused the error to a web browser:

import web.error
web.error.handle(
    handler  = 'browser',
    output   = 'code', 
    format   = 'text',
)

Finally, you may wish to use a different error handler, for example you may wish to log the error to a file rather than displaying it. You can specify the handler parameter as a string representing the name of the handler you wish to use. Any extra parameters the handler takes can also be specified in the handle() function. In this example filename is a parameter used by the file handler and output and format are used by the web.error.info() function to create a representation of the error:

import web.error
web.error.handle(
    handler  = 'file',
    filename = 'test.html',
    output   = 'traceback', 
    format   = 'text',
)

raise Exception('This error will be caught appended to the test.html file as a text format traceback')

This time the error will be logged to the file test.html and no output will be printed.

The next sections describe the options for the error() and info() functions and the various error handlers you can use with the handle() function provided in the web.error.handler module. The final section describes how you can create custom error handlers for even more advanced error handling.

There is a section in the documentation for the web.wsgi module describing how error handling could be performed in a Web Server Gateway Interface application.