============================

Request and response objects

============================

Quick overview

==============

Django uses request and response objects to pass state through the system.

When a page is requested, Django creates an ``HttpRequest`` object that

contains metadata about the request. Then Django loads the appropriate view,

passing the ``HttpRequest`` as the first argument to the view function. Each

view is responsible for returning an ``HttpResponse`` object.

This document explains the APIs for ``HttpRequest`` and ``HttpResponse``

objects.

HttpRequest objects

===================

Attributes

----------

All attributes except ``session`` should be considered read-only.

``path``

    A string representing the full path to the requested page, not including

    the domain.

    Example: ``"/music/bands/the_beatles/"``

``method``

    A string representing the HTTP method used in the request. This is

    guaranteed to be uppercase. Example::

        if request.method == 'GET':

            do_something()

        elif request.method == 'POST':

            do_something_else()

``GET``

    A dictionary-like object containing all given HTTP GET parameters. See the

    ``QueryDict`` documentation below.

``POST``

    A dictionary-like object containing all given HTTP POST parameters. See the

    ``QueryDict`` documentation below.

    It's possible that a request can come in via POST with an empty ``POST``

    dictionary -- if, say, a form is requested via the POST HTTP method but

    does not include form data. Therefore, you shouldn't use ``if request.POST``

    to check for use of the POST method; instead, use ``if request.method ==

    "POST"`` (see above).

    Note: ``POST`` does *not* include file-upload information. See ``FILES``.

``REQUEST``

    For convenience, a dictionary-like object that searches ``POST`` first,

    then ``GET``. Inspired by PHP's ``$_REQUEST``.

    For example, if ``GET = {"name": "john"}`` and ``POST = {"age": '34'}``,

    ``REQUEST["name"]`` would be ``"john"``, and ``REQUEST["age"]`` would be

    ``"34"``.

    It's strongly suggested that you use ``GET`` and ``POST`` instead of

    ``REQUEST``, because the former are more explicit.

``COOKIES``

    A standard Python dictionary containing all cookies. Keys and values are

    strings.

``FILES``

    A dictionary-like object containing all uploaded files. Each key in

    ``FILES`` is the ``name`` from the ``<input type="file" name="" />``. Each

    value in ``FILES`` is a standard Python dictionary with the following three

    keys:

        * ``filename`` -- The name of the uploaded file, as a Python string.

        * ``content-type`` -- The content type of the uploaded file.

        * ``content`` -- The raw content of the uploaded file.

    Note that ``FILES`` will only contain data if the request method was POST

    and the ``<form>`` that posted to the request had

    ``enctype="multipart/form-data"``. Otherwise, ``FILES`` will be a blank

    dictionary-like object.

``META``

    A standard Python dictionary containing all available HTTP headers.

    Available headers depend on the client and server, but here are some

    examples:

        * ``CONTENT_LENGTH``

        * ``CONTENT_TYPE``

        * ``HTTP_ACCEPT_ENCODING``

        * ``HTTP_ACCEPT_LANGUAGE``

        * ``HTTP_REFERER`` -- The referring page, if any.

        * ``HTTP_USER_AGENT`` -- The client's user-agent string.

        * ``QUERY_STRING`` -- The query string, as a single (unparsed) string.

        * ``REMOTE_ADDR`` -- The IP address of the client.

        * ``REMOTE_HOST`` -- The hostname of the client.

        * ``REQUEST_METHOD`` -- A string such as ``"GET"`` or ``"POST"``.

        * ``SERVER_NAME`` -- The hostname of the server.

        * ``SERVER_PORT`` -- The port of the server.

``user``

    A ``django.contrib.auth.models.User`` object representing the currently

    logged-in user. If the user isn't currently logged in, ``user`` will be set

    to an instance of ``django.contrib.auth.models.AnonymousUser``. You

    can tell them apart with ``is_authenticated()``, like so::

        if request.user.is_authenticated():

            # Do something for logged-in users.

        else:

            # Do something for anonymous users.

    ``user`` is only available if your Django installation has the

    ``AuthenticationMiddleware`` activated. For more, see

    `Authentication in Web requests`_.

    .. _Authentication in Web requests: ../authentication/#authentication-in-web-requests

``session``

    A readable-and-writable, dictionary-like object that represents the current

    session. This is only available if your Django installation has session

    support activated. See the `session documentation`_ for full details.

    .. _`session documentation`: ../sessions/

``raw_post_data``

    The raw HTTP POST data. This is only useful for advanced processing. Use

    ``POST`` instead.

Methods

-------

``__getitem__(key)``

   Returns the GET/POST value for the given key, checking POST first, then

   GET. Raises ``KeyError`` if the key doesn't exist.

   This lets you use dictionary-accessing syntax on an ``HttpRequest``

   instance. Example: ``request["foo"]`` would return ``True`` if either

   ``request.POST`` or ``request.GET`` had a ``"foo"`` key.

``has_key()``

   Returns ``True`` or ``False``, designating whether ``request.GET`` or

   ``request.POST`` has the given key.

``get_full_path()``

   Returns the ``path``, plus an appended query string, if applicable.

   Example: ``"/music/bands/the_beatles/?print=true"``

``is_secure()``

   Returns ``True`` if the request is secure; that is, if it was made with

   HTTPS.

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 here:

    * ``__getitem__(key)`` -- Returns the value for the given key. If the key

      has more than one value, ``__getitem__()`` returns the last value.

    * ``__setitem__(key, value)`` -- Sets the given key to ``[value]``

      (a Python list whose single element is ``value``). Note that this, as

      other dictionary functions that have side effects, can only be called on

      a mutable ``QueryDict`` (one that was created via ``copy()``).

    * ``__contains__(key)`` -- Returns ``True`` if the given key is set. This

      lets you do, e.g., ``if "foo" in request.GET``.

    * ``get(key, default)`` -- Uses the same logic as ``__getitem__()`` above,

      with a hook for returning a default value if the key doesn't exist.

    * ``has_key(key)``

    * ``setdefault(key, default)`` -- Just like the standard dictionary

      ``setdefault()`` method, except it uses ``__setitem__`` internally.

    * ``update(other_dict)`` -- Takes either a ``QueryDict`` or standard

      dictionary. Just like the standard dictionary ``update()`` method, except

      it *appends* to the current dictionary items rather than replacing them.

      For example::

          >>> 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']

    * ``items()`` -- Just like the standard dictionary ``items()`` method,

      except this uses the same last-value logic as ``__getitem()__``. For

      example::

           >>> q = QueryDict('a=1&a=2&a=3')

           >>> q.items()

           [('a', '3')]

    * ``values()`` -- Just like the standard dictionary ``values()`` method,

      except this uses the same last-value logic as ``__getitem()__``. For

      example::

           >>> q = QueryDict('a=1&a=2&a=3')

           >>> q.values()

           ['3']

In addition, ``QueryDict`` has the following methods:

    * ``copy()`` -- Returns a copy of the object, using ``copy.deepcopy()``

      from the Python standard library. The copy will be mutable -- that is,

      you can change its values.

    * ``getlist(key)`` -- Returns the data with the requested key, as a Python

      list. Returns an empty list if the key doesn't exist. It's guaranteed to

      return a list of some sort.

    * ``setlist(key, list_)`` -- Sets the given key to ``list_`` (unlike

      ``__setitem__()``).

    * ``appendlist(key, item)`` -- Appends an item to the internal list

      associated with key.

    * ``setlistdefault(key, default_list)`` -- Just like ``setdefault``, except

      it takes a list of values instead of a single value.

    * ``lists()`` -- Like ``items()``, except it includes all values, as a list,

      for each member of the dictionary. For example::

           >>> q = QueryDict('a=1&a=2&a=3')

           >>> q.lists()

           [('a', ['1', '2', '3'])]

    * ``urlencode()`` -- Returns a string of the data in query-string format.

      Example: ``"a=2&b=3&b=5"``.

Examples

--------

Here's an example HTML form and how Django would treat the input::

    <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'

Implementation notes

--------------------

The ``GET``, ``POST``, ``COOKIES``, ``FILES``, ``META``, ``REQUEST``,

``raw_post_data`` and ``user`` attributes are all lazily loaded. That means

Django doesn't spend resources calculating the values of those attributes until

your code requests them.

HttpResponse objects

====================

In contrast to ``HttpRequest`` objects, which are created automatically by

Django, ``HttpResponse`` objects are your responsibility. Each view you write

is responsible for instantiating, populating and returning an ``HttpResponse``.

The ``HttpResponse`` class lives at ``django.http.HttpResponse``.

Usage

-----

Passing strings

~~~~~~~~~~~~~~~

Typical usage is 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

file-like 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 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."

Note that ``del`` doesn't raise ``KeyError`` if the header doesn't exist.

Passing iterators

~~~~~~~~~~~~~~~~~

Finally, 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 file-like

      object. Doing so will raise ``Exception``.

Methods

-------

``__init__(content='', mimetype=DEFAULT_CONTENT_TYPE)``

    Instantiates an ``HttpResponse`` object with the given page content (a

    string) and MIME type. The ``DEFAULT_CONTENT_TYPE`` is ``'text/html'``.

    ``content`` can be an iterator or a string. If it's an iterator, it should

    return strings, and those strings will be joined together to form the

    content of the response.

``__setitem__(header, value)``

    Sets the given header name to the given value. Both ``header`` and

    ``value`` should be strings.

``__delitem__(header)``

    Deletes the header with the given name. Fails silently if the header

    doesn't exist. Case-sensitive.

``__getitem__(header)``

    Returns the value for the given header name. Case-sensitive.

``has_header(header)``

    Returns ``True`` or ``False`` based on a case-insensitive check for a

    header with the given name.

``set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=None)``

    Sets a cookie. The parameters are the same as in the `cookie Morsel`_

    object in the Python standard library.

        * ``max_age`` should be a number of seconds, or ``None`` (default) if

          the cookie should last only as long as the client's browser session.

        * ``expires`` should be a string in the format

          ``"Wdy, DD-Mon-YY HH:MM:SS GMT"``.

        * Use ``domain`` if you want to set a cross-domain cookie. For example,

          ``domain=".lawrence.com"`` will set a cookie that is readable by

          the domains www.lawrence.com, blogs.lawrence.com and

          calendars.lawrence.com. Otherwise, a cookie will only be readable by

          the domain that set it.

    .. _`cookie Morsel`: http://www.python.org/doc/current/lib/morsel-objects.html

``delete_cookie(key, path='/', domain=None)``

    Deletes the cookie with the given key. Fails silently if the key doesn't

    exist.

    Due to the way cookies work, ``path`` and ``domain`` should be the same

    values you used in ``set_cookie()`` -- otherwise the cookie may not be deleted.

``content``

    Returns the content as a Python string, encoding it from a Unicode object

    if necessary. Note this is a property, not a method, so use ``r.content``

    instead of ``r.content()``.

``write(content)``, ``flush()`` and ``tell()``

    These methods make an ``HttpResponse`` instance a file-like object.

HttpResponse subclasses

-----------------------

Django includes a number of ``HttpResponse`` subclasses that handle different

types of HTTP responses. Like ``HttpResponse``, these subclasses live in

``django.http``.

``HttpResponseRedirect``

    The constructor takes a single argument -- the path to redirect to. This

    can be a fully qualified URL (e.g. ``'http://www.yahoo.com/search/'``) or an

    absolute URL with no domain (e.g. ``'/search/'``). Note that this returns

    an HTTP status code 302.

``HttpResponsePermanentRedirect``

    Like ``HttpResponseRedirect``, but it returns a permanent redirect (HTTP

    status code 301) instead of a "found" redirect (status code 302).

``HttpResponseNotModified``

    The constructor doesn't take any arguments. Use this to designate that a

    page hasn't been modified since the user's last request.

``HttpResponseNotFound``

    Acts just like ``HttpResponse`` but uses a 404 status code.

``HttpResponseForbidden``

    Acts just like ``HttpResponse`` but uses a 403 status code.

``HttpResponseNotAllowed``

    Like ``HttpResponse``, but uses a 405 status code. Takes a single,

    required argument: a list of permitted methods (e.g. ``['GET', 'POST']``).

``HttpResponseGone``

    Acts just like ``HttpResponse`` but uses a 410 status code.

``HttpResponseServerError``

    Acts just like ``HttpResponse`` but uses a 500 status code.

Returning errors

================

Returning HTTP error codes in Django is easy. We've already mentioned the

``HttpResponseNotFound``, ``HttpResponseForbidden``,

``HttpResponseServerError``, etc., 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 404 errors are by far the most common HTTP error, there's an easier way

to handle those errors.

The Http404 exception

---------------------

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.

Example usage::

    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_to_response('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 located in the top level of your template tree.

Customing error views

---------------------

The 404 (page 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::

    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.

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.

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