From b483f66efefca1029d6ac8b9836f9db844ced05f Mon Sep 17 00:00:00 2001 From: Adrian Holovaty Date: Thu, 1 Sep 2005 05:10:30 +0000 Subject: [PATCH] Added docs/request_response.txt git-svn-id: http://code.djangoproject.com/svn/django/trunk@592 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/request_response.txt | 312 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 312 insertions(+) create mode 100644 docs/request_response.txt diff --git a/docs/request_response.txt b/docs/request_response.txt new file mode 100644 index 0000000000..72119459be --- /dev/null +++ b/docs/request_response.txt @@ -0,0 +1,312 @@ +============================ +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.