9.VIEWS

latex-note.png

You can also return objects from view callables that aren’t instances of pyramid.response.Response in various circumstances. This can be helpful when writing tests and when attempting to share code between view callables. See Renderers for the common way to allow for this. A much less common way to allow for view callables to return non-Response objects is documented in Changing How Pyramid Treats View Responses.

9.5 Using Special Exceptions In View Callables

Usually when a Python exception is raised within a view callable, Pyramid allows the exception to propagate all the way out to the WSGI server which invoked the application. It is usually caught and logged there.

However, for convenience, a special set of exceptions exists. When one of these exceptions is raised within a view callable, it will always cause Pyramid to generate a response. These are known as HTTP exception objects.

9.5.1 HTTP Exceptions

All classes documented in the pyramid.httpexceptions module documented as inheriting from the pryamid.httpexceptions.HTTPException are http exception objects. Instances of an HTTP exception object may either be returned or raised from within view code. In either case (return or raise) the instance will be used as as the view’s response.

For example, the pyramid.httpexceptions.HTTPUnauthorized exception can be raised. This will cause a response to be generated with a 401 Unauthorized status:

1

2

3

4

from pyramid.httpexceptions import HTTPUnauthorized

def aview(request):

raise HTTPUnauthorized()

An HTTP exception, instead of being raised, can alternately be returned (HTTP exceptions are also valid response objects):

98

9.5. USING SPECIAL EXCEPTIONS IN VIEW CALLABLES

1

2

3

4

from pyramid.httpexceptions import HTTPUnauthorized

def aview(request):

return HTTPUnauthorized()

A shortcut for creating an HTTP exception is the pyramid.httpexceptions.exception_response() function. This function accepts an HTTP status code and returns the corresponding HTTP exception. For example, instead of importing and constructing a HTTPUnauthorized response object, you can use

the exception_response() function to construct and return the same object.

1

2

3

4

from pyramid.httpexceptions import exception_response

def aview(request):

raise exception_response(401)

This is the case because 401 is the HTTP status code for “HTTP Unauthorized”. Therefore, raise exception_response(401) is functionally equivalent to raise HTTPUnauthorized(). Documentation which maps each HTTP response code to its purpose and its associated HTTP exception object is provided within pyramid.httpexceptions.

latex-note.png

The exception_response() function is new as of Pyramid 1.1.

9.5.2 How Pyramid Uses HTTP Exceptions

HTTP	exceptions	are	meant	to be used directly by		application	developers.	How-
ever,	Pyramid	itself	will	raise two HTTP exceptions at various points dur-
ing	normal	operations:		pyramid.httpexceptions.HTTPNotFound				and
pyramid.httpexceptions.HTTPForbidden.					Pyramid	will raise	the HTTPNotFound

exception are raised when it cannot find a view to service a request. Pyramid will raise the Forbidden exception or when authorization was forbidden by a security policy.

If HTTPNotFound is raised by Pyramid itself or within view code, the result of the Not Found View will be returned to the user agent which performed the request.

If HTTPForbidden is raised by Pyramid itself within view code, the result of the Forbidden View will be returned to the user agent which performed the request.

99