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