QueryDict Objects ¶

In an HttpRequest object, the GET and POST attributes are instances of django.http.QueryDict . QueryDict is a dictionary-like class customized to deal with multiple values for the same key. This is necessary because some HTML form elements, notably <select multiple="multiple"> , pass multiple values for the same key.

QueryDict instances are immutable, unless you create a copy() of them. That means you can’t change attributes of request.POST and request.GET directly.

QueryDict implements the all standard dictionary methods, because it’s a subclass of dictionary. Exceptions are outlined in Table G-3.

>>> q = QueryDict('a=1')
>>> q = q.copy() # to make it mutable
>>> q.update({'a': '2'})
>>> q.getlist('a')
['1', '2']
>>> q['a'] # returns the last
['2']

>>> q = QueryDict('a=1&a=2&a=3')
>>> q.items()
[('a', '3')]

In addition, QueryDict has the methods shown in Table G-4.

>>> q = QueryDict('a=1&a=2&a=3')
>>> q.lists()
[('a', ['1', '2', '3'])]

A Complete Example ¶

For example, given this HTML form:

<form action="/foo/bar/" method="post">
<input type="text" name="your_name" />
<select multiple="multiple" name="bands">
    <option value="beatles">The Beatles</option>
    <option value="who">The Who</option>
    <option value="zombies">The Zombies</option>
</select>
<input type="submit" />
</form>

if the user enters "John Smith" in the your_name field and selects both “The Beatles” and “The Zombies” in the multiple select box, here’s what Django’s request object would have:

>>> request.GET
{}
>>> request.POST
{'your_name': ['John Smith'], 'bands': ['beatles', 'zombies']}
>>> request.POST['your_name']
'John Smith'
>>> request.POST['bands']
'zombies'
>>> request.POST.getlist('bands')
['beatles', 'zombies']
>>> request.POST.get('your_name', 'Adrian')
'John Smith'
>>> request.POST.get('nonexistent_field', 'Nowhere Man')
'Nowhere Man'

Construction HttpResponses ¶

Typically, you’ll construct an HttpResponse to pass the contents of the page, as a string, to the HttpResponse constructor:

>>> response = HttpResponse("Here's the text of the Web page.")
>>> response = HttpResponse("Text only, please.", mimetype="text/plain")

But if you want to add content incrementally, you can use response as a filelike object:

>>> response = HttpResponse()
>>> response.write("<p>Here's the text of the Web page.</p>")
>>> response.write("<p>Here's another paragraph.</p>")

You can pass HttpResponse an iterator rather than passing it hard-coded strings. If you use this technique, follow these guidelines:

• The iterator should return strings.

• If an HttpResponse has been initialized with an iterator as its content, you can’t use the HttpResponse instance as a filelike object. Doing so will raise Exception .

Finally, note that HttpResponse implements a write() method, which makes is suitable for use anywhere that Python expects a filelike object. See Chapter 8 for some examples of using this technique.

Setting Headers ¶

You can add and delete headers using dictionary syntax:

>>> response = HttpResponse()
>>> response['X-DJANGO'] = "It's the best."
>>> del response['X-PHP']
>>> response['X-DJANGO']
"It's the best."

You can also use has_header(header) to check for the existence of a header.

Avoid setting Cookie headers by hand; instead, see Chapter 14 for instructions on how cookies work in Django.

HttpResponse Subclasses ¶

Django includes a number of HttpResponse subclasses that handle different types of HTTP responses (see Table G-5). Like HttpResponse , these subclasses live in django.http .

You can, of course, define your own HttpResponse subclass to support different types of responses not supported out of the box.

Returning Errors ¶

Returning HTTP error codes in Django is easy. We’ve already mentioned the HttpResponseNotFound , HttpResponseForbidden , HttpResponseServerError , and other subclasses. Just return an instance of one of those subclasses instead of a normal HttpResponse in order to signify an error, for example:

def my_view(request):
    # ...
    if foo:
        return HttpResponseNotFound('<h1>Page not found</h1>')
    else:
        return HttpResponse('<h1>Page was found</h1>')

Because a 404 error is by far the most common HTTP error, there’s an easier way to handle it.

When you return an error such as HttpResponseNotFound , you’re responsible for defining the HTML of the resulting error page:

return HttpResponseNotFound('<h1>Page not found</h1>')

For convenience, and because it’s a good idea to have a consistent 404 error page across your site, Django provides an Http404 exception. If you raise Http404 at any point in a view function, Django will catch it and return the standard error page for your application, along with an HTTP error code 404.

Here’s an example:

from django.http import Http404

def detail(request, poll_id):
    try:
        p = Poll.objects.get(pk=poll_id)
    except Poll.DoesNotExist:
        raise Http404
    return render(request, 'polls/detail.html', {'poll': p})

In order to use the Http404 exception to its fullest, you should create a template that is displayed when a 404 error is raised. This template should be called 404.html , and it should be located in the top level of your template tree.

Customizing the 404 (Not Found) View ¶

When you raise an Http404 exception, Django loads a special view devoted to handling 404 errors. By default, it’s the view django.views.defaults.page_not_found , which loads and renders the template 404.html .

This means you need to define a 404.html template in your root template directory. This template will be used for all 404 errors.

This page_not_found view should suffice for 99% of Web applications, but if you want to override the 404 view, you can specify handler404 in your URLconf, like so:

from django.conf.urls.defaults import *

urlpatterns = patterns('',
    ...
)

handler404 = 'mysite.views.my_custom_404_view'

Behind the scenes, Django determines the 404 view by looking for handler404 . By default, URLconfs contain the following line:

from django.conf.urls.defaults import *

That takes care of setting handler404 in the current module. As you can see in django/conf/urls/defaults.py , handler404 is set to 'django.views.defaults.page_not_found' by default.

There are three things to note about 404 views:

• The 404 view is also called if Django doesn’t find a match after checking every regular expression in the URLconf.

• If you don’t define your own 404 view – and simply use the default, which is recommended – you still have one obligation: to create a 404.html template in the root of your template directory. The default 404 view will use that template for all 404 errors.

• If DEBUG is set to True (in your settings module), then your 404 view will never be used, and the traceback will be displayed instead.

Customizing the 500 (Server Error) View ¶

Similarly, Django executes special-case behavior in the case of runtime errors in view code. If a view results in an exception, Django will, by default, call the view django.views.defaults.server_error , which loads and renders the template 500.html .

This means you need to define a 500.html template in your root template directory. This template will be used for all server errors.

This server_error view should suffice for 99% of Web applications, but if you want to override the view, you can specify handler500 in your URLconf, like so:

from django.conf.urls.defaults import *

urlpatterns = patterns('',
    ...
)

handler500 = 'mysite.views.my_custom_error_view'