Request and response objectsLink to this heading
Quick overviewLink to this heading
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, which are defined in the django.http
module.
HttpRequest objectsLink to this heading
- class HttpRequestLink to this definition
AttributesLink to this heading
All attributes should be considered read-only, unless stated otherwise.
- HttpRequest.schemeLink to this definition
A string representing the scheme of the request (
httporhttpsusually).
- HttpRequest.bodyLink to this definition
The raw HTTP request body as a byte string. This is useful for processing data in different ways than conventional HTML forms: binary images, XML payload etc. For processing conventional form data, use
HttpRequest.POST.You can also read from an HttpRequest using a file-like interface. See
HttpRequest.read().
- HttpRequest.pathLink to this definition
A string representing the full path to the requested page, not including the scheme or domain.
Example:
"/music/bands/the_beatles/"
- HttpRequest.path_infoLink to this definition
Under some Web server configurations, the portion of the URL after the host name is split up into a script prefix portion and a path info portion. The
path_infoattribute always contains the path info portion of the path, no matter what Web server is being used. Using this instead ofpathcan make your code easier to move between test and deployment servers.For example, if the
WSGIScriptAliasfor your application is set to"/minfo", thenpathmight be"/minfo/music/bands/the_beatles/"andpath_infowould be"/music/bands/the_beatles/".
- HttpRequest.methodLink to this definition
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()
- HttpRequest.encodingLink to this definition
A string representing the current encoding used to decode form submission data (or
None, which means theDEFAULT_CHARSETsetting is used). You can write to this attribute to change the encoding used when accessing the form data. Any subsequent attribute accesses (such as reading fromGETorPOST) will use the newencodingvalue. Useful if you know the form data is not in theDEFAULT_CHARSETencoding.
- HttpRequest.GETLink to this definition
A dictionary-like object containing all given HTTP GET parameters. See the
QueryDictdocumentation below.
- HttpRequest.POSTLink to this definition
A dictionary-like object containing all given HTTP POST parameters, providing that the request contains form data. See the
QueryDictdocumentation below. If you need to access raw or non-form data posted in the request, access this through theHttpRequest.bodyattribute instead.It’s possible that a request can come in via POST with an empty
POSTdictionary – if, say, a form is requested via the POST HTTP method but does not include form data. Therefore, you shouldn’t useif request.POSTto check for use of the POST method; instead, useif request.method == "POST"(see above).Note:
POSTdoes not include file-upload information. SeeFILES.
- HttpRequest.COOKIESLink to this definition
A standard Python dictionary containing all cookies. Keys and values are strings.
- HttpRequest.FILESLink to this definition
A dictionary-like object containing all uploaded files. Each key in
FILESis thenamefrom the<input type="file" name="" />. Each value inFILESis anUploadedFile.See Managing files for more information.
Note that
FILESwill only contain data if the request method was POST and the<form>that posted to the request hadenctype="multipart/form-data". Otherwise,FILESwill be a blank dictionary-like object.
- HttpRequest.METALink to this definition
A standard Python dictionary containing all available HTTP headers. Available headers depend on the client and server, but here are some examples:
CONTENT_LENGTH– The length of the request body (as a string).CONTENT_TYPE– The MIME type of the request body.HTTP_ACCEPT– Acceptable content types for the response.HTTP_ACCEPT_ENCODING– Acceptable encodings for the response.HTTP_ACCEPT_LANGUAGE– Acceptable languages for the response.HTTP_HOST– The HTTP Host header sent by the client.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.REMOTE_USER– The user authenticated by the Web server, if any.REQUEST_METHOD– A string such as"GET"or"POST".SERVER_NAME– The hostname of the server.SERVER_PORT– The port of the server (as a string).
With the exception of
CONTENT_LENGTHandCONTENT_TYPE, as given above, any HTTP headers in the request are converted toMETAkeys by converting all characters to uppercase, replacing any hyphens with underscores and adding anHTTP_prefix to the name. So, for example, a header calledX-Benderwould be mapped to theMETAkeyHTTP_X_BENDER.Note that
runserverstrips all headers with underscores in the name, so you won’t see them inMETA. This prevents header-spoofing based on ambiguity between underscores and dashes both being normalizing to underscores in WSGI environment variables. It matches the behavior of Web servers like Nginx and Apache 2.4+.
- HttpRequest.resolver_matchLink to this definition
An instance of
ResolverMatchrepresenting the resolved url. This attribute is only set after url resolving took place, which means it’s available in all views but not in middleware methods which are executed before url resolving takes place (likeprocess_request, you can useprocess_viewinstead).
Attributes set by application codeLink to this heading
Django doesn’t set these attributes itself but makes use of them if set by your application.
- HttpRequest.current_appLink to this definition
-
The
urltemplate tag will use its value as thecurrent_appargument toreverse().
- HttpRequest.urlconfLink to this definition
This will be used as the root URLconf for the current request, overriding the
ROOT_URLCONFsetting. See How Django processes a request for details.urlconfcan be set toNoneto revert any changes made by previous middleware and return to using theROOT_URLCONF.
Attributes set by middlewareLink to this heading
Some of the middleware included in Django’s contrib apps set attributes on the
request. If you don’t see the attribute on a request, be sure the appropriate
middleware class is listed in MIDDLEWARE_CLASSES.
- HttpRequest.sessionLink to this definition
From the
SessionMiddleware: A readable and writable, dictionary-like object that represents the current session.
- HttpRequest.siteLink to this definition
From the
CurrentSiteMiddleware: An instance ofSiteorRequestSiteas returned byget_current_site()representing the current site.
- HttpRequest.userLink to this definition
From the
AuthenticationMiddleware: An instance ofAUTH_USER_MODELrepresenting the currently logged-in user. If the user isn’t currently logged in,userwill be set to an instance ofAnonymousUser. You can tell them apart withis_authenticated(), like so:if request.user.is_authenticated(): ... # Do something for logged-in users. else: ... # Do something for anonymous users.
MethodsLink to this heading
- HttpRequest.get_host()Link to this definition
Returns the originating host of the request using information from the
HTTP_X_FORWARDED_HOST(ifUSE_X_FORWARDED_HOSTis enabled) andHTTP_HOSTheaders, in that order. If they don’t provide a value, the method uses a combination ofSERVER_NAMEandSERVER_PORTas detailed in PEP 3333.Example:
"127.0.0.1:8000"
- HttpRequest.get_port()Link to this definition
-
Returns the originating port of the request using information from the
HTTP_X_FORWARDED_PORT(ifUSE_X_FORWARDED_PORTis enabled) andSERVER_PORTMETAvariables, in that order.
- HttpRequest.get_full_path()Link to this definition
Returns the
path, plus an appended query string, if applicable.Example:
"/music/bands/the_beatles/?print=true"
- HttpRequest.build_absolute_uri(location)Link to this definition
Returns the absolute URI form of
location. If no location is provided, the location will be set torequest.get_full_path().If the location is already an absolute URI, it will not be altered. Otherwise the absolute URI is built using the server variables available in this request.
Example:
"https://example.com/music/bands/the_beatles/?print=true"
- HttpRequest.get_signed_cookie(key, default=RAISE_ERROR, salt='', max_age=None)Link to this definition
Returns a cookie value for a signed cookie, or raises a
django.core.signing.BadSignatureexception if the signature is no longer valid. If you provide thedefaultargument the exception will be suppressed and that default value will be returned instead.The optional
saltargument can be used to provide extra protection against brute force attacks on your secret key. If supplied, themax_ageargument will be checked against the signed timestamp attached to the cookie value to ensure the cookie is not older thanmax_ageseconds.For example:
>>> request.get_signed_cookie('name') 'Tony' >>> request.get_signed_cookie('name', salt='name-salt') 'Tony' # assuming cookie was set using the same salt >>> request.get_signed_cookie('non-existing-cookie') ... KeyError: 'non-existing-cookie' >>> request.get_signed_cookie('non-existing-cookie', False) False >>> request.get_signed_cookie('cookie-that-was-tampered-with') ... BadSignature: ... >>> request.get_signed_cookie('name', max_age=60) ... SignatureExpired: Signature age 1677.3839159 > 60 seconds >>> request.get_signed_cookie('name', False, max_age=60) FalseSee cryptographic signing for more information.
- HttpRequest.is_secure()Link to this definition
Returns
Trueif the request is secure; that is, if it was made with HTTPS.
- HttpRequest.is_ajax()Link to this definition
Returns
Trueif the request was made via anXMLHttpRequest, by checking theHTTP_X_REQUESTED_WITHheader for the string'XMLHttpRequest'. Most modern JavaScript libraries send this header. If you write your own XMLHttpRequest call (on the browser side), you’ll have to set this header manually if you wantis_ajax()to work.If a response varies on whether or not it’s requested via AJAX and you are using some form of caching like Django’s
cache middleware, you should decorate the view withvary_on_headers('X-Requested-With')so that the responses are properly cached.
- HttpRequest.read(size=None)Link to this definition
- HttpRequest.readline()Link to this definition
- HttpRequest.readlines()Link to this definition
- HttpRequest.xreadlines()Link to this definition
- HttpRequest.__iter__()Link to this definition
Methods implementing a file-like interface for reading from an HttpRequest instance. This makes it possible to consume an incoming request in a streaming fashion. A common use-case would be to process a big XML payload with an iterative parser without constructing a whole XML tree in memory.
Given this standard interface, an HttpRequest instance can be passed directly to an XML parser such as ElementTree:
import xml.etree.ElementTree as ET for element in ET.iterparse(request): process(element)
QueryDict objectsLink to this heading
- class QueryDictLink to this definition
In an HttpRequest object, the GET and POST attributes are
instances of django.http.QueryDict, 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>, pass multiple values for the same
key.
The QueryDicts at request.POST and request.GET will be immutable
when accessed in a normal request/response cycle. To get a mutable version you
need to use .copy().
MethodsLink to this heading
QueryDict implements all the standard dictionary methods because it’s
a subclass of dictionary. Exceptions are outlined here:
- QueryDict.__init__(query_string=None, mutable=False, encoding=None)Link to this definition
Instantiates a
QueryDictobject based onquery_string.>>> QueryDict('a=1&a=2&c=3') <QueryDict: {'a': ['1', '2'], 'c': ['3']}>If
query_stringis not passed in, the resultingQueryDictwill be empty (it will have no keys or values).Most
QueryDicts you encounter, and in particular those atrequest.POSTandrequest.GET, will be immutable. If you are instantiating one yourself, you can make it mutable by passingmutable=Trueto its__init__().Strings for setting both keys and values will be converted from
encodingto unicode. If encoding is not set, it defaults toDEFAULT_CHARSET.
- QueryDict.__getitem__(key)Link to this definition
Returns the value for the given key. If the key has more than one value,
__getitem__()returns the last value. Raisesdjango.utils.datastructures.MultiValueDictKeyErrorif the key does not exist. (This is a subclass of Python’s standardKeyError, so you can stick to catchingKeyError.)
- QueryDict.__setitem__(key, value)Link to this definition
Sets the given key to
[value](a Python list whose single element isvalue). Note that this, as other dictionary functions that have side effects, can only be called on a mutableQueryDict(such as one that was created viacopy()).
- QueryDict.__contains__(key)Link to this definition
Returns
Trueif the given key is set. This lets you do, e.g.,if "foo" in request.GET.
- QueryDict.get(key, default=None)Link to this definition
Uses the same logic as
__getitem__()above, with a hook for returning a default value if the key doesn’t exist.
- QueryDict.setdefault(key, default=None)Link to this definition
Just like the standard dictionary
setdefault()method, except it uses__setitem__()internally.
- QueryDict.update(other_dict)Link to this definition
Takes either a
QueryDictor standard dictionary. Just like the standard dictionaryupdate()method, except it appends to the current dictionary items rather than replacing them. For example:>>> q = QueryDict('a=1', mutable=True) >>> q.update({'a': '2'}) >>> q.getlist('a') ['1', '2'] >>> q['a'] # returns the last '2'
- QueryDict.items()Link to this definition
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')]
- QueryDict.iteritems()Link to this definition
Just like the standard dictionary
iteritems()method. LikeQueryDict.items()this uses the same last-value logic asQueryDict.__getitem__().
- QueryDict.iterlists()Link to this definition
Like
QueryDict.iteritems()except it includes all values, as a list, for each member of the dictionary.
- QueryDict.values()Link to this definition
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']
- QueryDict.itervalues()Link to this definition
Just like
QueryDict.values(), except an iterator.
In addition, QueryDict has the following methods:
- QueryDict.copy()Link to this definition
Returns a copy of the object, using
copy.deepcopy()from the Python standard library. This copy will be mutable even if the original was not.
- QueryDict.getlist(key, default=None)Link to this definition
Returns the data with the requested key, as a Python list. Returns an empty list if the key doesn’t exist and no default value was provided. It’s guaranteed to return a list of some sort unless the default value provided is not a list.
- QueryDict.setlist(key, list_)Link to this definition
Sets the given key to
list_(unlike__setitem__()).
- QueryDict.appendlist(key, item)Link to this definition
Appends an item to the internal list associated with key.
- QueryDict.setlistdefault(key, default_list=None)Link to this definition
Just like
setdefault, except it takes a list of values instead of a single value.
- QueryDict.lists()Link to this definition
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'])]
- QueryDict.pop(key)Link to this definition
Returns a list of values for the given key and removes them from the dictionary. Raises
KeyErrorif the key does not exist. For example:>>> q = QueryDict('a=1&a=2&a=3', mutable=True) >>> q.pop('a') ['1', '2', '3']
- QueryDict.popitem()Link to this definition
Removes an arbitrary member of the dictionary (since there’s no concept of ordering), and returns a two value tuple containing the key and a list of all values for the key. Raises
KeyErrorwhen called on an empty dictionary. For example:>>> q = QueryDict('a=1&a=2&a=3', mutable=True) >>> q.popitem() ('a', ['1', '2', '3'])
- QueryDict.dict()Link to this definition
Returns
dictrepresentation ofQueryDict. For every (key, list) pair inQueryDict,dictwill have (key, item), where item is one element of the list, using same logic asQueryDict.__getitem__():>>> q = QueryDict('a=1&a=3&a=5') >>> q.dict() {'a': '5'}
- QueryDict.urlencode(safe=None)Link to this definition
Returns a string of the data in query-string format. Example:
>>> q = QueryDict('a=2&b=3&b=5') >>> q.urlencode() 'a=2&b=3&b=5'Optionally, urlencode can be passed characters which do not require encoding. For example:
>>> q = QueryDict(mutable=True) >>> q['next'] = '/a&b/' >>> q.urlencode(safe='/') 'next=/a%26b/'
HttpResponse objectsLink to this heading
- class HttpResponseLink to this definition
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 in the django.http module.
UsageLink to this heading
Passing stringsLink to this heading
Typical usage is to pass the contents of the page, as a string, to the
HttpResponse constructor:
>>> from django.http import HttpResponse
>>> response = HttpResponse("Here's the text of the Web page.")
>>> response = HttpResponse("Text only, please.", content_type="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>")
Passing iteratorsLink to this heading
Finally, you can pass HttpResponse an iterator rather than strings.
HttpResponse will consume the iterator immediately, store its content as a
string, and discard it.
If you need the response to be streamed from the iterator to the client, you
must use the StreamingHttpResponse class instead.
Setting header fieldsLink to this heading
To set or remove a header field in your response, treat it like a dictionary:
>>> response = HttpResponse()
>>> response['Age'] = 120
>>> del response['Age']
Note that unlike a dictionary, del doesn’t raise KeyError if the header
field doesn’t exist.
For setting the Cache-Control and Vary header fields, it is recommended
to use the patch_cache_control() and
patch_vary_headers() methods from
django.utils.cache, since these fields can have multiple, comma-separated
values. The «patch» methods ensure that other values, e.g. added by a
middleware, are not removed.
HTTP header fields cannot contain newlines. An attempt to set a header field
containing a newline character (CR or LF) will raise BadHeaderError
Telling the browser to treat the response as a file attachmentLink to this heading
To tell the browser to treat the response as a file attachment, use the
content_type argument and set the Content-Disposition header. For example,
this is how you might return a Microsoft Excel spreadsheet:
>>> response = HttpResponse(my_data, content_type='application/vnd.ms-excel')
>>> response['Content-Disposition'] = 'attachment; filename="foo.xls"'
There’s nothing Django-specific about the Content-Disposition header, but
it’s easy to forget the syntax, so we’ve included it here.
AttributesLink to this heading
- HttpResponse.contentLink to this definition
A bytestring representing the content, encoded from a Unicode object if necessary.
- HttpResponse.charsetLink to this definition
-
A string denoting the charset in which the response will be encoded. If not given at
HttpResponseinstantiation time, it will be extracted fromcontent_typeand if that is unsuccessful, theDEFAULT_CHARSETsetting will be used.
- HttpResponse.status_codeLink to this definition
The HTTP status code for the response.
- HttpResponse.reason_phraseLink to this definition
The HTTP reason phrase for the response.
- HttpResponse.streamingLink to this definition
This is always
False.This attribute exists so middleware can treat streaming responses differently from regular responses.
- HttpResponse.closedLink to this definition
-
Trueif the response has been closed.
MethodsLink to this heading
- HttpResponse.__init__(content='', content_type=None, status=200, reason=None, charset=None)Link to this definition
Instantiates an
HttpResponseobject with the given page content and content type.contentshould 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. If it is not an iterator or a string, it will be converted to a string when accessed.content_typeis the MIME type optionally completed by a character set encoding and is used to fill the HTTPContent-Typeheader. If not specified, it is formed by theDEFAULT_CONTENT_TYPEandDEFAULT_CHARSETsettings, by default: «text/html; charset=utf-8».statusis the HTTP status code for the response.reasonis the HTTP response phrase. If not provided, a default phrase will be used.charsetis the charset in which the response will be encoded. If not given it will be extracted fromcontent_type, and if that is unsuccessful, theDEFAULT_CHARSETsetting will be used.
- HttpResponse.__setitem__(header, value)Link to this definition
Sets the given header name to the given value. Both
headerandvalueshould be strings.
- HttpResponse.__delitem__(header)Link to this definition
Deletes the header with the given name. Fails silently if the header doesn’t exist. Case-insensitive.
- HttpResponse.__getitem__(header)Link to this definition
Returns the value for the given header name. Case-insensitive.
- HttpResponse.has_header(header)Link to this definition
Returns
TrueorFalsebased on a case-insensitive check for a header with the given name.
- HttpResponse.setdefault(header, value)Link to this definition
-
Sets a header unless it has already been set.
- HttpResponse.set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=False)Link to this definition
Sets a cookie. The parameters are the same as in the
Morselcookie object in the Python standard library.max_ageshould be a number of seconds, orNone(default) if the cookie should last only as long as the client’s browser session. Ifexpiresis not specified, it will be calculated.expiresshould either be a string in the format"Wdy, DD-Mon-YY HH:MM:SS GMT"or adatetime.datetimeobject in UTC. Ifexpiresis adatetimeobject, themax_agewill be calculated.Use
domainif 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.Use
httponly=Trueif you want to prevent client-side JavaScript from having access to the cookie.HTTPOnly is a flag included in a Set-Cookie HTTP response header. It is not part of the RFC 2109 standard for cookies, and it isn’t honored consistently by all browsers. However, when it is honored, it can be a useful way to mitigate the risk of a client-side script from accessing the protected cookie data.
- HttpResponse.set_signed_cookie(key, value, salt='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=True)Link to this definition
Like
set_cookie(), but cryptographic signing the cookie before setting it. Use in conjunction withHttpRequest.get_signed_cookie(). You can use the optionalsaltargument for added key strength, but you will need to remember to pass it to the correspondingHttpRequest.get_signed_cookie()call.
- HttpResponse.delete_cookie(key, path='/', domain=None)Link to this definition
Deletes the cookie with the given key. Fails silently if the key doesn’t exist.
Due to the way cookies work,
pathanddomainshould be the same values you used inset_cookie()– otherwise the cookie may not be deleted.
- HttpResponse.write(content)Link to this definition
This method makes an
HttpResponseinstance a file-like object.
- HttpResponse.flush()Link to this definition
This method makes an
HttpResponseinstance a file-like object.
- HttpResponse.tell()Link to this definition
This method makes an
HttpResponseinstance a file-like object.
- HttpResponse.getvalue()Link to this definition
-
Returns the value of
HttpResponse.content. This method makes anHttpResponseinstance a stream-like object.
- HttpResponse.writable()Link to this definition
-
Always
True. This method makes anHttpResponseinstance a stream-like object.
- HttpResponse.writelines(lines)Link to this definition
-
Writes a list of lines to the response. Line separators are not added. This method makes an
HttpResponseinstance a stream-like object.
HttpResponse subclassesLink to this heading
Django includes a number of HttpResponse subclasses that handle different
types of HTTP responses. Like HttpResponse, these subclasses live in
django.http.
- class HttpResponseRedirectLink to this definition
The first argument to the constructor is required – the path to redirect to. This can be a fully qualified URL (e.g.
'https://www.yahoo.com/search/'), an absolute path with no domain (e.g.'/search/'), or even a relative path (e.g.'search/'). In that last case, the client browser will reconstruct the full URL itself according to the current path. SeeHttpResponsefor other optional constructor arguments. Note that this returns an HTTP status code 302.- urlLink to this definition
This read-only attribute represents the URL the response will redirect to (equivalent to the
Locationresponse header).
- class HttpResponsePermanentRedirectLink to this definition
Like
HttpResponseRedirect, but it returns a permanent redirect (HTTP status code 301) instead of a «found» redirect (status code 302).
- class HttpResponseNotModifiedLink to this definition
The constructor doesn’t take any arguments and no content should be added to this response. Use this to designate that a page hasn’t been modified since the user’s last request (status code 304).
- class HttpResponseBadRequestLink to this definition
Acts just like
HttpResponsebut uses a 400 status code.
- class HttpResponseNotFoundLink to this definition
Acts just like
HttpResponsebut uses a 404 status code.
- class HttpResponseForbiddenLink to this definition
Acts just like
HttpResponsebut uses a 403 status code.
- class HttpResponseNotAllowedLink to this definition
Like
HttpResponse, but uses a 405 status code. The first argument to the constructor is required: a list of permitted methods (e.g.['GET', 'POST']).
- class HttpResponseGoneLink to this definition
Acts just like
HttpResponsebut uses a 410 status code.
- class HttpResponseServerErrorLink to this definition
Acts just like
HttpResponsebut uses a 500 status code.
JsonResponse objectsLink to this heading
- class JsonResponse(data, encoder=DjangoJSONEncoder, safe=True, json_dumps_params=None, **kwargs)Link to this definition
An
HttpResponsesubclass that helps to create a JSON-encoded response. It inherits most behavior from its superclass with a couple differences:Its default
Content-Typeheader is set toapplication/json.The first parameter,
data, should be adictinstance. If thesafeparameter is set toFalse(see below) it can be any JSON-serializable object.The
encoder, which defaults todjango.core.serializers.json.DjangoJSONEncoder, will be used to serialize the data. See JSON serialization for more details about this serializer.The
safeboolean parameter defaults toTrue. If it’s set toFalse, any object can be passed for serialization (otherwise onlydictinstances are allowed). IfsafeisTrueand a non-dictobject is passed as the first argument, aTypeErrorwill be raised.The
json_dumps_paramsparameter is a dictionary of keyword arguments to pass to thejson.dumps()call used to generate the response.
UsageLink to this heading
Typical usage could look like:
>>> from django.http import JsonResponse
>>> response = JsonResponse({'foo': 'bar'})
>>> response.content
b'{"foo": "bar"}'
Serializing non-dictionary objectsLink to this heading
In order to serialize objects other than dict you must set the safe
parameter to False:
>>> response = JsonResponse([1, 2, 3], safe=False)
Without passing safe=False, a TypeError will be raised.
Changing the default JSON encoderLink to this heading
If you need to use a different JSON encoder class you can pass the encoder
parameter to the constructor method:
>>> response = JsonResponse(data, encoder=MyJSONEncoder)
StreamingHttpResponse objectsLink to this heading
- class StreamingHttpResponseLink to this definition
The StreamingHttpResponse class is used to stream a response from
Django to the browser. You might want to do this if generating the response
takes too long or uses too much memory. For instance, it’s useful for
generating large CSV files.
The StreamingHttpResponse is not a subclass of HttpResponse,
because it features a slightly different API. However, it is almost identical,
with the following notable differences:
It should be given an iterator that yields strings as content.
You cannot access its content, except by iterating the response object itself. This should only occur when the response is returned to the client.
It has no
contentattribute. Instead, it has astreaming_contentattribute.You cannot use the file-like object
tell()orwrite()methods. Doing so will raise an exception.
StreamingHttpResponse should only be used in situations where it is
absolutely required that the whole content isn’t iterated before transferring
the data to the client. Because the content can’t be accessed, many
middlewares can’t function normally. For example the ETag and Content-
Length headers can’t be generated for streaming responses.
AttributesLink to this heading
- StreamingHttpResponse.streaming_contentLink to this definition
An iterator of strings representing the content.
- StreamingHttpResponse.status_codeLink to this definition
The HTTP status code for the response.
- StreamingHttpResponse.reason_phraseLink to this definition
The HTTP reason phrase for the response.
- StreamingHttpResponse.streamingLink to this definition
This is always
True.
FileResponse objectsLink to this heading
- class FileResponseLink to this definition
FileResponse is a subclass of StreamingHttpResponse optimized
for binary files. It uses wsgi.file_wrapper if provided by the wsgi server,
otherwise it streams the file out in small chunks.
FileResponse expects a file open in binary mode like so:
>>> from django.http import FileResponse
>>> response = FileResponse(open('myfile.png', 'rb'))