============================ 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/"`` ``GET`` A dictionary-like object containing all given HTTP GET parameters. See the ``MultiValueDict`` documentation below. ``POST`` A dictionary-like object containing all given HTTP POST parameters. See the ``MultiValueDict`` documentation below. ``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 ````. 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 ``
`` 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.models.auth.users.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.parts.auth.anonymoususers.AnonymousUser``. You can tell them apart with ``is_anonymous()``, like so:: if request.user.is_anonymous(): # Do something for anonymous users. else: # Do something for logged-in users. ``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`: http://www.djangoproject.com/documentation/sessions/ ``raw_post_data`` The raw HTTP POST data. This is only useful for advanced processing. Use ``POST`` instead. Methods ------- ``get_full_path()`` Returns the ``path``, plus an appended query string, if applicable. Example: ``"/music/bands/the_beatles/?print=true"`` MultiValueDict objects ---------------------- In an ``HttpRequest`` object, the ``GET`` and ``POST`` attributes are instances of ``django.utils.datastructures.MultiValueDict``. ``MultiValueDict`` is a dictionary-like class customized to deal with multiple values for the same key. This is necessary because some HTML form elements, notably ``
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.utils.httpwrappers.HttpResponse``. Usage ----- 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("

Here's the text of the Web page.

") >>> response.write("

Here's another paragraph.

") 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. Methods ------- ``__init__(content='', mimetype=DEFAULT_MIME_TYPE)`` Instantiates an ``HttpResponse`` object with the given page content (a string) and MIME type. The ``DEFAULT_MIME_TYPE`` is ``"text/html"``. ``__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, 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. * 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 object`: http://www.python.org/doc/current/lib/morsel-objects.html ``get_content_as_string(encoding)`` Returns the content as a Python string, encoding it from a Unicode object if necessary. ``write(content)`` ``flush()`` ``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.utils.httpwrappers``. ``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/"``). ``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. ``HttpResponseGone`` Acts just like ``HttpResponse`` but uses a 410 status code. ``HttpResponseServerError`` Acts just like ``HttpResponse`` but uses a 500 status code.