1.6.2 Using the built in handlers

If you want more control over the format of the error messages you can use one of the handlers in web.error.handler.

The web.error.handle() function has the following parameters:

handle( [customHandler=None], [context=5], [**params]): The customHandler parameter can be any error handler function including those in the web.error.handler module. context which sets how many lines of code to display in tracebacks and can be set independantly of your error handler and the values will be built into the values in the dict parameter. All other parameters are passed to the second parameter of the customHandler as a dictionary.

In the example below we specify customHandler as the web.error.handler.text handler to ouput a text representation of the error:

import web.error, web.error.handler; web.error.handle(web.error.handler.text)
# This is line 2
# This is line 3
# This is line 4
# This is line 5
raise Exception('This error will be caught and nicely displayed')
# This is line 7
# This is line 8
# This is line 9
# This is line 10

This produces the output:

Content-type: text/plain


Exception
Python 2.2.3 : C:\WINDOWS\Python22\pythonw.exe
Sat Jul 10 17:43:09 2004

A problem occurred in a Python script.  Here is the sequence of
function calls leading up to the error, in the order they occurred.

 C:\Work\PythonWeb.org\CVS Branches\PythonWeb.org 0.4\doc\src\lib\test.py 
    4 # This is line 4
    5 # This is line 5
    6 raise Exception('This error will be caught and nicely displayed')
    7 # This is line 7
    8 # This is line 8
Exception undefined
Exception: This error will be caught and nicely displayed
    args = ('This error will be caught and nicely displayed',)

The above is a description of an error in a Python program.  Here is
the original traceback:

Traceback (most recent call last):
  File "test.py", line 6, in ?
    raise Exception('This error will be caught and nicely displayed')
Exception: This error will be caught and nicely displayed

Note that the handler printed Content-type HTTP header. This is so that the output could be displayed in a web browser. If this header wasn't displayed you would see an Internal Server Error 500 message in the browser.

If you are not writing a web application you can configure the error handler not to display the HTTP header. You can pass parameters to all of the handlers by specifying them as param=value pairs in the web.error.handle() function after the first parameter as shown in the example below.

The example below would produce the same output but without the HTTP header:

import web.error, web.error.handler; web.error.handle(web.error.handler.text, header=False)

If you want to control the number of lines of code displayed in the error output you can set the context parameter. This is the number of lines to be displayed around each line of the traceback. In the example below we set context=3 to reduce the amount of output:

import web.error, web.error.handler; web.error.handle(web.error.handler.text, header=False, context=3)

The output is:

Exception
Python 2.2.3 : C:\WINDOWS\Python22\pythonw.exe
Sat Jul 10 17:47:18 2004

A problem occurred in a Python script.  Here is the sequence of
function calls leading up to the error, in the order they occurred.

 C:\Work\PythonWeb.org\CVS Branches\PythonWeb.org 0.4\doc\src\lib\test.py 
    5 # This is line 5
    6 raise Exception('This error will be caught and nicely displayed')
    7 # This is line 7
Exception undefined
Exception: This error will be caught and nicely displayed
    args = ('This error will be caught and nicely displayed',)

The above is a description of an error in a Python program.  Here is
the original traceback:

Traceback (most recent call last):
  File "test.py", line 8, in ?
    raise Exception('This error will be caught and nicely displayed')
Exception: This error will be caught and nicely displayed

Note that there are fewer lines of code in the code display of the traceback than before.

There are three built-in handlers besides web.error.handler.text used in the examples so far. All of the built-in handlers support the context parameter to adjust the number of lines of code displayed in the output.

web.error.handler.text

Produces a text output of the code and the traceback. By default an HTTP header is produced but this can be disabled by setting header to False.

web.error.handler.html

Produces an HTML output of the code and the traceback. By default an HTTP header is produced but this can be disabled by setting header to False.

web.error.handler.textfile

Writes a text output of the code and the traceback to the file specified by the file parameter. By default a line is printed to inform the user that the error occured. This can be disabled by setting print to False.

Warning: Every time an error occurs the file is over-written.

web.error.handler.htmlfile

Writes an HTML output of the code and the traceback to the file specified by the file parameter. By default a line is printed to inform the user that the error occured. This can be disabled by setting print to False.

Warning: Every time an error occurs the file is over-written.

All of the handlers are used in the same way.

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