1 ============================
2 Request and response objects
3 ============================
8 Django uses request and response objects to pass state through the system.
10 When a page is requested, Django creates an ``HttpRequest`` object that
11 contains metadata about the request. Then Django loads the appropriate view,
12 passing the ``HttpRequest`` as the first argument to the view function. Each
13 view is responsible for returning an ``HttpResponse`` object.
15 This document explains the APIs for ``HttpRequest`` and ``HttpResponse``
24 All attributes except ``session`` should be considered read-only.
27 A string representing the full path to the requested page, not including
30 Example: ``"/music/bands/the_beatles/"``
33 A string representing the HTTP method used in the request. This is
34 guaranteed to be uppercase. Example::
36 if request.method == 'GET':
38 elif request.method == 'POST':
42 A dictionary-like object containing all given HTTP GET parameters. See the
43 ``QueryDict`` documentation below.
46 A dictionary-like object containing all given HTTP POST parameters. See the
47 ``QueryDict`` documentation below.
49 It's possible that a request can come in via POST with an empty ``POST``
50 dictionary -- if, say, a form is requested via the POST HTTP method but
51 does not include form data. Therefore, you shouldn't use ``if request.POST``
52 to check for use of the POST method; instead, use ``if request.method ==
55 Note: ``POST`` does *not* include file-upload information. See ``FILES``.
58 For convenience, a dictionary-like object that searches ``POST`` first,
59 then ``GET``. Inspired by PHP's ``$_REQUEST``.
61 For example, if ``GET = {"name": "john"}`` and ``POST = {"age": '34'}``,
62 ``REQUEST["name"]`` would be ``"john"``, and ``REQUEST["age"]`` would be
65 It's strongly suggested that you use ``GET`` and ``POST`` instead of
66 ``REQUEST``, because the former are more explicit.
69 A standard Python dictionary containing all cookies. Keys and values are
73 A dictionary-like object containing all uploaded files. Each key in
74 ``FILES`` is the ``name`` from the ``<input type="file" name="" />``. Each
75 value in ``FILES`` is a standard Python dictionary with the following three
78 * ``filename`` -- The name of the uploaded file, as a Python string.
79 * ``content-type`` -- The content type of the uploaded file.
80 * ``content`` -- The raw content of the uploaded file.
82 Note that ``FILES`` will only contain data if the request method was POST
83 and the ``<form>`` that posted to the request had
84 ``enctype="multipart/form-data"``. Otherwise, ``FILES`` will be a blank
85 dictionary-like object.
88 A standard Python dictionary containing all available HTTP headers.
89 Available headers depend on the client and server, but here are some
94 * ``HTTP_ACCEPT_ENCODING``
95 * ``HTTP_ACCEPT_LANGUAGE``
96 * ``HTTP_REFERER`` -- The referring page, if any.
97 * ``HTTP_USER_AGENT`` -- The client's user-agent string.
98 * ``QUERY_STRING`` -- The query string, as a single (unparsed) string.
99 * ``REMOTE_ADDR`` -- The IP address of the client.
100 * ``REMOTE_HOST`` -- The hostname of the client.
101 * ``REQUEST_METHOD`` -- A string such as ``"GET"`` or ``"POST"``.
102 * ``SERVER_NAME`` -- The hostname of the server.
103 * ``SERVER_PORT`` -- The port of the server.
106 A ``django.contrib.auth.models.User`` object representing the currently
107 logged-in user. If the user isn't currently logged in, ``user`` will be set
108 to an instance of ``django.contrib.auth.models.AnonymousUser``. You
109 can tell them apart with ``is_authenticated()``, like so::
111 if request.user.is_authenticated():
112 # Do something for logged-in users.
114 # Do something for anonymous users.
116 ``user`` is only available if your Django installation has the
117 ``AuthenticationMiddleware`` activated. For more, see
118 `Authentication in Web requests`_.
120 .. _Authentication in Web requests: ../authentication/#authentication-in-web-requests
123 A readable-and-writable, dictionary-like object that represents the current
124 session. This is only available if your Django installation has session
125 support activated. See the `session documentation`_ for full details.
127 .. _`session documentation`: ../sessions/
130 The raw HTTP POST data. This is only useful for advanced processing. Use
137 Returns the GET/POST value for the given key, checking POST first, then
138 GET. Raises ``KeyError`` if the key doesn't exist.
140 This lets you use dictionary-accessing syntax on an ``HttpRequest``
141 instance. Example: ``request["foo"]`` would return ``True`` if either
142 ``request.POST`` or ``request.GET`` had a ``"foo"`` key.
145 Returns ``True`` or ``False``, designating whether ``request.GET`` or
146 ``request.POST`` has the given key.
149 Returns the ``path``, plus an appended query string, if applicable.
151 Example: ``"/music/bands/the_beatles/?print=true"``
154 Returns ``True`` if the request is secure; that is, if it was made with
160 In an ``HttpRequest`` object, the ``GET`` and ``POST`` attributes are instances
161 of ``django.http.QueryDict``. ``QueryDict`` is a dictionary-like
162 class customized to deal with multiple values for the same key. This is
163 necessary because some HTML form elements, notably
164 ``<select multiple="multiple">``, pass multiple values for the same key.
166 ``QueryDict`` instances are immutable, unless you create a ``copy()`` of them.
167 That means you can't change attributes of ``request.POST`` and ``request.GET``
170 ``QueryDict`` implements the all standard dictionary methods, because it's a
171 subclass of dictionary. Exceptions are outlined here:
173 * ``__getitem__(key)`` -- Returns the value for the given key. If the key
174 has more than one value, ``__getitem__()`` returns the last value.
176 * ``__setitem__(key, value)`` -- Sets the given key to ``[value]``
177 (a Python list whose single element is ``value``). Note that this, as
178 other dictionary functions that have side effects, can only be called on
179 a mutable ``QueryDict`` (one that was created via ``copy()``).
181 * ``__contains__(key)`` -- Returns ``True`` if the given key is set. This
182 lets you do, e.g., ``if "foo" in request.GET``.
184 * ``get(key, default)`` -- Uses the same logic as ``__getitem__()`` above,
185 with a hook for returning a default value if the key doesn't exist.
189 * ``setdefault(key, default)`` -- Just like the standard dictionary
190 ``setdefault()`` method, except it uses ``__setitem__`` internally.
192 * ``update(other_dict)`` -- Takes either a ``QueryDict`` or standard
193 dictionary. Just like the standard dictionary ``update()`` method, except
194 it *appends* to the current dictionary items rather than replacing them.
197 >>> q = QueryDict('a=1')
198 >>> q = q.copy() # to make it mutable
199 >>> q.update({'a': '2'})
202 >>> q['a'] # returns the last
205 * ``items()`` -- Just like the standard dictionary ``items()`` method,
206 except this uses the same last-value logic as ``__getitem()__``. For
209 >>> q = QueryDict('a=1&a=2&a=3')
213 * ``values()`` -- Just like the standard dictionary ``values()`` method,
214 except this uses the same last-value logic as ``__getitem()__``. For
217 >>> q = QueryDict('a=1&a=2&a=3')
221 In addition, ``QueryDict`` has the following methods:
223 * ``copy()`` -- Returns a copy of the object, using ``copy.deepcopy()``
224 from the Python standard library. The copy will be mutable -- that is,
225 you can change its values.
227 * ``getlist(key)`` -- Returns the data with the requested key, as a Python
228 list. Returns an empty list if the key doesn't exist. It's guaranteed to
229 return a list of some sort.
231 * ``setlist(key, list_)`` -- Sets the given key to ``list_`` (unlike
234 * ``appendlist(key, item)`` -- Appends an item to the internal list
237 * ``setlistdefault(key, default_list)`` -- Just like ``setdefault``, except
238 it takes a list of values instead of a single value.
240 * ``lists()`` -- Like ``items()``, except it includes all values, as a list,
241 for each member of the dictionary. For example::
243 >>> q = QueryDict('a=1&a=2&a=3')
245 [('a', ['1', '2', '3'])]
247 * ``urlencode()`` -- Returns a string of the data in query-string format.
248 Example: ``"a=2&b=3&b=5"``.
253 Here's an example HTML form and how Django would treat the input::
255 <form action="/foo/bar/" method="post">
256 <input type="text" name="your_name" />
257 <select multiple="multiple" name="bands">
258 <option value="beatles">The Beatles</option>
259 <option value="who">The Who</option>
260 <option value="zombies">The Zombies</option>
262 <input type="submit" />
265 If the user enters ``"John Smith"`` in the ``your_name`` field and selects both
266 "The Beatles" and "The Zombies" in the multiple select box, here's what
267 Django's request object would have::
272 {'your_name': ['John Smith'], 'bands': ['beatles', 'zombies']}
273 >>> request.POST['your_name']
275 >>> request.POST['bands']
277 >>> request.POST.getlist('bands')
278 ['beatles', 'zombies']
279 >>> request.POST.get('your_name', 'Adrian')
281 >>> request.POST.get('nonexistent_field', 'Nowhere Man')
287 The ``GET``, ``POST``, ``COOKIES``, ``FILES``, ``META``, ``REQUEST``,
288 ``raw_post_data`` and ``user`` attributes are all lazily loaded. That means
289 Django doesn't spend resources calculating the values of those attributes until
290 your code requests them.
295 In contrast to ``HttpRequest`` objects, which are created automatically by
296 Django, ``HttpResponse`` objects are your responsibility. Each view you write
297 is responsible for instantiating, populating and returning an ``HttpResponse``.
299 The ``HttpResponse`` class lives at ``django.http.HttpResponse``.
307 Typical usage is to pass the contents of the page, as a string, to the
308 ``HttpResponse`` constructor::
310 >>> response = HttpResponse("Here's the text of the Web page.")
311 >>> response = HttpResponse("Text only, please.", mimetype="text/plain")
313 But if you want to add content incrementally, you can use ``response`` as a
316 >>> response = HttpResponse()
317 >>> response.write("<p>Here's the text of the Web page.</p>")
318 >>> response.write("<p>Here's another paragraph.</p>")
320 You can add and delete headers using dictionary syntax::
322 >>> response = HttpResponse()
323 >>> response['X-DJANGO'] = "It's the best."
324 >>> del response['X-PHP']
325 >>> response['X-DJANGO']
328 Note that ``del`` doesn't raise ``KeyError`` if the header doesn't exist.
333 Finally, you can pass ``HttpResponse`` an iterator rather than passing it
334 hard-coded strings. If you use this technique, follow these guidelines:
336 * The iterator should return strings.
337 * If an ``HttpResponse`` has been initialized with an iterator as its
338 content, you can't use the ``HttpResponse`` instance as a file-like
339 object. Doing so will raise ``Exception``.
344 ``__init__(content='', mimetype=DEFAULT_CONTENT_TYPE)``
345 Instantiates an ``HttpResponse`` object with the given page content (a
346 string) and MIME type. The ``DEFAULT_CONTENT_TYPE`` is ``'text/html'``.
348 ``content`` can be an iterator or a string. If it's an iterator, it should
349 return strings, and those strings will be joined together to form the
350 content of the response.
352 ``__setitem__(header, value)``
353 Sets the given header name to the given value. Both ``header`` and
354 ``value`` should be strings.
356 ``__delitem__(header)``
357 Deletes the header with the given name. Fails silently if the header
358 doesn't exist. Case-sensitive.
360 ``__getitem__(header)``
361 Returns the value for the given header name. Case-sensitive.
363 ``has_header(header)``
364 Returns ``True`` or ``False`` based on a case-insensitive check for a
365 header with the given name.
367 ``set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=None)``
368 Sets a cookie. The parameters are the same as in the `cookie Morsel`_
369 object in the Python standard library.
371 * ``max_age`` should be a number of seconds, or ``None`` (default) if
372 the cookie should last only as long as the client's browser session.
373 * ``expires`` should be a string in the format
374 ``"Wdy, DD-Mon-YY HH:MM:SS GMT"``.
375 * Use ``domain`` if you want to set a cross-domain cookie. For example,
376 ``domain=".lawrence.com"`` will set a cookie that is readable by
377 the domains www.lawrence.com, blogs.lawrence.com and
378 calendars.lawrence.com. Otherwise, a cookie will only be readable by
379 the domain that set it.
381 .. _`cookie Morsel`: http://www.python.org/doc/current/lib/morsel-objects.html
383 ``delete_cookie(key, path='/', domain=None)``
384 Deletes the cookie with the given key. Fails silently if the key doesn't
387 Due to the way cookies work, ``path`` and ``domain`` should be the same
388 values you used in ``set_cookie()`` -- otherwise the cookie may not be deleted.
391 Returns the content as a Python string, encoding it from a Unicode object
392 if necessary. Note this is a property, not a method, so use ``r.content``
393 instead of ``r.content()``.
395 ``write(content)``, ``flush()`` and ``tell()``
396 These methods make an ``HttpResponse`` instance a file-like object.
398 HttpResponse subclasses
399 -----------------------
401 Django includes a number of ``HttpResponse`` subclasses that handle different
402 types of HTTP responses. Like ``HttpResponse``, these subclasses live in
405 ``HttpResponseRedirect``
406 The constructor takes a single argument -- the path to redirect to. This
407 can be a fully qualified URL (e.g. ``'http://www.yahoo.com/search/'``) or an
408 absolute URL with no domain (e.g. ``'/search/'``). Note that this returns
409 an HTTP status code 302.
411 ``HttpResponsePermanentRedirect``
412 Like ``HttpResponseRedirect``, but it returns a permanent redirect (HTTP
413 status code 301) instead of a "found" redirect (status code 302).
415 ``HttpResponseNotModified``
416 The constructor doesn't take any arguments. Use this to designate that a
417 page hasn't been modified since the user's last request.
419 ``HttpResponseNotFound``
420 Acts just like ``HttpResponse`` but uses a 404 status code.
422 ``HttpResponseForbidden``
423 Acts just like ``HttpResponse`` but uses a 403 status code.
425 ``HttpResponseNotAllowed``
426 Like ``HttpResponse``, but uses a 405 status code. Takes a single,
427 required argument: a list of permitted methods (e.g. ``['GET', 'POST']``).
430 Acts just like ``HttpResponse`` but uses a 410 status code.
432 ``HttpResponseServerError``
433 Acts just like ``HttpResponse`` but uses a 500 status code.
438 Returning HTTP error codes in Django is easy. We've already mentioned the
439 ``HttpResponseNotFound``, ``HttpResponseForbidden``,
440 ``HttpResponseServerError``, etc., subclasses; just return an instance of one
441 of those subclasses instead of a normal ``HttpResponse`` in order to signify
442 an error. For example::
444 def my_view(request):
447 return HttpResponseNotFound('<h1>Page not found</h1>')
449 return HttpResponse('<h1>Page was found</h1>')
451 Because 404 errors are by far the most common HTTP error, there's an easier way
452 to handle those errors.
454 The Http404 exception
455 ---------------------
457 When you return an error such as ``HttpResponseNotFound``, you're responsible
458 for defining the HTML of the resulting error page::
460 return HttpResponseNotFound('<h1>Page not found</h1>')
462 For convenience, and because it's a good idea to have a consistent 404 error page
463 across your site, Django provides an ``Http404`` exception. If you raise
464 ``Http404`` at any point in a view function, Django will catch it and return the
465 standard error page for your application, along with an HTTP error code 404.
469 from django.http import Http404
471 def detail(request, poll_id):
473 p = Poll.objects.get(pk=poll_id)
474 except Poll.DoesNotExist:
476 return render_to_response('polls/detail.html', {'poll': p})
478 In order to use the ``Http404`` exception to its fullest, you should create a
479 template that is displayed when a 404 error is raised. This template should be
480 called ``404.html`` and located in the top level of your template tree.
482 Customing error views
483 ---------------------
485 The 404 (page not found) view
486 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
488 When you raise an ``Http404`` exception, Django loads a special view devoted
489 to handling 404 errors. By default, it's the view
490 ``django.views.defaults.page_not_found``, which loads and renders the template
493 This means you need to define a ``404.html`` template in your root template
494 directory. This template will be used for all 404 errors.
496 This ``page_not_found`` view should suffice for 99% of Web applications, but if
497 you want to override the 404 view, you can specify ``handler404`` in your
500 handler404 = 'mysite.views.my_custom_404_view'
502 Behind the scenes, Django determines the 404 view by looking for ``handler404``.
503 By default, URLconfs contain the following line::
505 from django.conf.urls.defaults import *
507 That takes care of setting ``handler404`` in the current module. As you can see
508 in ``django/conf/urls/defaults.py``, ``handler404`` is set to
509 ``'django.views.defaults.page_not_found'`` by default.
511 Three things to note about 404 views:
513 * The 404 view is also called if Django doesn't find a match after checking
514 every regular expression in the URLconf.
516 * If you don't define your own 404 view -- and simply use the default,
517 which is recommended -- you still have one obligation: To create a
518 ``404.html`` template in the root of your template directory. The default
519 404 view will use that template for all 404 errors.
521 * If ``DEBUG`` is set to ``True`` (in your settings module) then your 404
522 view will never be used, and the traceback will be displayed instead.
524 The 500 (server error) view
525 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
527 Similarly, Django executes special-case behavior in the case of runtime errors
528 in view code. If a view results in an exception, Django will, by default, call
529 the view ``django.views.defaults.server_error``, which loads and renders the
530 template ``500.html``.
532 This means you need to define a ``500.html`` template in your root template
533 directory. This template will be used for all server errors.
535 This ``server_error`` view should suffice for 99% of Web applications, but if
536 you want to override the view, you can specify ``handler500`` in your
539 handler500 = 'mysite.views.my_custom_error_view'
541 Behind the scenes, Django determines the error view by looking for ``handler500``.
542 By default, URLconfs contain the following line::
544 from django.conf.urls.defaults import *
546 That takes care of setting ``handler500`` in the current module. As you can see
547 in ``django/conf/urls/defaults.py``, ``handler500`` is set to
548 ``'django.views.defaults.server_error'`` by default.