1 ============================

     2 Request and response objects

     3 ============================

     4 

     5 Quick overview

     6 ==============

     7 

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

     9 

    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.

    14 

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

    16 objects.

    17 

    18 HttpRequest objects

    19 ===================

    20 

    21 Attributes

    22 ----------

    23 

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

    25 

    26 ``path``

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

    28     the domain.

    29 

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

    31 

    32 ``method``

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

    34     guaranteed to be uppercase. Example::

    35 

    36         if request.method == 'GET':

    37             do_something()

    38         elif request.method == 'POST':

    39             do_something_else()

    40 

    41 ``GET``

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

    43     ``QueryDict`` documentation below.

    44 

    45 ``POST``

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

    47     ``QueryDict`` documentation below.

    48 

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

    53     "POST"`` (see above).

    54 

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

    56 

    57 ``REQUEST``

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

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

    60 

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

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

    63     ``"34"``.

    64 

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

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

    67 

    68 ``COOKIES``

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

    70     strings.

    71 

    72 ``FILES``

    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

    76     keys:

    77 

    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.

    81 

    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.

    86 

    87 ``META``

    88     A standard Python dictionary containing all available HTTP headers.

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

    90     examples:

    91 

    92         * ``CONTENT_LENGTH``

    93         * ``CONTENT_TYPE``

    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.

   104 

   105 ``user``

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

   110 

   111         if request.user.is_authenticated():

   112             # Do something for logged-in users.

   113         else:

   114             # Do something for anonymous users.

   115 

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

   117     ``AuthenticationMiddleware`` activated. For more, see

   118     `Authentication in Web requests`_.

   119 

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

   121 

   122 ``session``

   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.

   126 

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

   128 

   129 ``raw_post_data``

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

   131     ``POST`` instead.

   132 

   133 Methods

   134 -------

   135 

   136 ``__getitem__(key)``

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

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

   139 

   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.

   143 

   144 ``has_key()``

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

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

   147 

   148 ``get_full_path()``

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

   150 

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

   152 

   153 ``is_secure()``

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

   155    HTTPS.

   156 

   157 QueryDict objects

   158 -----------------

   159 

   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.

   165 

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

   168 directly.

   169 

   170 ``QueryDict`` implements the all standard dictionary methods, because it's a

   171 subclass of dictionary. Exceptions are outlined here:

   172 

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

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

   175 

   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()``).

   180 

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

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

   183 

   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.

   186 

   187     * ``has_key(key)``

   188 

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

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

   191 

   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.

   195       For example::

   196 

   197           >>> q = QueryDict('a=1')

   198           >>> q = q.copy() # to make it mutable

   199           >>> q.update({'a': '2'})

   200           >>> q.getlist('a')

   201           ['1', '2']

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

   203           ['2']

   204 

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

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

   207       example::

   208 

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

   210            >>> q.items()

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

   212 

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

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

   215       example::

   216 

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

   218            >>> q.values()

   219            ['3']

   220 

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

   222 

   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.

   226 

   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.

   230 

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

   232       ``__setitem__()``).

   233 

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

   235       associated with key.

   236 

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

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

   239 

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

   241       for each member of the dictionary. For example::

   242 

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

   244            >>> q.lists()

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

   246 

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

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

   249 

   250 Examples

   251 --------

   252 

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

   254 

   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>

   261     </select>

   262     <input type="submit" />

   263     </form>

   264 

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

   268 

   269     >>> request.GET

   270     {}

   271     >>> request.POST

   272     {'your_name': ['John Smith'], 'bands': ['beatles', 'zombies']}

   273     >>> request.POST['your_name']

   274     'John Smith'

   275     >>> request.POST['bands']

   276     'zombies'

   277     >>> request.POST.getlist('bands')

   278     ['beatles', 'zombies']

   279     >>> request.POST.get('your_name', 'Adrian')

   280     'John Smith'

   281     >>> request.POST.get('nonexistent_field', 'Nowhere Man')

   282     'Nowhere Man'

   283 

   284 Implementation notes

   285 --------------------

   286 

   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.

   291 

   292 HttpResponse objects

   293 ====================

   294 

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

   298 

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

   300 

   301 Usage

   302 -----

   303 

   304 Passing strings

   305 ~~~~~~~~~~~~~~~

   306 

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

   308 ``HttpResponse`` constructor::

   309 

   310     >>> response = HttpResponse("Here's the text of the Web page.")

   311     >>> response = HttpResponse("Text only, please.", mimetype="text/plain")

   312 

   313 But if you want to add content incrementally, you can use ``response`` as a

   314 file-like object::

   315 

   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>")

   319 

   320 You can add and delete headers using dictionary syntax::

   321 

   322     >>> response = HttpResponse()

   323     >>> response['X-DJANGO'] = "It's the best."

   324     >>> del response['X-PHP']

   325     >>> response['X-DJANGO']

   326     "It's the best."

   327 

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

   329 

   330 Passing iterators

   331 ~~~~~~~~~~~~~~~~~

   332 

   333 Finally, you can pass ``HttpResponse`` an iterator rather than passing it

   334 hard-coded strings. If you use this technique, follow these guidelines:

   335 

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

   340 

   341 Methods

   342 -------

   343 

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

   347 

   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.

   351 

   352 ``__setitem__(header, value)``

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

   354     ``value`` should be strings.

   355 

   356 ``__delitem__(header)``

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

   358     doesn't exist. Case-sensitive.

   359 

   360 ``__getitem__(header)``

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

   362 

   363 ``has_header(header)``

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

   365     header with the given name.

   366 

   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.

   370 

   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.

   380 

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

   382 

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

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

   385     exist.

   386 

   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.

   389 

   390 ``content``

   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()``.

   394 

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

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

   397 

   398 HttpResponse subclasses

   399 -----------------------

   400 

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

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

   403 ``django.http``.

   404 

   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.

   410 

   411 ``HttpResponsePermanentRedirect``

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

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

   414 

   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.

   418 

   419 ``HttpResponseNotFound``

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

   421 

   422 ``HttpResponseForbidden``

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

   424 

   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']``).

   428 

   429 ``HttpResponseGone``

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

   431 

   432 ``HttpResponseServerError``

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

   434 

   435 Returning errors

   436 ================

   437 

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

   443 

   444     def my_view(request):

   445         # ...

   446         if foo:

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

   448         else:

   449             return HttpResponse('<h1>Page was found</h1>')

   450 

   451 Because 404 errors are by far the most common HTTP error, there's an easier way

   452 to handle those errors.

   453 

   454 The Http404 exception

   455 ---------------------

   456 

   457 When you return an error such as ``HttpResponseNotFound``, you're responsible

   458 for defining the HTML of the resulting error page::

   459 

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

   461 

   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.

   466 

   467 Example usage::

   468 

   469     from django.http import Http404

   470 

   471     def detail(request, poll_id):

   472         try:

   473             p = Poll.objects.get(pk=poll_id)

   474         except Poll.DoesNotExist:

   475             raise Http404

   476         return render_to_response('polls/detail.html', {'poll': p})

   477 

   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.

   481 

   482 Customing error views

   483 ---------------------

   484 

   485 The 404 (page not found) view

   486 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   487 

   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

   491 ``404.html``.

   492 

   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.

   495 

   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

   498 URLconf, like so::

   499 

   500     handler404 = 'mysite.views.my_custom_404_view'

   501 

   502 Behind the scenes, Django determines the 404 view by looking for ``handler404``.

   503 By default, URLconfs contain the following line::

   504 

   505     from django.conf.urls.defaults import *

   506 

   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.

   510 

   511 Three things to note about 404 views:

   512 

   513     * The 404 view is also called if Django doesn't find a match after checking

   514       every regular expression in the URLconf.

   515 

   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.

   520 

   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.

   523 

   524 The 500 (server error) view

   525 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

   526 

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

   531 

   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.

   534 

   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

   537 URLconf, like so::

   538 

   539     handler500 = 'mysite.views.my_custom_error_view'

   540 

   541 Behind the scenes, Django determines the error view by looking for ``handler500``.

   542 By default, URLconfs contain the following line::

   543 

   544     from django.conf.urls.defaults import *

   545 

   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.