14.2. RESPONSE

•The pyramid.request.Request API documentation.

•The WebOb documentation. All methods and attributes of a webob.Request documented within the WebOb documentation will work with request objects created by Pyramid.

14.2 Response

The Pyramid response object can be imported as pyramid.response.Response. This class is a subclass of the webob.Response class. The subclass does not add or change any functionality, so the WebOb Response documentation will be completely relevant for this class as well.

A response object has three fundamental parts:

response.status: The response code plus reason message, like ’200 OK’. To set the code without a message, use status_int, i.e.: response.status_int = 200.

response.headerlist: A list of all the headers, like [(’Content-Type’, ’text/html’)]. There’s a case-insensitive multidict in response.headers that also allows you to access these same headers.

response.app_iter: An iterable (such as a list or generator) that will produce the content of the response. This is also accessible as response.body (a string), response.unicode_body (a unicode object, informed by response.charset), and response.body_file (a file-like object; writing to it appends to app_iter).

Everything else in the object typically derives from this underlying state. Here are some highlights:

response.content_type The content type not including the charset parameter. Typical use: response.content_type = ’text/html’.

response.charset: The charset parameter of the content-type, it also informs encoding in response.unicode_body. response.content_type_params is a dictionary of all the parameters.

response.set_cookie(key, value, max_age=None, path=’/’, ...): Set a cookie. The keyword arguments control the various cookie parameters. The max_age argument is the length for the cookie to live in seconds (you may also use a timedelta object). The Expires key will also be set based on the value of max_age.

response.delete_cookie(key, path=’/’, domain=None): Delete a cookie from the client. This sets max_age to 0 and the cookie value to ”.

response.cache_expires(seconds=0): This makes this response cacheable for the given number of seconds, or if seconds is 0 then the response is uncacheable (this also sets the Expires header).

response(environ, start_response): The response object is a WSGI application. As an application, it acts according to how you create it. It can do conditional responses if you pass conditional_response=True when instantiating (or set that attribute later). It can also do HEAD and Range requests.

169

14. REQUEST AND RESPONSE OBJECTS

14.2.1 Headers

Like the request, most HTTP response headers are available as properties. These are parsed, so you can do things like response.last_modified = os.path.getmtime(filename).

The details are available in the extracted Response documentation.

14.2.2 Instantiating the Response

Of course most of the time you just want to make a response. Generally any attribute of the response can be passed in as a keyword argument to the class; e.g.:

The status defaults to ’200 OK’. The content_type does not default to anything, though if you subclass pyramid.response.Response and set default_content_type you can override this behavior.

14.2.3 Exception Responses

To facilitate error responses like 404 Not Found, the module pyramid.httpexceptions contains classes for each kind of error response. These include boring, but appropriate error bodies. The exceptions exposed by this module, when used under Pyramid, should be imported from the pyramid.httpexceptions module. This import location contains subclasses and replacements that mirror those in the webob.exc module.

Each class is named pyramid.httpexceptions.HTTP*, where * is the reason for the error. For instance, pyramid.httpexceptions.HTTPNotFound subclasses pyramid.Response, so you can manipulate the instances in the same way. A typical example is:

14.2.4 More Details

More details about the response object API are available in the pyramid.response documentation. More details about exception responses are in the pyramid.httpexceptions API documentation. The WebOb documentation is also useful.

170