commit | author | age
|
bf76ad
|
1 |
.. index:: |
c5f24b
|
2 |
single: Bicking, Ian |
590fe7
|
3 |
single: WebOb |
bf76ad
|
4 |
|
d5b2f4
|
5 |
.. _webob_chapter: |
CM |
6 |
|
888d65
|
7 |
Request and Response Objects |
CM |
8 |
============================ |
bf76ad
|
9 |
|
CM |
10 |
.. note:: This chapter is adapted from a portion of the :term:`WebOb` |
|
11 |
documentation, originally written by Ian Bicking. |
888d65
|
12 |
|
d868ff
|
13 |
:app:`Pyramid` uses the :term:`WebOb` package as a basis for its |
888d65
|
14 |
:term:`request` and :term:`response` object implementations. The |
d868ff
|
15 |
:term:`request` object that is passed to a :app:`Pyramid` :term:`view` is an |
e0d42d
|
16 |
instance of the :class:`pyramid.request.Request` class, which is a subclass of |
SP |
17 |
:class:`webob.Request`. The :term:`response` returned from a :app:`Pyramid` |
|
18 |
:term:`view` :term:`renderer` is an instance of the |
d868ff
|
19 |
:mod:`pyramid.response.Response` class, which is a subclass of the |
CM |
20 |
:class:`webob.Response` class. Users can also return an instance of |
|
21 |
:class:`pyramid.response.Response` directly from a view as necessary. |
888d65
|
22 |
|
e0d42d
|
23 |
WebOb is a project separate from :app:`Pyramid` with a separate set of authors |
SP |
24 |
and a fully separate `set of documentation |
|
25 |
<http://docs.webob.org/en/latest/index.html>`_. :app:`Pyramid` adds some |
e005c2
|
26 |
functionality to the standard WebOb request, which is documented in the |
MM |
27 |
:ref:`request_module` API documentation. |
888d65
|
28 |
|
d868ff
|
29 |
WebOb provides objects for HTTP requests and responses. Specifically it does |
1cb30e
|
30 |
this by wrapping the `WSGI <http://wsgi.readthedocs.org/en/latest/>`_ request |
SP |
31 |
environment and response status, header list, and app_iter (body) values. |
888d65
|
32 |
|
d868ff
|
33 |
WebOb request and response objects provide many conveniences for parsing WSGI |
CM |
34 |
requests and forming WSGI responses. WebOb is a nice way to represent "raw" |
e0d42d
|
35 |
WSGI requests and responses. However, we won't cover that use case in this |
d868ff
|
36 |
document, as users of :app:`Pyramid` don't typically need to use the |
CM |
37 |
WSGI-related features of WebOb directly. The `reference documentation |
e005c2
|
38 |
<http://docs.webob.org/en/latest/reference.html>`_ shows many examples of |
844e98
|
39 |
creating requests and using response objects in this manner, however. |
888d65
|
40 |
|
8c56ae
|
41 |
.. index:: |
CM |
42 |
single: request object |
c5f24b
|
43 |
single: request attributes |
8c56ae
|
44 |
|
888d65
|
45 |
Request |
CM |
46 |
~~~~~~~ |
|
47 |
|
|
48 |
The request object is a wrapper around the `WSGI environ dictionary |
1cb30e
|
49 |
<https://www.python.org/dev/peps/pep-0333/#environ-variables>`_. This |
e0d42d
|
50 |
dictionary contains keys for each header, keys that describe the request |
SP |
51 |
(including the path and query string), a file-like object for the request body, |
|
52 |
and a variety of custom keys. You can always access the environ with |
|
53 |
``req.environ``. |
888d65
|
54 |
|
e0d42d
|
55 |
Some of the most important and interesting attributes of a request object are |
SP |
56 |
below. |
888d65
|
57 |
|
e0d42d
|
58 |
``req.method`` |
SP |
59 |
The request method, e.g., ``GET``, ``POST`` |
888d65
|
60 |
|
e0d42d
|
61 |
``req.GET`` |
SP |
62 |
A :term:`multidict` with all the variables in the query string. |
888d65
|
63 |
|
e0d42d
|
64 |
``req.POST`` |
SP |
65 |
A :term:`multidict` with all the variables in the request body. This only |
|
66 |
has variables if the request was a ``POST`` and it is a form submission. |
888d65
|
67 |
|
e0d42d
|
68 |
``req.params`` |
SP |
69 |
A :term:`multidict` with a combination of everything in ``req.GET`` and |
|
70 |
``req.POST``. |
888d65
|
71 |
|
e0d42d
|
72 |
``req.body`` |
SP |
73 |
The contents of the body of the request. This contains the entire request |
|
74 |
body as a string. This is useful when the request is a ``POST`` that is |
|
75 |
*not* a form submission, or a request like a ``PUT``. You can also get |
|
76 |
``req.body_file`` for a file-like object. |
888d65
|
77 |
|
6a0602
|
78 |
``req.json_body`` |
CM |
79 |
The JSON-decoded contents of the body of the request. See |
|
80 |
:ref:`request_json_body`. |
|
81 |
|
e0d42d
|
82 |
``req.cookies`` |
888d65
|
83 |
A simple dictionary of all the cookies. |
CM |
84 |
|
e0d42d
|
85 |
``req.headers`` |
31309f
|
86 |
A dictionary of all the headers. This dictionary is case-insensitive. |
888d65
|
87 |
|
e0d42d
|
88 |
``req.urlvars`` and ``req.urlargs`` |
SP |
89 |
``req.urlvars`` are the keyword parameters associated with the request URL. |
|
90 |
``req.urlargs`` are the positional parameters. These are set by products |
|
91 |
like `Routes <http://routes.readthedocs.org/en/latest/>`_ and `Selector |
|
92 |
<https://github.com/lukearno/selector>`_. |
888d65
|
93 |
|
e0d42d
|
94 |
Also for standard HTTP request headers, there are usually attributes such as |
SP |
95 |
``req.accept_language``, ``req.content_length``, and ``req.user_agent``. These |
|
96 |
properties expose the *parsed* form of each header, for whatever parsing makes |
|
97 |
sense. For instance, ``req.if_modified_since`` returns a :mod:`datetime` |
|
98 |
object (or None if the header is was not provided). |
888d65
|
99 |
|
e0d42d
|
100 |
.. note:: Full API documentation for the :app:`Pyramid` request object is |
SP |
101 |
available in :ref:`request_module`. |
5c7bdc
|
102 |
|
bf76ad
|
103 |
.. index:: |
c5f24b
|
104 |
single: request attributes (special) |
590fe7
|
105 |
|
41cc8f
|
106 |
.. _special_request_attributes: |
CM |
107 |
|
fd5ae9
|
108 |
Special Attributes Added to the Request by :app:`Pyramid` |
e0d42d
|
109 |
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
590fe7
|
110 |
|
72ad33
|
111 |
In addition to the standard :term:`WebOb` attributes, :app:`Pyramid` adds |
CM |
112 |
special attributes to every request: ``context``, ``registry``, ``root``, |
|
113 |
``subpath``, ``traversed``, ``view_name``, ``virtual_root``, |
e0d42d
|
114 |
``virtual_root_path``, ``session``, ``matchdict``, and ``matched_route``. These |
SP |
115 |
attributes are documented further within the :class:`pyramid.request.Request` |
|
116 |
API documentation. |
590fe7
|
117 |
|
CM |
118 |
.. index:: |
c5f24b
|
119 |
single: request URLs |
bf76ad
|
120 |
|
888d65
|
121 |
URLs |
CM |
122 |
++++ |
|
123 |
|
e0d42d
|
124 |
In addition to these attributes, there are several ways to get the URL of the |
SP |
125 |
request and its parts. We'll show various values for an example URL |
16388c
|
126 |
``http://localhost/app/blog?id=10``, where the application is mounted at |
44f1df
|
127 |
``http://localhost/app``. |
888d65
|
128 |
|
e0d42d
|
129 |
``req.url`` |
SP |
130 |
The full request URL with query string, e.g., |
16388c
|
131 |
``http://localhost/app/blog?id=10`` |
BB |
132 |
|
e0d42d
|
133 |
``req.host`` |
SP |
134 |
The host information in the URL, e.g., ``localhost`` |
16388c
|
135 |
|
e0d42d
|
136 |
``req.host_url`` |
16388c
|
137 |
The URL with the host, e.g., ``http://localhost`` |
888d65
|
138 |
|
e0d42d
|
139 |
``req.application_url`` |
SP |
140 |
The URL of the application (just the ``SCRIPT_NAME`` portion of the path, |
|
141 |
not ``PATH_INFO``), e.g., ``http://localhost/app`` |
888d65
|
142 |
|
e0d42d
|
143 |
``req.path_url`` |
SP |
144 |
The URL of the application including the ``PATH_INFO``, e.g., |
16388c
|
145 |
``http://localhost/app/blog`` |
BB |
146 |
|
e0d42d
|
147 |
``req.path`` |
SP |
148 |
The URL including ``PATH_INFO`` without the host or scheme, e.g., |
16388c
|
149 |
``/app/blog`` |
BB |
150 |
|
e0d42d
|
151 |
``req.path_qs`` |
SP |
152 |
The URL including ``PATH_INFO`` and the query string, e.g, |
16388c
|
153 |
``/app/blog?id=10`` |
BB |
154 |
|
e0d42d
|
155 |
``req.query_string`` |
SP |
156 |
The query string in the URL, e.g., ``id=10`` |
888d65
|
157 |
|
e0d42d
|
158 |
``req.relative_url(url, to_application=False)`` |
SP |
159 |
Gives a URL relative to the current URL. If ``to_application`` is True, |
|
160 |
then resolves it relative to ``req.application_url``. |
bf76ad
|
161 |
|
CM |
162 |
.. index:: |
c5f24b
|
163 |
single: request methods |
bf76ad
|
164 |
|
888d65
|
165 |
Methods |
CM |
166 |
+++++++ |
|
167 |
|
d868ff
|
168 |
There are methods of request objects documented in |
CM |
169 |
:class:`pyramid.request.Request` but you'll find that you won't use very many |
|
170 |
of them. Here are a couple that might be useful: |
888d65
|
171 |
|
e0d42d
|
172 |
``Request.blank(base_url)`` |
SP |
173 |
Creates a new request with blank information, based at the given URL. This |
|
174 |
can be useful for subrequests and artificial requests. You can also use |
|
175 |
``req.copy()`` to copy an existing request, or for subrequests |
|
176 |
``req.copy_get()`` which copies the request but always turns it into a GET |
|
177 |
(which is safer to share for subrequests). |
888d65
|
178 |
|
e0d42d
|
179 |
``req.get_response(wsgi_application)`` |
SP |
180 |
This method calls the given WSGI application with this request, and returns |
|
181 |
a :class:`pyramid.response.Response` object. You can also use this for |
|
182 |
subrequests or testing. |
bf76ad
|
183 |
|
CM |
184 |
.. index:: |
844726
|
185 |
single: request (and text/unicode) |
CM |
186 |
single: unicode and text (and the request) |
888d65
|
187 |
|
844726
|
188 |
Text (Unicode) |
CM |
189 |
++++++++++++++ |
888d65
|
190 |
|
844726
|
191 |
Many of the properties of the request object will be text values (``unicode`` |
CM |
192 |
under Python 2 or ``str`` under Python 3) if the request encoding/charset is |
|
193 |
provided. If it is provided, the values in ``req.POST``, ``req.GET``, |
|
194 |
``req.params``, and ``req.cookies`` will contain text. The client *can* |
888d65
|
195 |
indicate the charset with something like ``Content-Type: |
844726
|
196 |
application/x-www-form-urlencoded; charset=utf8``, but browsers seldom set |
CM |
197 |
this. You can reset the charset of an existing request with ``newreq = |
|
198 |
req.decode('utf-8')``, or during instantiation with ``Request(environ, |
|
199 |
charset='utf8')``. |
888d65
|
200 |
|
2a1c3f
|
201 |
.. index:: |
CM |
202 |
single: multidict (WebOb) |
|
203 |
|
|
204 |
.. _multidict_narr: |
|
205 |
|
|
206 |
Multidict |
|
207 |
+++++++++ |
|
208 |
|
e0d42d
|
209 |
Several attributes of a WebOb request are multidict structures (such as |
2a1c3f
|
210 |
``request.GET``, ``request.POST``, and ``request.params``). A multidict is a |
e0d42d
|
211 |
dictionary where a key can have multiple values. The quintessential example is |
SP |
212 |
a query string like ``?pref=red&pref=blue``; the ``pref`` variable has two |
2a1c3f
|
213 |
values: ``red`` and ``blue``. |
CM |
214 |
|
e0d42d
|
215 |
In a multidict, when you do ``request.GET['pref']``, you'll get back only |
SP |
216 |
``"blue"`` (the last value of ``pref``). This returned result might not be |
|
217 |
expected—sometimes returning a string, and sometimes returning a list—and may |
|
218 |
be cause of frequent exceptions. If you want *all* the values back, use |
|
219 |
``request.GET.getall('pref')``. If you want to be sure there is *one and only |
|
220 |
one* value, use ``request.GET.getone('pref')``, which will raise an exception |
|
221 |
if there is zero or more than one value for ``pref``. |
2a1c3f
|
222 |
|
e0d42d
|
223 |
When you use operations like ``request.GET.items()``, you'll get back something |
SP |
224 |
like ``[('pref', 'red'), ('pref', 'blue')]``. All the key/value pairs will |
|
225 |
show up. Similarly ``request.GET.keys()`` returns ``['pref', 'pref']``. |
|
226 |
Multidict is a view on a list of tuples; all the keys are ordered, and all the |
|
227 |
values are ordered. |
2a1c3f
|
228 |
|
CM |
229 |
API documentation for a multidict exists as |
|
230 |
:class:`pyramid.interfaces.IMultiDict`. |
|
231 |
|
6ce1e0
|
232 |
.. index:: |
CM |
233 |
pair: json_body; request |
|
234 |
|
6a0602
|
235 |
.. _request_json_body: |
CM |
236 |
|
e0d42d
|
237 |
Dealing with a JSON-Encoded Request Body |
6a0602
|
238 |
++++++++++++++++++++++++++++++++++++++++ |
CM |
239 |
|
40dbf4
|
240 |
.. versionadded:: 1.1 |
6a0602
|
241 |
|
CM |
242 |
:attr:`pyramid.request.Request.json_body` is a property that returns a |
e0d42d
|
243 |
:term:`JSON`-decoded representation of the request body. If the request does |
SP |
244 |
not have a body, or the body is not a properly JSON-encoded value, an exception |
|
245 |
will be raised when this attribute is accessed. |
6a0602
|
246 |
|
e0d42d
|
247 |
This attribute is useful when you invoke a :app:`Pyramid` view callable via, |
SP |
248 |
for example, jQuery's ``$.ajax`` function, which has the potential to send a |
|
249 |
request with a JSON-encoded body. |
6a0602
|
250 |
|
CM |
251 |
Using ``request.json_body`` is equivalent to: |
|
252 |
|
|
253 |
.. code-block:: python |
|
254 |
|
|
255 |
from json import loads |
|
256 |
loads(request.body, encoding=request.charset) |
|
257 |
|
e0d42d
|
258 |
Here's how to construct an AJAX request in JavaScript using :term:`jQuery` that |
SP |
259 |
allows you to use the ``request.json_body`` attribute when the request is sent |
|
260 |
to a :app:`Pyramid` application: |
6a0602
|
261 |
|
CM |
262 |
.. code-block:: javascript |
|
263 |
|
e0d42d
|
264 |
jQuery.ajax({type:'POST', |
6a0602
|
265 |
url: 'http://localhost:6543/', // the pyramid server |
e0d42d
|
266 |
data: JSON.stringify({'a':1}), |
e33496
|
267 |
contentType: 'application/json; charset=utf-8'}); |
6a0602
|
268 |
|
CM |
269 |
When such a request reaches a view in your application, the |
|
270 |
``request.json_body`` attribute will be available in the view callable body. |
|
271 |
|
22f221
|
272 |
.. code-block:: python |
6a0602
|
273 |
|
e33496
|
274 |
@view_config(renderer='string') |
6a0602
|
275 |
def aview(request): |
edfc4f
|
276 |
print(request.json_body) |
e33496
|
277 |
return 'OK' |
6a0602
|
278 |
|
CM |
279 |
For the above view, printed to the console will be: |
|
280 |
|
|
281 |
.. code-block:: python |
|
282 |
|
|
283 |
{u'a': 1} |
|
284 |
|
e0d42d
|
285 |
For bonus points, here's a bit of client-side code that will produce a request |
SP |
286 |
that has a body suitable for reading via ``request.json_body`` using Python's |
|
287 |
``urllib2`` instead of a JavaScript AJAX request: |
0b0b20
|
288 |
|
CM |
289 |
.. code-block:: python |
|
290 |
|
|
291 |
import urllib2 |
e0d42d
|
292 |
import json |
0b0b20
|
293 |
|
CM |
294 |
json_payload = json.dumps({'a':1}) |
|
295 |
headers = {'Content-Type':'application/json; charset=utf-8'} |
|
296 |
req = urllib2.Request('http://localhost:6543/', json_payload, headers) |
|
297 |
resp = urllib2.urlopen(req) |
|
298 |
|
2660f5
|
299 |
If you are doing Cross-origin resource sharing (CORS), then the standard |
CM |
300 |
requires the browser to do a pre-flight HTTP OPTIONS request. The easiest way |
e0d42d
|
301 |
to handle this is to add an extra ``view_config`` for the same route, with |
SP |
302 |
``request_method`` set to ``OPTIONS``, and set the desired response header |
|
303 |
before returning. You can find examples of response headers `Access control |
|
304 |
CORS, Preflighted requests |
|
305 |
<https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Preflighted_requests>`_. |
271191
|
306 |
|
b37b97
|
307 |
.. index:: |
CM |
308 |
single: cleaning up after request |
|
309 |
|
|
310 |
.. _cleaning_up_after_a_request: |
|
311 |
|
e0d42d
|
312 |
Cleaning up after a Request |
b37b97
|
313 |
+++++++++++++++++++++++++++ |
CM |
314 |
|
e0d42d
|
315 |
Sometimes it's required to perform some cleanup at the end of a request when a |
SP |
316 |
database connection is involved. |
b37b97
|
317 |
|
CM |
318 |
For example, let's say you have a ``mypackage`` :app:`Pyramid` application |
|
319 |
package that uses SQLAlchemy, and you'd like the current SQLAlchemy database |
|
320 |
session to be removed after each request. Put the following in the |
|
321 |
``mypackage.__init__`` module: |
|
322 |
|
|
323 |
.. code-block:: python |
|
324 |
:linenos: |
|
325 |
|
|
326 |
from mypackage.models import DBSession |
|
327 |
|
|
328 |
from pyramid.events import subscriber |
|
329 |
from pyramid.events import NewRequest |
|
330 |
|
|
331 |
def cleanup_callback(request): |
|
332 |
DBSession.remove() |
|
333 |
|
|
334 |
@subscriber(NewRequest) |
|
335 |
def add_cleanup_callback(event): |
|
336 |
event.request.add_finished_callback(cleanup_callback) |
|
337 |
|
|
338 |
Registering the ``cleanup_callback`` finished callback at the start of a |
|
339 |
request (by causing the ``add_cleanup_callback`` to receive a |
|
340 |
:class:`pyramid.events.NewRequest` event at the start of each request) will |
e0d42d
|
341 |
cause the DBSession to be removed whenever request processing has ended. Note |
SP |
342 |
that in the example above, for the :class:`pyramid.events.subscriber` decorator |
|
343 |
to work, the :meth:`pyramid.config.Configurator.scan` method must be called |
|
344 |
against your ``mypackage`` package during application initialization. |
b37b97
|
345 |
|
e0d42d
|
346 |
.. note:: |
SP |
347 |
This is only an example. In particular, it is not necessary to cause |
af098b
|
348 |
``DBSession.remove`` to be called in an application generated from a |
SP |
349 |
:app:`Pyramid` cookiecutter, because these all use the ``pyramid_tm`` package. |
e0d42d
|
350 |
The cleanup done by ``DBSession.remove`` is unnecessary when ``pyramid_tm`` |
SP |
351 |
:term:`middleware` is configured into the application. |
b37b97
|
352 |
|
844e98
|
353 |
More Details |
CM |
354 |
++++++++++++ |
|
355 |
|
e0d42d
|
356 |
More detail about the request object API is available as follows. |
844e98
|
357 |
|
e0d42d
|
358 |
- :class:`pyramid.request.Request` API documentation |
844e98
|
359 |
|
e0d42d
|
360 |
- `WebOb documentation <http://docs.webob.org/en/latest/index.html>`_. All |
SP |
361 |
methods and attributes of a ``webob.Request`` documented within the WebOb |
|
362 |
documentation will work with request objects created by :app:`Pyramid`. |
8c56ae
|
363 |
|
94b889
|
364 |
.. index:: |
CM |
365 |
single: response object |
|
366 |
|
888d65
|
367 |
Response |
CM |
368 |
~~~~~~~~ |
|
369 |
|
fd5ae9
|
370 |
The :app:`Pyramid` response object can be imported as |
d868ff
|
371 |
:class:`pyramid.response.Response`. This class is a subclass of the |
CM |
372 |
``webob.Response`` class. The subclass does not add or change any |
e0d42d
|
373 |
functionality, so the WebOb Response documentation will be completely relevant |
SP |
374 |
for this class as well. |
94b889
|
375 |
|
CM |
376 |
A response object has three fundamental parts: |
888d65
|
377 |
|
e0d42d
|
378 |
``response.status`` |
SP |
379 |
The response code plus reason message, like ``200 OK``. To set the code |
|
380 |
without a message, use ``status_int``, i.e., ``response.status_int = 200``. |
888d65
|
381 |
|
e0d42d
|
382 |
``response.headerlist`` |
SP |
383 |
A list of all the headers, like ``[('Content-Type', 'text/html')]``. |
|
384 |
There's a case-insensitive :term:`multidict` in ``response.headers`` that |
|
385 |
also allows you to access these same headers. |
888d65
|
386 |
|
e0d42d
|
387 |
``response.app_iter`` |
SP |
388 |
An iterable (such as a list or generator) that will produce the content of |
|
389 |
the response. This is also accessible as ``response.body`` (a string), |
|
390 |
``response.text`` (a unicode object, informed by ``response.charset``), and |
|
391 |
``response.body_file`` (a file-like object; writing to it appends to |
|
392 |
``app_iter``). |
888d65
|
393 |
|
d868ff
|
394 |
Everything else in the object typically derives from this underlying state. |
CM |
395 |
Here are some highlights: |
888d65
|
396 |
|
94b889
|
397 |
``response.content_type`` |
888d65
|
398 |
The content type *not* including the ``charset`` parameter. |
e0d42d
|
399 |
|
94b889
|
400 |
Typical use: ``response.content_type = 'text/html'``. |
888d65
|
401 |
|
ac16ec
|
402 |
Default value: ``response.content_type = 'text/html'``. |
W |
403 |
|
e0d42d
|
404 |
``response.charset`` |
SP |
405 |
The ``charset`` parameter of the content-type, it also informs encoding in |
|
406 |
``response.text``. ``response.content_type_params`` is a dictionary of all |
|
407 |
the parameters. |
888d65
|
408 |
|
80acf2
|
409 |
``response.set_cookie(name, value, max_age=None, path='/', ...)`` |
e0d42d
|
410 |
Set a cookie. The keyword arguments control the various cookie parameters. |
SP |
411 |
The ``max_age`` argument is the length for the cookie to live in seconds |
|
412 |
(you may also use a timedelta object). The ``Expires`` key will also be |
|
413 |
set based on the value of ``max_age``. |
888d65
|
414 |
|
80acf2
|
415 |
``response.delete_cookie(name, path='/', domain=None)`` |
e0d42d
|
416 |
Delete a cookie from the client. This sets ``max_age`` to 0 and the cookie |
SP |
417 |
value to ``''``. |
888d65
|
418 |
|
e0d42d
|
419 |
``response.cache_expires(seconds=0)`` |
SP |
420 |
This makes the response cacheable for the given number of seconds, or if |
|
421 |
``seconds`` is ``0`` then the response is uncacheable (this also sets the |
|
422 |
``Expires`` header). |
888d65
|
423 |
|
e0d42d
|
424 |
``response(environ, start_response)`` |
SP |
425 |
The response object is a WSGI application. As an application, it acts |
|
426 |
according to how you create it. It *can* do conditional responses if you |
|
427 |
pass ``conditional_response=True`` when instantiating (or set that |
|
428 |
attribute later). It can also do HEAD and Range requests. |
888d65
|
429 |
|
8c56ae
|
430 |
.. index:: |
c5f24b
|
431 |
single: response headers |
8c56ae
|
432 |
|
888d65
|
433 |
Headers |
CM |
434 |
+++++++ |
|
435 |
|
e0d42d
|
436 |
Like the request, most HTTP response headers are available as properties. These |
SP |
437 |
are parsed, so you can do things like ``response.last_modified = |
|
438 |
os.path.getmtime(filename)``. |
888d65
|
439 |
|
e0d42d
|
440 |
The details are available in the :mod:`webob.response` API documentation. |
888d65
|
441 |
|
bf76ad
|
442 |
.. index:: |
c5f24b
|
443 |
single: response (creating) |
bf76ad
|
444 |
|
888d65
|
445 |
Instantiating the Response |
CM |
446 |
++++++++++++++++++++++++++ |
|
447 |
|
e0d42d
|
448 |
Of course most of the time you just want to *make* a response. Generally any |
SP |
449 |
attribute of the response can be passed in as a keyword argument to the class, |
|
450 |
e.g.: |
888d65
|
451 |
|
CM |
452 |
.. code-block:: python |
16cd50
|
453 |
:linenos: |
888d65
|
454 |
|
94b889
|
455 |
from pyramid.response import Response |
888d65
|
456 |
response = Response(body='hello world!', content_type='text/plain') |
CM |
457 |
|
ac16ec
|
458 |
The status defaults to ``'200 OK'``. |
W |
459 |
|
e0d42d
|
460 |
The value of ``content_type`` defaults to |
SP |
461 |
``webob.response.Response.default_content_type``, which is ``text/html``. You |
|
462 |
can subclass :class:`pyramid.response.Response` and set |
ac16ec
|
463 |
``default_content_type`` to override this behavior. |
888d65
|
464 |
|
8c56ae
|
465 |
.. index:: |
6ce1e0
|
466 |
single: exception responses |
8c56ae
|
467 |
|
94b889
|
468 |
Exception Responses |
CM |
469 |
+++++++++++++++++++ |
888d65
|
470 |
|
2e6905
|
471 |
To facilitate error responses like ``404 Not Found``, the module |
e0d42d
|
472 |
:mod:`pyramid.httpexceptions` contains classes for each kind of error response. |
SP |
473 |
These include boring but appropriate error bodies. The exceptions exposed by |
|
474 |
this module, when used under :app:`Pyramid`, should be imported from the |
|
475 |
:mod:`pyramid.httpexceptions` module. This import location contains subclasses |
|
476 |
and replacements that mirror those in the ``webob.exc`` module. |
888d65
|
477 |
|
e0d42d
|
478 |
Each class is named ``pyramid.httpexceptions.HTTP*``, where ``*`` is the reason |
SP |
479 |
for the error. For instance, :class:`pyramid.httpexceptions.HTTPNotFound` |
|
480 |
subclasses :class:`pyramid.response.Response`, so you can manipulate the |
|
481 |
instances in the same way. A typical example is: |
888d65
|
482 |
|
CM |
483 |
.. code-block:: python |
16cd50
|
484 |
:linenos: |
888d65
|
485 |
|
99edc5
|
486 |
from pyramid.httpexceptions import HTTPNotFound |
CM |
487 |
from pyramid.httpexceptions import HTTPMovedPermanently |
888d65
|
488 |
|
CM |
489 |
response = HTTPNotFound('There is no such resource') |
|
490 |
# or: |
|
491 |
response = HTTPMovedPermanently(location=new_url) |
|
492 |
|
844e98
|
493 |
More Details |
CM |
494 |
++++++++++++ |
|
495 |
|
94b889
|
496 |
More details about the response object API are available in the |
e0d42d
|
497 |
:mod:`pyramid.response` documentation. More details about exception responses |
SP |
498 |
are in the :mod:`pyramid.httpexceptions` API documentation. The `WebOb |
|
499 |
documentation <http://docs.webob.org/en/latest/index.html>`_ is also useful. |