--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/thirdparty/google_appengine/lib/django/docs/request_response.txt Tue Aug 26 21:49:54 2008 +0000
@@ -0,0 +1,548 @@
+============================
+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
+template ``500.html``.
+
+This means you need to define a ``500.html`` template in your root template
+directory. This template will be used for all server errors.
+
+This ``server_error`` view should suffice for 99% of Web applications, but if
+you want to override the view, you can specify ``handler500`` in your
+URLconf, like so::
+
+ handler500 = 'mysite.views.my_custom_error_view'
+
+Behind the scenes, Django determines the error view by looking for ``handler500``.
+By default, URLconfs contain the following line::
+
+ from django.conf.urls.defaults import *
+
+That takes care of setting ``handler500`` in the current module. As you can see
+in ``django/conf/urls/defaults.py``, ``handler500`` is set to
+``'django.views.defaults.server_error'`` by default.