## 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')

This will produce a text format output of the traceback information.

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')

This will produce a full HTML page giving the debug traceback of the error.

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. 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.