1.14.3.3 web.wsgi.error.documents

An error document is simply a web page which is used to let the user know that an error occured.

Note: You will often see "Internal Server Error" error documents if you are using Apache and a CGI script does not have the correct permissions for example. This is an error document. In Apache you can change the error page displayed using a .htaccess file. In WSGI you can use the error document middleware to provide custom error documents.

If a WSGI application or calls start_response() with a status which is not 200 and is not handled by any middleware, the server will need to display an error message or handle the error in appropriate way, usually by displaying an error document in a similar way to the way Apache would.

The error document middleware lets you intercept these status messages before they are sent to the server to display a custom error document.

The Documents class lets you specify error documents in three ways, as files, text, or by calling a function. Each of the three methods involves specifying the status code as an integer key to the dictionary and the object as the item.

For example, to specify a file error/500.html to be displayed if a 500 server error occurs you could specify files={500:'error/500.html'}. To specify a the error document as a text you could use the following: text={500:'<html><h1>Internal Server Error</h1></html>'}.

import web.wsgi.error.documents

def simpleApp(environ, start_response):
    start_response('500 There was a server error', [('Content-type','text/html')])
    return []
 
application = web.wsgi.error.documents.Documents(
    simpleApp,
    text = {
        500:"<html><body><h1>A server error occured</h1></body></html>"
    }
)

You can also provide more advanced error document handling by specifying a function to handle the error. For example:

def serverError(environ):
    import wsgi
    return """<html><h1>Internal Server Error</h1>
    <p>The page %s caused an error<\p></html>"""%wsgi.currentURL(environ)

You could then specify functions={500:serverError}. The environ paramter is the full WSGI environ dictionary passed to all WSGI applications, and as such can be used for advanced dynamic error document generation.

Note: You cannot specify different types of document for the same error. For example if you specify a text server error document for error 500, you cannot also specify a function server error document for error 500.

1.14.3.3 web.wsgi.error.documents - Error Documents

1.14.3.3 `web.wsgi.error.documents` - Error Documents