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

Request and response objects

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

.. module:: django.http

   :synopsis: Classes dealing with HTTP requests and responses.

Quick overview

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

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

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

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

passing the :class:`HttpRequest` as the first argument to the view function.

Each view is responsible for returning an :class:`HttpResponse` object.

This document explains the APIs for :class:`HttpRequest` and

:class:`HttpResponse` objects.

HttpRequest objects

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

.. class:: HttpRequest

Attributes

----------

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

.. attribute:: HttpRequest.path

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

    the domain.

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

.. attribute:: HttpRequest.path_info

    Under some web server configurations, the portion of the URL after the host

    name is split up into a script prefix portion and a path info portion

    (this happens, for example, when using the ``django.root`` option

    with the :ref:`modpython handler from Apache <howto-deployment-modpython>`).

    The ``path_info`` attribute always contains the path info portion of the

    path, no matter what web server is being used. Using this instead of

    attr:`~HttpRequest.path` can make your code much easier to move between test

    and deployment servers.

    For example, if the ``django.root`` for your application is set to 

    ``"/minfo"``, then ``path`` might be ``"/minfo/music/bands/the_beatles/"``

    and ``path_info`` would be ``"/music/bands/the_beatles/"``.

.. attribute:: HttpRequest.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()

.. attribute:: HttpRequest.encoding

    A string representing the current encoding used to decode form submission

    data (or ``None``, which means the :setting:`DEFAULT_CHARSET` setting is

    used). You can write to this attribute to change the encoding used when

    accessing the form data. Any subsequent attribute accesses (such as reading

    from ``GET`` or ``POST``) will use the new ``encoding`` value.  Useful if

    you know the form data is not in the :setting:`DEFAULT_CHARSET` encoding.

.. attribute:: HttpRequest.GET

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

    :class:`QueryDict` documentation below.

.. attribute:: HttpRequest.POST

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

    :class:`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``.

.. attribute:: HttpRequest.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.

.. attribute:: HttpRequest.COOKIES

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

    strings.

.. attribute:: HttpRequest.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 an :class:`UploadedFile` as described below.

    See :doc:`/topics/files` for more information.

    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.

    .. versionchanged:: 1.0

    In previous versions of Django, ``request.FILES`` contained simple ``dict``

    objects representing uploaded files. This is no longer true -- files are

    represented by :class:`UploadedFile` objects.

    These :class:`UploadedFile` objects will emulate the old-style ``dict``

    interface, but this is deprecated and will be removed in the next release

    of Django.

.. attribute:: HttpRequest.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_HOST`` -- The HTTP Host header sent by the client.

        * ``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.

        * ``REMOTE_USER`` -- The user authenticated by the Web server, if any.

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

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

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

    With the exception of ``CONTENT_LENGTH`` and ``CONTENT_TYPE``, as given

    above, any HTTP headers in the request are converted to ``META`` keys by

    converting all characters to uppercase, replacing any hyphens with

    underscores and adding an ``HTTP_`` prefix to the name. So, for example, a

    header called ``X-Bender`` would be mapped to the ``META`` key

    ``HTTP_X_BENDER``.

.. attribute:: HttpRequest.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

    :doc:`/topics/auth`.

.. attribute:: HttpRequest.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 :doc:`session documentation

    </topics/http/sessions>` for full details.

.. attribute:: HttpRequest.raw_post_data

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

    ``POST`` instead.

.. attribute:: HttpRequest.urlconf

    Not defined by Django itself, but will be read if other code (e.g., a custom

    middleware class) sets it. When present, this will be used as the root

    URLconf for the current request, overriding the :setting:`ROOT_URLCONF`

    setting. See :ref:`how-django-processes-a-request` for details.

Methods

-------

.. method:: HttpRequest.get_host()

    Returns the originating host of the request using information from the

    ``HTTP_X_FORWARDED_HOST`` and ``HTTP_HOST`` headers (in that order). If

    they don't provide a value, the method uses a combination of

    ``SERVER_NAME`` and ``SERVER_PORT`` as detailed in `PEP 333`_.

    .. _PEP 333: http://www.python.org/dev/peps/pep-0333/

    Example: ``"127.0.0.1:8000"``

    .. note:: The :meth:`~HttpRequest.get_host()` method fails when the host is

        behind multiple proxies. One solution is to use middleware to rewrite

        the proxy headers, as in the following example::

            class MultipleProxyMiddleware(object):

                FORWARDED_FOR_FIELDS = [

                    'HTTP_X_FORWARDED_FOR',

                    'HTTP_X_FORWARDED_HOST',

                    'HTTP_X_FORWARDED_SERVER',

                ]

                def process_request(self, request):

                    """

                    Rewrites the proxy headers so that only the most

                    recent proxy is used.

                    """

                    for field in self.FORWARDED_FOR_FIELDS:

                        if field in request.META:

                            if ',' in request.META[field]:

                                parts = request.META[field].split(',')

                                request.META[field] = parts[-1].strip()

.. method:: HttpRequest.get_full_path()

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

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

.. method:: HttpRequest.build_absolute_uri(location)

   Returns the absolute URI form of ``location``. If no location is provided,

   the location will be set to ``request.get_full_path()``.

   If the location is already an absolute URI, it will not be altered.

   Otherwise the absolute URI is built using the server variables available in

   this request.

   Example: ``"http://example.com/music/bands/the_beatles/?print=true"``

.. method:: HttpRequest.is_secure()

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

   HTTPS.

.. method:: HttpRequest.is_ajax()

   Returns ``True`` if the request was made via an ``XMLHttpRequest``, by

   checking the ``HTTP_X_REQUESTED_WITH`` header for the string

   ``'XMLHttpRequest'``. Most modern JavaScript libraries send this header.

   If you write your own XMLHttpRequest call (on the browser side), you'll

   have to set this header manually if you want ``is_ajax()`` to work.

UploadedFile objects

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

.. class:: UploadedFile

Attributes

----------

.. attribute::  UploadedFile.name

    The name of the uploaded file.

.. attribute:: UploadedFile.size

    The size, in bytes, of the uploaded file.

Methods

----------

.. method:: UploadedFile.chunks(chunk_size=None)

    Returns a generator that yields sequential chunks of data.

.. method:: UploadedFile.read(num_bytes=None)

    Read a number of bytes from the file.

QueryDict objects

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

.. class:: QueryDict

In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are instances

of ``django.http.QueryDict``. :class:`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.

Methods

-------

:class:`QueryDict` implements all the standard dictionary methods, because it's

a subclass of dictionary. Exceptions are outlined here:

.. method:: QueryDict.__getitem__(key)

    Returns the value for the given key. If the key has more than one value,

    ``__getitem__()`` returns the last value. Raises

    ``django.utils.datastructures.MultiValueDictKeyError`` if the key does not

    exist. (This is a subclass of Python's standard ``KeyError``, so you can

    stick to catching ``KeyError``.)

.. method:: QueryDict.__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()``).

.. method:: QueryDict.__contains__(key)

    Returns ``True`` if the given key is set. This lets you do, e.g., ``if "foo"

    in request.GET``.

.. method:: QueryDict.get(key, default)

    Uses the same logic as ``__getitem__()`` above, with a hook for returning a

    default value if the key doesn't exist.

.. method:: QueryDict.setdefault(key, default)

    Just like the standard dictionary ``setdefault()`` method, except it uses

    ``__setitem__()`` internally.

.. method:: QueryDict.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')

          [u'1', u'2']

          >>> q['a'] # returns the last

          [u'2']

.. method:: QueryDict.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()

           [(u'a', u'3')]

.. method:: QueryDict.iteritems()

    Just like the standard dictionary ``iteritems()`` method. Like

    :meth:`QueryDict.items()` this uses the same last-value logic as

    :meth:`QueryDict.__getitem__()`.

.. method:: QueryDict.iterlists()

    Like :meth:`QueryDict.iteritems()` except it includes all values, as a list,

    for each member of the dictionary.

.. method:: QueryDict.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()

           [u'3']

.. method:: QueryDict.itervalues()

    Just like :meth:`QueryDict.values()`, except an iterator.

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

.. method:: QueryDict.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.

.. method:: QueryDict.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.

.. method:: QueryDict.setlist(key, list_)

    Sets the given key to ``list_`` (unlike ``__setitem__()``).

.. method:: QueryDict.appendlist(key, item)

    Appends an item to the internal list associated with key.

.. method:: QueryDict.setlistdefault(key, default_list)

    Just like ``setdefault``, except it takes a list of values instead of a

    single value.

.. method:: QueryDict.lists()

    Like :meth:`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()

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

.. method:: QueryDict.urlencode()

    Returns a string of the data in query-string format.

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

HttpResponse objects

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

.. class:: HttpResponse

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

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

write is responsible for instantiating, populating and returning an

:class:`HttpResponse`.

The :class:`HttpResponse` class lives in the :mod:`django.http` module.

Usage

-----

Passing strings

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

Typical usage is to pass the contents of the page, as a string, to the

:class:`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>")

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 :class:`HttpResponse` has been initialized with an iterator as its

      content, you can't use the class:`HttpResponse` instance as a file-like

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

Setting headers

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

To set or remove a header in your response, treat it like a dictionary::

    >>> response = HttpResponse()

    >>> response['Cache-Control'] = 'no-cache'

    >>> del response['Cache-Control']

Note that unlike a dictionary, ``del`` doesn't raise ``KeyError`` if the header

doesn't exist.

.. versionadded:: 1.1

HTTP headers cannot contain newlines. An attempt to set a header containing a

newline character (CR or LF) will raise ``BadHeaderError``

Telling the browser to treat the response as a file attachment

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

To tell the browser to treat the response as a file attachment, use the

``mimetype`` argument and set the ``Content-Disposition`` header. For example,

this is how you might return a Microsoft Excel spreadsheet::

    >>> response = HttpResponse(my_data, mimetype='application/vnd.ms-excel')

    >>> response['Content-Disposition'] = 'attachment; filename=foo.xls'

There's nothing Django-specific about the ``Content-Disposition`` header, but

it's easy to forget the syntax, so we've included it here.

Attributes

----------

.. attribute:: HttpResponse.content

    A normal Python string representing the content, encoded from a Unicode

    object if necessary.

.. attribute:: HttpResponse.status_code

    The `HTTP Status code`_ for the response.

Methods

-------

.. method:: HttpResponse.__init__(content='', mimetype=None, status=200, content_type=DEFAULT_CONTENT_TYPE)

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

    string) and MIME type. The :setting:`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.

    ``status`` is the `HTTP Status code`_ for the response.

    ``content_type`` is an alias for ``mimetype``. Historically, this parameter