Exceptions, HTTP Errors, and Redirects¶
Issuing redirects and HTTP errors¶
Here's how to send redirects and HTTP errors in Pyramid compared to Pylons:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
# Pylons -- in controller action from pylons.controllers.util import abort, redirect abort(404) # Not Found abort(403) # Forbidden abort(400) # Bad request; e.g., invalid query parameter abort(500) # Internal server error redirect(url("section1")) # Redirect (default 302 Found) # Pyramid -- in view code import pyramid.httpexceptions as exc raise exc.exception_response(400) # Not Found raise exc.HTTPNotFound() # Same thing return exc.HTTPNotFound() # Same thing raise exc.HTTPForbidden() raise exc.HTTPBadRequest() raise exc.HTTPInternalServerError() raise exc.HTTPFound(request.route_url("section1")) # Redirect
pyramid.httpexceptions module has classes for all official HTTP
statuses. These classes inherit from both
you can either return them or raise them. Raising HTTP exceptions can make
your code structurally more readable. It's particularly useful in
subroutines where it can cut through several calling stack frames that would
otherwise each need an
if to pass the error condition through.
- Pyramid internally raises
HTTPNotFoundif no route matches the request, or if no view matches the route and request. It raises
HTTPForbiddenif the request is denied based on the current authorization policy.
- If an uncaught exception occurs during request processing, Pyramid will catch it and look for an "exception view" that matches it. An exception view is one whose context argument is the exception's class, an ancestor of it, or an interface it implements. All other view predicates must also match; e.g., if a 'route_name' argument is specified, it must match the actual route name. (Thus an exception view is typically registered without a route name.) The view is called with the exception object as its context, and whatever response the view returns will be sent to the browser. You can thus use an exception view to customize the error screen shown to the user.
- If no matching exception view is found, HTTP exceptions are their own response so they are sent to the browser. Standard HTTPExceptions have a simple error message and layout; subclasses can customize this.
- Non-HTTPException responses propagate to the WSGI server. If the debug toolbar tween is enabled, it will catch the exception and display the interactive traceback. Otherwise the WSGI server will catch it and send its own "500 Internal Server Error" screen.
Here are the most popular HTTP exceptions:
|HTTPMovedPermanently||301||Y||Permanent redirect; client should change bookmarks.|
|HTTPFound||302||Y||Temporary redirect. |
|HTTPSeeOther||303||Y||Temporary redirect; client should use GET. |
|HTTPTemporaryRedirect||307||Y||Temporary redirect. |
|HTTPClientError||400||N||General user error; e.g., invalid query param.|
|HTTPUnauthorized||401||N||User must authenticate.|
|HTTPForbidden||403||N||Authorization failure, or general refusal.|
|HTTPNotFound||404||N||The URL is not recognized.|
|HTTPGone||410||N||The resource formerly at this URL is permanently gone; client should delete bookmarks.|
|HTTPInternalServerError||500||N||The server could not process the request due to an internal error.|
The constructor args for classes with a "Y" in the location column are
(location="", detail=None, headers=None, comment=None, ...). Otherwise the
constructor args are
(detail=None, headers=None, comment=None, ...).
location argument is optional at the Python level, but the HTTP spec
requires a location that's an absolute URL, so it's effectively required.
detail argument may be a plain-text string which will be incorporated
into the error screen.
headers may be a list of HTTP headers (name-value
tuples) to add to the response.
comment may be a plain-text string which is
not shown to the user. (XXX Is it logged?)
You can register an exception view for any exception class, although it's most
commonly used with
HTTPForbidden. Here's an example of
an exception view with a custom exception, borrowed from the Pyramid manual:
1 2 3 4 5 6 7 8 9 10 11 12 13
from pyramid.response import Response class ValidationFailure(Exception): pass @view_config(context=ValidationFailure) def failed_validation(exc, request): # If the view has two formal arguments, the first is the context. # The context is always available as ``request.context`` too. msg = exc.args if exc.args else "" response = Response('Failed validation: %s' % msg) response.status_int = 500 return response
For convenience, Pyramid has special decorators and configurator methods to
register a "Not Found" view or a "Forbidden" view.
@forbidden_view_config (defined in
pyramid.view) takes care of the
context argument for you.
@notfound_view_config accepts an
which can be used to enforce a trailing-slash convention. If your site defines
all its routes to end in a slash and you set
append_slash=True, then when
a slashless request doesn't match any route, Pyramid try again with a slash
appended to the request URL. If that matches a route, Pyramid will issue a
redirect to it. This is useful only for sites that prefer a trailing slash
("/dir/" and "/dir/a/"). Other sites prefer not to have a trailing slash
("/dir" and "/dir/a"), and there are no special features for this.