9. VIEWS

9.6 Custom Exception Views

The machinery which allows HTTP exceptions to be raised and caught by specialized views as described in Using Special Exceptions In View Callables can also be used by application developers to convert arbitrary exceptions to responses.

To register a view that should be called whenever a particular exception is raised from with Pyramid view code, use the exception class or one of its superclasses as the context of a view configuration which points at a view callable you’d like to generate a response.

For example, given the following exception class in a module named helloworld.exceptions:

1 class ValidationFailure(Exception):

2 def __init__(self, msg):

3self.msg = msg

You can wire a view callable to be called whenever any of your other code raises a helloworld.exceptions.ValidationFailure exception:

8return response

Assuming that a scan was run to pick up this view registration, this view callable will be invoked whenever a helloworld.exceptions.ValidationFailure is raised by your application’s view code. The same exception raised by a custom root factory, a custom traverser, or a custom view or route predicate is also caught and hooked.

Other normal view predicates can also be used in combination with an exception view registration:

8return response

100

9.7. USING A VIEW CALLABLE TO DO AN HTTP REDIRECT

The above exception view names the route_name of home, meaning that it will only be called when the route matched has a name of home. You can therefore have more than one exception view for any given exception in the system: the “most specific” one will be called when the set of request circumstances match the view registration.

The only view predicate that cannot be used successfully when creating an exception view configuration is name. The name used to look up an exception view is always the empty string. Views registered as exception views which have a name will be ignored.

latex-note.png

Normal (i.e., non-exception) views registered against a context resource type which inherits from Exception will work normally. When an exception view configuration is processed, two views are registered. One as a “normal” view, the other as an “exception” view. This means that you can use an exception as context for a normal view.

Exception views can be configured with any view registration mechanism: @view_config decorator or imperative add_view styles.

9.7 Using a View Callable to Do an HTTP Redirect

You can issue an HTTP redirect by using the pyramid.httpexceptions.HTTPFound class. Raising or returning an instance of this class will cause the client to receive a “302 Found” response.

To do so, you can return a pyramid.httpexceptions.HTTPFound instance.

Alternately, you can raise an HTTPFound exception instead of returning one.

When the instance is raised, it is caught by the default exception response handler and turned into a response.

101

9. VIEWS

9.8Handling Form Submissions in View Callables (Unicode and Character Set Issues)

Most web applications need to accept form submissions from web browsers and various other clients. In Pyramid, form submission handling logic is always part of a view. For a general overview of how to handle form submission data using the WebOb API, see Request and Response Objects and “Query and POST variables” within the WebOb documentation. Pyramid defers to WebOb for its request and response implementations, and handling form submission data is a property of the request implementation. Understanding WebOb’s request API is the key to understanding how to process form submission data.

There are some defaults that you need to be aware of when trying to handle form submission data in a Pyramid view. Having high-order (i.e., non-ASCII) characters in data contained within form submissions is exceedingly common, and the UTF-8 encoding is the most common encoding used on the web for character data. Since Unicode values are much saner than working with and storing bytestrings, Pyramid configures the WebOb request machinery to attempt to decode form submission values into Unicode from UTF-8 implicitly. This implicit decoding happens when view code obtains form field values via the request.params, request.GET, or request.POST APIs (see pyramid.request for details about these APIs).

latex-note.png

Many people find the difference between Unicode and UTF-8 confusing. Unicode is a standard for representing text that supports most of the world’s writing systems. However, there are many ways that Unicode data can be encoded into bytes for transit and storage. UTF-8 is a specific encoding for Unicode, that is backwards-compatible with ASCII. This makes UTF-8 very convenient for encoding data where a large subset of that data is ASCII characters, which is largely true on the web. UTF-8 is also the standard character encoding for URLs.

As an example, let’s assume that the following form page is served up to a browser client, and its action points at some Pyramid view code:

1 <html xmlns="http://www.w3.org/1999/xhtml">

2<head>

3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>

4</head>

5<form method="POST" action="myview">

6<div>

102

9.8. HANDLING FORM SUBMISSIONS IN VIEW CALLABLES (UNICODE AND CHARACTER SET ISSUES)

The myview view code in the Pyramid application must expect that the values returned by request.params will be of type unicode, as opposed to type str. The following will work to accept a form post from the above form:

But the following myview view code may not work, as it tries to decode already-decoded (unicode) values obtained from request.params:

3# characters in the firstname or lastname

4firstname = request.params[’firstname’].decode(’utf-8’)

5lastname = request.params[’lastname’].decode(’utf-8’)

For implicit decoding to work reliably, you should ensure that every form you render that posts to a Pyramid view explicitly defines a charset encoding of UTF-8. This can be done via a response that has a ;charset=UTF-8 in its Content-Type header; or, as in the form above, with a meta http-equiv tag that implies that the charset is UTF-8 within the HTML head of the page containing the form. This must be done explicitly because all known browser clients assume that they should encode form data in the same character set implied by Content-Type value of the response containing the form when subsequently submitting that form. There is no other generally accepted way to tell browser clients which charset to use to encode form data. If you do not specify an encoding explicitly, the browser client will choose to encode form data in its default character set before submitting it, which may not be UTF-8 as the server expects. If a request containing form data encoded in a non-UTF8 charset is handled by your view code, eventually the request code accessed within your view will throw an error when it can’t decode some high-order character encoded in another character set within form data, e.g., when request.params[’somename’] is accessed.

If you are using the Response class to generate a response, or if you use the render_template_* templating APIs, the UTF-8 charset is set automatically as the default via the Content-Type

103