paste.httpexceptions – Easily product HTTP errors

HTTP Exception Middleware

This module processes Python exceptions that relate to HTTP exceptions by defining a set of exceptions, all subclasses of HTTPException, and a request handler (middleware) that catches these exceptions and turns them into proper responses.

This module defines exceptions according to RFC 2068 1 : codes with 100-300 are not really errors; 400’s are client errors, and 500’s are server errors. According to the WSGI specification 2 , the application can call start_response more then once only under two conditions: (a) the response has not yet been sent, or (b) if the second and subsequent invocations of start_response have a valid exc_info argument obtained from sys.exc_info(). The WSGI specification then requires the server or gateway to handle the case where content has been sent and then an exception was encountered.

Exceptions in the 5xx range and those raised after start_response has been called are treated as serious errors and the exc_info is filled-in with information needed for a lower level module to generate a stack trace and log information.

Exception
HTTPException
HTTPRedirection

  • 300 - HTTPMultipleChoices

  • 301 - HTTPMovedPermanently

  • 302 - HTTPFound

  • 303 - HTTPSeeOther

  • 304 - HTTPNotModified

  • 305 - HTTPUseProxy

  • 306 - Unused (not implemented, obviously)

  • 307 - HTTPTemporaryRedirect

HTTPError
HTTPClientError

  • 400 - HTTPBadRequest

  • 401 - HTTPUnauthorized

  • 402 - HTTPPaymentRequired

  • 403 - HTTPForbidden

  • 404 - HTTPNotFound

  • 405 - HTTPMethodNotAllowed

  • 406 - HTTPNotAcceptable

  • 407 - HTTPProxyAuthenticationRequired

  • 408 - HTTPRequestTimeout

  • 409 - HTTPConfict

  • 410 - HTTPGone

  • 411 - HTTPLengthRequired

  • 412 - HTTPPreconditionFailed

  • 413 - HTTPRequestEntityTooLarge

  • 414 - HTTPRequestURITooLong

  • 415 - HTTPUnsupportedMediaType

  • 416 - HTTPRequestRangeNotSatisfiable

  • 417 - HTTPExpectationFailed

  • 429 - HTTPTooManyRequests

HTTPServerError

  • 500 - HTTPInternalServerError

  • 501 - HTTPNotImplemented

  • 502 - HTTPBadGateway

  • 503 - HTTPServiceUnavailable

  • 504 - HTTPGatewayTimeout

  • 505 - HTTPVersionNotSupported

References:

1

http://www.python.org/peps/pep-0333.html#error-handling

2

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5

Module Contents

class paste.httpexceptions.HTTPExceptionHandler(application, warning_level=None)

catches exceptions and turns them into proper HTTP responses

This middleware catches any exceptions (which are subclasses of HTTPException) and turns them into proper HTTP responses. Note if the headers have already been sent, the stack trace is always maintained as this indicates a programming error.

Note that you must raise the exception before returning the app_iter, and you cannot use this with generator apps that don’t raise an exception until after their app_iter is iterated over.

paste.httpexceptions.make_middleware(app, global_conf=None, warning_level=None)

httpexceptions middleware; this catches any paste.httpexceptions.HTTPException exceptions (exceptions like HTTPNotFound, HTTPMovedPermanently, etc) and turns them into proper HTTP responses.

warning_level can be an integer corresponding to an HTTP code. Any code over that value will be passed ‘up’ the chain, potentially reported on by another piece of middleware.

Exceptions

exception paste.httpexceptions.HTTPException(detail=None, headers=None, comment=None)

the HTTP exception base class

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.

exception paste.httpexceptions.HTTPError(detail=None, headers=None, comment=None)

base class for status codes in the 400’s and 500’s

This is an exception which indicates that an error has occurred, and that any work in progress should not be committed. These are typically results in the 400’s and 500’s.

exception paste.httpexceptions.HTTPRedirection(detail=None, headers=None, comment=None)

base class for 300’s status code (redirections)

This is an abstract base class for 3xx redirection. It indicates that further action needs to be taken by the user agent in order to fulfill the request. It does not necessarly signal an error condition.

exception paste.httpexceptions.HTTPMultipleChoices(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPMovedPermanently(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPFound(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPNotModified(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPUseProxy(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPTemporaryRedirect(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPClientError(detail=None, headers=None, comment=None)

base class for the 400’s, where the client is in-error

This is an error condition in which the client is presumed to be in-error. This is an expected problem, and thus is not considered a bug. A server-side traceback is not warranted. Unless specialized, this is a ‘400 Bad Request’

exception paste.httpexceptions.HTTPBadRequest(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPUnauthorized(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPPaymentRequired(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPForbidden(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPNotFound(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPMethodNotAllowed(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPNotAcceptable(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPProxyAuthenticationRequired(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPRequestTimeout(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPConflict(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPGone(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPLengthRequired(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPPreconditionFailed(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPRequestEntityTooLarge(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPRequestURITooLong(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPUnsupportedMediaType(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPRequestRangeNotSatisfiable(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPExpectationFailed(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPServerError(detail=None, headers=None, comment=None)

base class for the 500’s, where the server is in-error

This is an error condition in which the server is presumed to be in-error. This is usually unexpected, and thus requires a traceback; ideally, opening a support ticket for the customer. Unless specialized, this is a ‘500 Internal Server Error’

exception paste.httpexceptions.HTTPInternalServerError(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPNotImplemented(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPBadGateway(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPServiceUnavailable(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPGatewayTimeout(detail=None, headers=None, comment=None)
exception paste.httpexceptions.HTTPVersionNotSupported(detail=None, headers=None, comment=None)