This encapsulates an HTTP response that interrupts normal application flow; but one which is not necessarly an error condition. For example, codes in the 300's are exceptions in that they interrupt normal processing; however, they are not considered errors.

This class is complicated by 4 factors:

1. The content given to the exception may either be plain-text or as html-text.
2. The template may want to have string-substitutions taken from the current environ or values from incoming headers. This is especially troublesome due to case sensitivity.
3. The final output may either be text/plain or text/html mime-type as requested by the client application.
4. Each exception has a default explanation, but those who raise exceptions may want to provide additional detail.

Attributes:

code

the HTTP status code for the exception

title

remainder of the status line (stuff after the code)

explanation

a plain-text explanation of the error message that is not subject to environment or header substitutions; it is accessible in the template via %(explanation)s

detail

a plain-text message customization that is not subject to environment or header substitutions; accessible in the template via %(detail)s

template

a content fragment (in HTML) used for environment and header substitution; the default template includes both the explanation and further detail provided in the message

required_headers

a sequence of headers which are required for proper construction of the exception

Parameters:

detail

a plain-text override of the default detail

headers

a list of (k,v) header pairs

comment

a plain-text additional information which is usually stripped/hidden for end-users

To override the template (which is HTML content) or the plain-text explanation, one must subclass the given exception; or customize it after it has been created. This particular breakdown of a message into explanation, detail and template allows both the creation of plain-text and html messages for various clients as well as error-free substitution of environment variables and headers.