CHAPTER

TEN

RENDERERS

A view callable needn’t always return a Response object. If a view happens to return something which does not implement the Pyramid Response interface, Pyramid will attempt to use a renderer to construct a response. For example:

The above example returns a dictionary from the view callable. A dictionary does not implement the Pyramid response interface, so you might believe that this example would fail. However, since a renderer is associated with the view callable through its view configuration (in this case, using a renderer argument passed to view_config()), if the view does not return a Response object, the renderer will attempt to convert the result of the view to a response on the developer’s behalf.

Of course, if no renderer is associated with a view’s configuration, returning anything except an object which implements the Response interface will result in an error. And, if a renderer is used, whatever is returned by the view must be compatible with the particular kind of renderer used, or an error may occur during view invocation.

One exception exists: it is always OK to return a Response object, even when a renderer is configured. If a view callable returns a response object from a view that is configured with a renderer, the renderer is bypassed entirely.

Various types of renderers exist, including serialization renderers and renderers which use templating systems. See also Writing View Callables Which Use a Renderer.

107

10. RENDERERS

10.1 Writing View Callables Which Use a Renderer

As we’ve seen, view callables needn’t always return a Response object. Instead, they may return an arbitrary Python object, with the expectation that a renderer will convert that object into a response instance on your behalf. Some renderers use a templating system; other renderers use object serialization techniques.

View configuration can vary the renderer associated with a view callable via the renderer attribute. For example, this call to add_view() associates the json renderer with a view callable:

1 config.add_view(’myproject.views.my_view’, renderer=’json’)

When this configuration is added to an application, the myproject.views.my_view view callable will now use a json renderer, which renders view return values to a JSON response serialization.

Other built-in renderers include renderers which use the Chameleon templating language to render a dictionary to a response. Additional renderers can be added by developers to the system as necessary (see

Adding and Changing Renderers).

Views which use a renderer and return a non-Response value can vary non-body response attributes (such as headers and the HTTP status code) by attaching a property to the request.response attribute See

Varying Attributes of Rendered Responses.

If the view callable associated with a view configuration returns a Response object directly, any renderer associated with the view configuration is ignored, and the response is passed back to Pyramid unchanged. For example, if your view callable returns an instance of the pyramid.response.Response class as a response, no renderer will be employed.

Likewise for an HTTP exception response:

1 from pyramid.httpexceptions import HTTPFound

2 from pyramid.view import view_config

3

4 @view_config(renderer=’json’)

5 def view(request):

6return HTTPFound(location=’http://example.com’) # json renderer avoided

108