1.6.3 Using The handler() Function

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( [handler], [**params])

handler should be a string representing the name of a default handler to use or a custom handler function. The parameters specified by params are a combination of parameters used by the handler function chosen and any of the parameters output, format and context used to specify how the error information is displayed.

For example:

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

This would append a text format traceback of the error to the test.html file.

The default value for handler is 'browser' and the default display options produce a full HTML debug report so most of the time the following code is sufficient to add at the top of a CGI script:

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

In the example below we specify format as 'text' handler to ouput a text representation of the error:

import web.error; web.error.handle(handler='browser', output='debug', format='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

exceptions.Exception
Python 2.2.3 : C:\WINDOWS\Python22\pythonw.exe
Tue Jan 18 20:43:21 2005

    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\Web Modules 0.5\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
exceptions.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 might choose to use the 'print' handler instead of the 'browser' handler so that the Content-type HTTP header is not displayed.

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.handle(handler='print', output='debug', format='text', context=3)

The output is:

exceptions.Exception
Python 2.2.3 : C:\WINDOWS\Python22\pythonw.exe
Tue Jan 18 20:45:02 2005

    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\Web Modules 0.5\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
exceptions.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 there are fewer lines of code in the code display of the traceback than before.

If info is not specified in the handler() function, information can be produced in any of the formats supported by info() simply by passing the handler() function the parameters you would normally pass to info() and not specifying the info parameter. The exception to this rule it that handler() does not accept the output='class' option as this does not produce text output.

There are three built-in handlers each of which handle the error information generated in different ways.

'print' (web.error.handler.send())

Simply prints the error information to the standard output.

'browser' (web.error.handler.browser())

Sends the error information to the standard output after first sending an HTTP Content-type header for display in a web browser. You can over-ride the default header to be sent by specifying header. For example header='text/plain' would send a Content-type: text/plain HTTP header.

'file' (web.error.handler.file())

Writes the error information to the file specified by filename.

If no filename is specified, the error information is written to a file in the format 2005-01-18.log. If append is specified False the file is overwritten, the default is True meaning that error information is appended to the file. If dir is specified, files are logged to that directory, the default is to log to the script directory. Warning: It is good practice, but not enforced, to specify dir otherwise it is possible a logfile will overwrite a file of the same name.

If message is specified that message is sent to the standard output. Usually you should set message to be something like web.header('text/plain')+'An error occured and has been logged.'. Obviously you would not need to specify web.header('text/plain') if you are not outputting the error message to a web browser.

All of the handlers are used in the same way.