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.

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.

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.

Usage

>>> response = HttpResponse("Here's the text of the Web page.")
>>> response = HttpResponse("Text only, please.", mimetype="text/plain")

>>> response = HttpResponse()
>>> response.write("<p>Here's the text of the Web page.</p>")
>>> response.write("<p>Here's another paragraph.</p>")

>>> response = HttpResponse()
>>> response['X-DJANGO'] = "It's the best."
>>> del response['X-PHP']
>>> response['X-DJANGO']
"It's the best."

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

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.

delete_cookie(key)

Deletes the cookie with the given key. Fails silently if the key doesn’t exist.

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.