webob.exc — WebOb Exceptions

This module processes Python exceptions that relate to HTTP exceptions by defining a set of exceptions, all subclasses of HTTPException. Each exception, in addition to being a Python exception that can be raised and caught, is also a WSGI application and webob.Response object.

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.

Exception

Usage notes

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

Subclass attributes and call parameters are designed to provide an easier path through the complications.

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

body_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

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

body_template

a string.Template object containing a content fragment in HTML that frames the explanation and further detail

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.

The subclasses of _HTTPMove (HTTPMultipleChoices, HTTPMovedPermanently, HTTPFound, HTTPSeeOther, HTTPUseProxy and HTTPTemporaryRedirect) are redirections that require a Location field. Reflecting this, these subclasses have two additional keyword arguments: location and add_slash.

Parameters:

location

to set the location immediately

add_slash

set to True to redirect to the same URL as the request, except with a / appended

Relative URLs in the location will be resolved to absolute.

References:

[1]https://www.python.org/dev/peps/pep-0333/#error-handling
[2]https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5

HTTP Exceptions

exception webob.exc.HTTPException(message, wsgi_response)

exception webob.exc.WSGIHTTPException(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

exception webob.exc.HTTPError(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

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 webob.exc.HTTPRedirection(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

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 webob.exc.HTTPOk(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

Base class for the 200’s status code (successful responses)

code: 200, title: OK

exception webob.exc.HTTPCreated(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPOk

This indicates that request has been fulfilled and resulted in a new resource being created.

code: 201, title: Created

exception webob.exc.HTTPAccepted(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPOk

This indicates that the request has been accepted for processing, but the processing has not been completed.

code: 202, title: Accepted

exception webob.exc.HTTPNonAuthoritativeInformation(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPOk

This indicates that the returned metainformation in the entity-header is not the definitive set as available from the origin server, but is gathered from a local or a third-party copy.

code: 203, title: Non-Authoritative Information

exception webob.exc.HTTPNoContent(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPOk

This indicates that the server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.

code: 204, title: No Content

exception webob.exc.HTTPResetContent(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPOk

This indicates that the the server has fulfilled the request and the user agent SHOULD reset the document view which caused the request to be sent.

code: 205, title: Reset Content

exception webob.exc.HTTPPartialContent(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPOk

This indicates that the server has fulfilled the partial GET request for the resource.

code: 206, title: Partial Content

exception webob.exc._HTTPMove(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

redirections which require a Location field

Since a ‘Location’ header is a required attribute of 301, 302, 303, 305, 307 and 308 (but not 304), this base class provides the mechanics to make this easy.

You can provide a location keyword argument to set the location immediately. You may also give add_slash=True if you want to redirect to the same URL as the request, except with a / added to the end.

Relative URLs in the location will be resolved to absolute.

exception webob.exc.HTTPMultipleChoices(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource corresponds to any one of a set of representations, each with its own specific location, and agent-driven negotiation information is being provided so that the user can select a preferred representation and redirect its request to that location.

code: 300, title: Multiple Choices

exception webob.exc.HTTPMovedPermanently(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs.

code: 301, title: Moved Permanently

exception webob.exc.HTTPFound(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource resides temporarily under a different URI.

code: 302, title: Found

exception webob.exc.HTTPSeeOther(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource.

code: 303, title: See Other

exception webob.exc.HTTPNotModified(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPRedirection

This indicates that if the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server SHOULD respond with this status code.

code: 304, title: Not Modified

exception webob.exc.HTTPUseProxy(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource MUST be accessed through the proxy given by the Location field.

code: 305, title: Use Proxy

exception webob.exc.HTTPTemporaryRedirect(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource resides temporarily under a different URI.

code: 307, title: Temporary Redirect

exception webob.exc.HTTPClientError(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

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’

code: 400, title: Bad Request

exception webob.exc.HTTPBadRequest(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

exception webob.exc.HTTPUnauthorized(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the request requires user authentication.

code: 401, title: Unauthorized

exception webob.exc.HTTPPaymentRequired(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

code: 402, title: Payment Required

exception webob.exc.HTTPForbidden(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the server understood the request, but is refusing to fulfill it.

code: 403, title: Forbidden

exception webob.exc.HTTPNotFound(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the server did not find anything matching the Request-URI.

code: 404, title: Not Found

exception webob.exc.HTTPMethodNotAllowed(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the method specified in the Request-Line is not allowed for the resource identified by the Request-URI.

code: 405, title: Method Not Allowed

exception webob.exc.HTTPNotAcceptable(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates the resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.

code: 406, title: Not Acceptable

exception webob.exc.HTTPProxyAuthenticationRequired(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This is similar to 401, but indicates that the client must first authenticate itself with the proxy.

code: 407, title: Proxy Authentication Required

exception webob.exc.HTTPRequestTimeout(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the client did not produce a request within the time that the server was prepared to wait.

code: 408, title: Request Timeout

exception webob.exc.HTTPConflict(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the request could not be completed due to a conflict with the current state of the resource.

code: 409, title: Conflict

exception webob.exc.HTTPGone(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the requested resource is no longer available at the server and no forwarding address is known.

code: 410, title: Gone

exception webob.exc.HTTPLengthRequired(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the the server refuses to accept the request without a defined Content-Length.

code: 411, title: Length Required

exception webob.exc.HTTPPreconditionFailed(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the precondition given in one or more of the request-header fields evaluated to false when it was tested on the server.

code: 412, title: Precondition Failed

exception webob.exc.HTTPRequestEntityTooLarge(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the server is refusing to process a request because the request entity is larger than the server is willing or able to process.

code: 413, title: Request Entity Too Large

exception webob.exc.HTTPRequestURITooLong(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the server is refusing to service the request because the Request-URI is longer than the server is willing to interpret.

code: 414, title: Request-URI Too Long

exception webob.exc.HTTPUnsupportedMediaType(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.

code: 415, title: Unsupported Media Type

exception webob.exc.HTTPRequestRangeNotSatisfiable(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

The server SHOULD return a response with this status code if a request included a Range request-header field, and none of the range-specifier values in this field overlap the current extent of the selected resource, and the request did not include an If-Range request-header field.

code: 416, title: Request Range Not Satisfiable

exception webob.exc.HTTPExpectationFailed(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indidcates that the expectation given in an Expect request-header field could not be met by this server.

code: 417, title: Expectation Failed

exception webob.exc.HTTPUnprocessableEntity(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the server is unable to process the contained instructions.

code: 422, title: Unprocessable Entity

exception webob.exc.HTTPLocked(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the resource is locked.

code: 423, title: Locked

exception webob.exc.HTTPFailedDependency(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the method could not be performed because the requested action depended on another action and that action failed.

code: 424, title: Failed Dependency

exception webob.exc.HTTPPreconditionRequired(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the origin server requires the request to be conditional. From RFC 6585, “Additional HTTP Status Codes”.

code: 428, title: Precondition Required

exception webob.exc.HTTPTooManyRequests(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the client has sent too many requests in a given amount of time. Useful for rate limiting.

From RFC 6585, “Additional HTTP Status Codes”.

code: 429, title: Too Many Requests

exception webob.exc.HTTPRequestHeaderFieldsTooLarge(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the server is unwilling to process the request because its header fields are too large. The request may be resubmitted after reducing the size of the request header fields.

From RFC 6585, “Additional HTTP Status Codes”.

code: 431, title: Request Header Fields Too Large

exception webob.exc.HTTPUnavailableForLegalReasons(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPClientError

This indicates that the server is unable to process the request because of legal reasons, e.g. censorship or government-mandated blocked access.

From the draft “A New HTTP Status Code for Legally-restricted Resources” by Tim Bray:

https://tools.ietf.org/html/draft-tbray-http-legally-restricted-status-00

code: 451, title: Unavailable For Legal Reasons

exception webob.exc.HTTPServerError(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

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 webob.exc.HTTPInternalServerError(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

exception webob.exc.HTTPNotImplemented(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPServerError

This indicates that the server does not support the functionality required to fulfill the request.

code: 501, title: Not Implemented

exception webob.exc.HTTPBadGateway(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPServerError

This indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.

code: 502, title: Bad Gateway

exception webob.exc.HTTPServiceUnavailable(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPServerError

This indicates that the server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

code: 503, title: Service Unavailable

exception webob.exc.HTTPGatewayTimeout(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPServerError

This indicates that the server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.

code: 504, title: Gateway Timeout

exception webob.exc.HTTPVersionNotSupported(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPServerError

This indicates that the server does not support, or refuses to support, the HTTP protocol version that was used in the request message.

code: 505, title: HTTP Version Not Supported

exception webob.exc.HTTPInsufficientStorage(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPServerError

This indicates that the server does not have enough space to save the resource.

code: 507, title: Insufficient Storage

exception webob.exc.HTTPNetworkAuthenticationRequired(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, \*kw*)

subclass of HTTPServerError

This indicates that the client needs to authenticate to gain network access. From RFC 6585, “Additional HTTP Status Codes”.

code: 511, title: Network Authentication Required

exception webob.exc.HTTPExceptionMiddleware(application)

Middleware that catches exceptions in the sub-application. This does not catch exceptions in the app_iter; only during the initial calling of the application.

This should be put very close to applications that might raise these exceptions. This should not be applied globally; letting expected exceptions raise through the WSGI stack is dangerous.