mirror of
https://github.com/django/django.git
synced 2024-12-23 09:36:06 +00:00
1233 lines
46 KiB
Plaintext
1233 lines
46 KiB
Plaintext
============================
|
|
Request and response objects
|
|
============================
|
|
|
|
.. module:: django.http
|
|
:synopsis: Classes dealing with HTTP requests and responses.
|
|
|
|
Quick overview
|
|
==============
|
|
|
|
Django uses request and response objects to pass state through the system.
|
|
|
|
When a page is requested, Django creates an :class:`HttpRequest` object that
|
|
contains metadata about the request. Then Django loads the appropriate view,
|
|
passing the :class:`HttpRequest` as the first argument to the view function.
|
|
Each view is responsible for returning an :class:`HttpResponse` object.
|
|
|
|
This document explains the APIs for :class:`HttpRequest` and
|
|
:class:`HttpResponse` objects, which are defined in the :mod:`django.http`
|
|
module.
|
|
|
|
``HttpRequest`` objects
|
|
=======================
|
|
|
|
.. class:: HttpRequest
|
|
|
|
.. _httprequest-attributes:
|
|
|
|
Attributes
|
|
----------
|
|
|
|
All attributes should be considered read-only, unless stated otherwise.
|
|
|
|
.. attribute:: HttpRequest.scheme
|
|
|
|
A string representing the scheme of the request (``http`` or ``https``
|
|
usually).
|
|
|
|
.. attribute:: HttpRequest.body
|
|
|
|
The raw HTTP request body as a bytestring. This is useful for processing
|
|
data in different ways than conventional HTML forms: binary images,
|
|
XML payload etc. For processing conventional form data, use
|
|
:attr:`HttpRequest.POST`.
|
|
|
|
You can also read from an ``HttpRequest`` using a file-like interface with
|
|
:meth:`HttpRequest.read` or :meth:`HttpRequest.readline`. Accessing
|
|
the ``body`` attribute *after* reading the request with either of these I/O
|
|
stream methods will produce a ``RawPostDataException``.
|
|
|
|
.. attribute:: HttpRequest.path
|
|
|
|
A string representing the full path to the requested page, not including
|
|
the scheme, domain, or query string.
|
|
|
|
Example: ``"/music/bands/the_beatles/"``
|
|
|
|
.. attribute:: HttpRequest.path_info
|
|
|
|
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_info`` attribute always contains the path info portion
|
|
of the path, no matter what web server is being used. Using this instead
|
|
of :attr:`~HttpRequest.path` can make your code easier to move between
|
|
test and deployment servers.
|
|
|
|
For example, if the ``WSGIScriptAlias`` for your application is set to
|
|
``"/minfo"``, then ``path`` might be ``"/minfo/music/bands/the_beatles/"``
|
|
and ``path_info`` would be ``"/music/bands/the_beatles/"``.
|
|
|
|
.. attribute:: HttpRequest.method
|
|
|
|
A string representing the HTTP method used in the request. This is
|
|
guaranteed to be uppercase. For example::
|
|
|
|
if request.method == 'GET':
|
|
do_something()
|
|
elif request.method == 'POST':
|
|
do_something_else()
|
|
|
|
.. attribute:: HttpRequest.encoding
|
|
|
|
A string representing the current encoding used to decode form submission
|
|
data (or ``None``, which means the :setting:`DEFAULT_CHARSET` setting 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
|
|
from :attr:`GET` or :attr:`POST`) will use the new ``encoding`` value.
|
|
Useful if you know the form data is not in the :setting:`DEFAULT_CHARSET`
|
|
encoding.
|
|
|
|
.. attribute:: HttpRequest.content_type
|
|
|
|
A string representing the MIME type of the request, parsed from the
|
|
``CONTENT_TYPE`` header.
|
|
|
|
.. attribute:: HttpRequest.content_params
|
|
|
|
A dictionary of key/value parameters included in the ``CONTENT_TYPE``
|
|
header.
|
|
|
|
.. attribute:: HttpRequest.GET
|
|
|
|
A dictionary-like object containing all given HTTP GET parameters. See the
|
|
:class:`QueryDict` documentation below.
|
|
|
|
.. attribute:: HttpRequest.POST
|
|
|
|
A dictionary-like object containing all given HTTP POST parameters,
|
|
providing that the request contains form data. See the
|
|
:class:`QueryDict` documentation below. If you need to access raw or
|
|
non-form data posted in the request, access this through the
|
|
:attr:`HttpRequest.body` attribute instead.
|
|
|
|
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 :attr:`HttpRequest.method`).
|
|
|
|
``POST`` does *not* include file-upload information. See :attr:`FILES`.
|
|
|
|
.. attribute:: HttpRequest.COOKIES
|
|
|
|
A dictionary containing all cookies. Keys and values are strings.
|
|
|
|
.. attribute:: HttpRequest.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 an :class:`~django.core.files.uploadedfile.UploadedFile`.
|
|
|
|
See :doc:`/topics/files` for more information.
|
|
|
|
``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.
|
|
|
|
.. attribute:: HttpRequest.META
|
|
|
|
A 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_LENGTH`` and ``CONTENT_TYPE``, as given
|
|
above, any HTTP headers in the request are converted to ``META`` keys by
|
|
converting all characters to uppercase, replacing any hyphens with
|
|
underscores and adding an ``HTTP_`` prefix to the name. So, for example, a
|
|
header called ``X-Bender`` would be mapped to the ``META`` key
|
|
``HTTP_X_BENDER``.
|
|
|
|
Note that :djadmin:`runserver` strips all headers with underscores in the
|
|
name, so you won't see them in ``META``. 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+.
|
|
|
|
:attr:`HttpRequest.headers` is a simpler way to access all HTTP-prefixed
|
|
headers, plus ``CONTENT_LENGTH`` and ``CONTENT_TYPE``.
|
|
|
|
.. attribute:: HttpRequest.headers
|
|
|
|
A case insensitive, dict-like object that provides access to all
|
|
HTTP-prefixed headers (plus ``Content-Length`` and ``Content-Type``) from
|
|
the request.
|
|
|
|
The name of each header is stylized with title-casing (e.g. ``User-Agent``)
|
|
when it's displayed. You can access headers case-insensitively::
|
|
|
|
>>> request.headers
|
|
{'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6', ...}
|
|
|
|
>>> 'User-Agent' in request.headers
|
|
True
|
|
>>> 'user-agent' in request.headers
|
|
True
|
|
|
|
>>> request.headers['User-Agent']
|
|
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)
|
|
>>> request.headers['user-agent']
|
|
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)
|
|
|
|
>>> request.headers.get('User-Agent')
|
|
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)
|
|
>>> request.headers.get('user-agent')
|
|
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)
|
|
|
|
For use in, for example, Django templates, headers can also be looked up
|
|
using underscores in place of hyphens::
|
|
|
|
{{ request.headers.user_agent }}
|
|
|
|
.. attribute:: HttpRequest.resolver_match
|
|
|
|
An instance of :class:`~django.urls.ResolverMatch` representing 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 which are
|
|
executed before URL resolving takes place (you can use it in
|
|
:meth:`process_view` though).
|
|
|
|
Attributes set by application code
|
|
----------------------------------
|
|
|
|
Django doesn't set these attributes itself but makes use of them if set by your
|
|
application.
|
|
|
|
.. attribute:: HttpRequest.current_app
|
|
|
|
The :ttag:`url` template tag will use its value as the ``current_app``
|
|
argument to :func:`~django.urls.reverse()`.
|
|
|
|
.. attribute:: HttpRequest.urlconf
|
|
|
|
This will be used as the root URLconf for the current request, overriding
|
|
the :setting:`ROOT_URLCONF` setting. See
|
|
:ref:`how-django-processes-a-request` for details.
|
|
|
|
``urlconf`` can be set to ``None`` to revert any changes made by previous
|
|
middleware and return to using the :setting:`ROOT_URLCONF`.
|
|
|
|
.. attribute:: HttpRequest.exception_reporter_filter
|
|
|
|
This will be used instead of :setting:`DEFAULT_EXCEPTION_REPORTER_FILTER`
|
|
for the current request. See :ref:`custom-error-reports` for details.
|
|
|
|
.. attribute:: HttpRequest.exception_reporter_class
|
|
|
|
This will be used instead of :setting:`DEFAULT_EXCEPTION_REPORTER` for the
|
|
current request. See :ref:`custom-error-reports` for details.
|
|
|
|
Attributes set by middleware
|
|
----------------------------
|
|
|
|
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 :setting:`MIDDLEWARE`.
|
|
|
|
.. attribute:: HttpRequest.session
|
|
|
|
From the :class:`~django.contrib.sessions.middleware.SessionMiddleware`: A
|
|
readable and writable, dictionary-like object that represents the current
|
|
session.
|
|
|
|
.. attribute:: HttpRequest.site
|
|
|
|
From the :class:`~django.contrib.sites.middleware.CurrentSiteMiddleware`:
|
|
An instance of :class:`~django.contrib.sites.models.Site` or
|
|
:class:`~django.contrib.sites.requests.RequestSite` as returned by
|
|
:func:`~django.contrib.sites.shortcuts.get_current_site()`
|
|
representing the current site.
|
|
|
|
.. attribute:: HttpRequest.user
|
|
|
|
From the :class:`~django.contrib.auth.middleware.AuthenticationMiddleware`:
|
|
An instance of :setting:`AUTH_USER_MODEL` representing the currently
|
|
logged-in user. If the user isn't currently logged in, ``user`` will be set
|
|
to an instance of :class:`~django.contrib.auth.models.AnonymousUser`. You
|
|
can tell them apart with
|
|
:attr:`~django.contrib.auth.models.User.is_authenticated`, like so::
|
|
|
|
if request.user.is_authenticated:
|
|
... # Do something for logged-in users.
|
|
else:
|
|
... # Do something for anonymous users.
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. method:: HttpRequest.get_host()
|
|
|
|
Returns the originating host of the request using information from the
|
|
``HTTP_X_FORWARDED_HOST`` (if :setting:`USE_X_FORWARDED_HOST` is enabled)
|
|
and ``HTTP_HOST`` headers, in that order. If they don't provide a value,
|
|
the method uses a combination of ``SERVER_NAME`` and ``SERVER_PORT`` as
|
|
detailed in :pep:`3333`.
|
|
|
|
Example: ``"127.0.0.1:8000"``
|
|
|
|
Raises ``django.core.exceptions.DisallowedHost`` if the host is not in
|
|
:setting:`ALLOWED_HOSTS` or the domain name is invalid according to
|
|
:rfc:`1034`/:rfc:`1035 <1035>`.
|
|
|
|
.. note:: The :meth:`~HttpRequest.get_host()` method fails when the host is
|
|
behind multiple proxies. One solution is to use middleware to rewrite
|
|
the proxy headers, as in the following example::
|
|
|
|
class MultipleProxyMiddleware:
|
|
FORWARDED_FOR_FIELDS = [
|
|
'HTTP_X_FORWARDED_FOR',
|
|
'HTTP_X_FORWARDED_HOST',
|
|
'HTTP_X_FORWARDED_SERVER',
|
|
]
|
|
|
|
def __init__(self, get_response):
|
|
self.get_response = get_response
|
|
|
|
def __call__(self, request):
|
|
"""
|
|
Rewrites the proxy headers so that only the most
|
|
recent proxy is used.
|
|
"""
|
|
for field in self.FORWARDED_FOR_FIELDS:
|
|
if field in request.META:
|
|
if ',' in request.META[field]:
|
|
parts = request.META[field].split(',')
|
|
request.META[field] = parts[-1].strip()
|
|
return self.get_response(request)
|
|
|
|
This middleware should be positioned before any other middleware that
|
|
relies on the value of :meth:`~HttpRequest.get_host()` -- for instance,
|
|
:class:`~django.middleware.common.CommonMiddleware` or
|
|
:class:`~django.middleware.csrf.CsrfViewMiddleware`.
|
|
|
|
.. method:: HttpRequest.get_port()
|
|
|
|
Returns the originating port of the request using information from the
|
|
``HTTP_X_FORWARDED_PORT`` (if :setting:`USE_X_FORWARDED_PORT` is enabled)
|
|
and ``SERVER_PORT`` ``META`` variables, in that order.
|
|
|
|
.. method:: HttpRequest.get_full_path()
|
|
|
|
Returns the ``path``, plus an appended query string, if applicable.
|
|
|
|
Example: ``"/music/bands/the_beatles/?print=true"``
|
|
|
|
.. method:: HttpRequest.get_full_path_info()
|
|
|
|
Like :meth:`get_full_path`, but uses :attr:`path_info` instead of
|
|
:attr:`path`.
|
|
|
|
Example: ``"/minfo/music/bands/the_beatles/?print=true"``
|
|
|
|
.. method:: HttpRequest.build_absolute_uri(location=None)
|
|
|
|
Returns the absolute URI form of ``location``. If no location is provided,
|
|
the location will be set to ``request.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. For example:
|
|
|
|
>>> request.build_absolute_uri()
|
|
'https://example.com/music/bands/the_beatles/?print=true'
|
|
>>> request.build_absolute_uri('/bands/')
|
|
'https://example.com/bands/'
|
|
>>> request.build_absolute_uri('https://example2.com/bands/')
|
|
'https://example2.com/bands/'
|
|
|
|
.. note::
|
|
|
|
Mixing HTTP and HTTPS on the same site is discouraged, therefore
|
|
:meth:`~HttpRequest.build_absolute_uri()` will always generate an
|
|
absolute URI with the same scheme the current request has. If you need
|
|
to redirect users to HTTPS, it's best to let your web server redirect
|
|
all HTTP traffic to HTTPS.
|
|
|
|
.. method:: HttpRequest.get_signed_cookie(key, default=RAISE_ERROR, salt='', max_age=None)
|
|
|
|
Returns a cookie value for a signed cookie, or raises a
|
|
``django.core.signing.BadSignature`` exception if the signature is
|
|
no longer valid. If you provide the ``default`` argument the exception
|
|
will be suppressed and that default value will be returned instead.
|
|
|
|
The optional ``salt`` argument can be used to provide extra protection
|
|
against brute force attacks on your secret key. If supplied, the
|
|
``max_age`` argument will be checked against the signed timestamp
|
|
attached to the cookie value to ensure the cookie is not older than
|
|
``max_age`` seconds.
|
|
|
|
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('nonexistent-cookie')
|
|
...
|
|
KeyError: 'nonexistent-cookie'
|
|
>>> request.get_signed_cookie('nonexistent-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)
|
|
False
|
|
|
|
See :doc:`cryptographic signing </topics/signing>` for more information.
|
|
|
|
.. method:: HttpRequest.is_secure()
|
|
|
|
Returns ``True`` if the request is secure; that is, if it was made with
|
|
HTTPS.
|
|
|
|
.. method:: HttpRequest.accepts(mime_type)
|
|
|
|
Returns ``True`` if the request ``Accept`` header matches the ``mime_type``
|
|
argument::
|
|
|
|
>>> request.accepts('text/html')
|
|
True
|
|
|
|
Most browsers send ``Accept: */*`` by default, so this would return
|
|
``True`` for all content types. Setting an explicit ``Accept`` header in
|
|
API requests can be useful for returning a different content type for those
|
|
consumers only. See :ref:`content-negotiation-example` of using
|
|
``accepts()`` to return different content to API consumers.
|
|
|
|
If a response varies depending on the content of the ``Accept`` header and
|
|
you are using some form of caching like Django's :mod:`cache middleware
|
|
<django.middleware.cache>`, you should decorate the view with
|
|
:func:`vary_on_headers('Accept')
|
|
<django.views.decorators.vary.vary_on_headers>` so that the responses are
|
|
properly cached.
|
|
|
|
.. method:: HttpRequest.read(size=None)
|
|
.. method:: HttpRequest.readline()
|
|
.. method:: HttpRequest.readlines()
|
|
.. method:: HttpRequest.__iter__()
|
|
|
|
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
|
|
:class:`~xml.etree.ElementTree.ElementTree`::
|
|
|
|
import xml.etree.ElementTree as ET
|
|
for element in ET.iterparse(request):
|
|
process(element)
|
|
|
|
|
|
``QueryDict`` objects
|
|
=====================
|
|
|
|
.. class:: QueryDict
|
|
|
|
In an :class:`HttpRequest` object, the :attr:`~HttpRequest.GET` and
|
|
:attr:`~HttpRequest.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 ``QueryDict``\ s 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 :meth:`QueryDict.copy`.
|
|
|
|
Methods
|
|
-------
|
|
|
|
:class:`QueryDict` implements all the standard dictionary methods because it's
|
|
a subclass of dictionary. Exceptions are outlined here:
|
|
|
|
.. method:: QueryDict.__init__(query_string=None, mutable=False, encoding=None)
|
|
|
|
Instantiates a ``QueryDict`` object based on ``query_string``.
|
|
|
|
>>> QueryDict('a=1&a=2&c=3')
|
|
<QueryDict: {'a': ['1', '2'], 'c': ['3']}>
|
|
|
|
If ``query_string`` is not passed in, the resulting ``QueryDict`` will be
|
|
empty (it will have no keys or values).
|
|
|
|
Most ``QueryDict``\ s you encounter, and in particular those at
|
|
``request.POST`` and ``request.GET``, will be immutable. If you are
|
|
instantiating one yourself, you can make it mutable by passing
|
|
``mutable=True`` to its ``__init__()``.
|
|
|
|
Strings for setting both keys and values will be converted from ``encoding``
|
|
to ``str``. If ``encoding`` is not set, it defaults to
|
|
:setting:`DEFAULT_CHARSET`.
|
|
|
|
.. classmethod:: QueryDict.fromkeys(iterable, value='', mutable=False, encoding=None)
|
|
|
|
Creates a new ``QueryDict`` with keys from ``iterable`` and each value
|
|
equal to ``value``. For example::
|
|
|
|
>>> QueryDict.fromkeys(['a', 'a', 'b'], value='val')
|
|
<QueryDict: {'a': ['val', 'val'], 'b': ['val']}>
|
|
|
|
.. method:: QueryDict.__getitem__(key)
|
|
|
|
Returns the value for the given key. If the key has more than one value,
|
|
it returns the last value. Raises
|
|
``django.utils.datastructures.MultiValueDictKeyError`` if the key does not
|
|
exist. (This is a subclass of Python's standard :exc:`KeyError`, so you can
|
|
stick to catching ``KeyError``.)
|
|
|
|
.. method:: QueryDict.__setitem__(key, value)
|
|
|
|
Sets the given key to ``[value]`` (a 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`` (such as one that
|
|
was created via :meth:`QueryDict.copy`).
|
|
|
|
.. method:: QueryDict.__contains__(key)
|
|
|
|
Returns ``True`` if the given key is set. This lets you do, e.g., ``if "foo"
|
|
in request.GET``.
|
|
|
|
.. method:: QueryDict.get(key, default=None)
|
|
|
|
Uses the same logic as :meth:`__getitem__`, with a hook for returning a
|
|
default value if the key doesn't exist.
|
|
|
|
.. method:: QueryDict.setdefault(key, default=None)
|
|
|
|
Like :meth:`dict.setdefault`, except it uses :meth:`__setitem__` internally.
|
|
|
|
.. method:: QueryDict.update(other_dict)
|
|
|
|
Takes either a ``QueryDict`` or a dictionary. Like :meth:`dict.update`,
|
|
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'
|
|
|
|
.. method:: QueryDict.items()
|
|
|
|
Like :meth:`dict.items`, except this uses the same last-value logic as
|
|
:meth:`__getitem__` and returns an iterator object instead of a view object.
|
|
For example::
|
|
|
|
>>> q = QueryDict('a=1&a=2&a=3')
|
|
>>> list(q.items())
|
|
[('a', '3')]
|
|
|
|
.. method:: QueryDict.values()
|
|
|
|
Like :meth:`dict.values`, except this uses the same last-value logic as
|
|
:meth:`__getitem__` and returns an iterator instead of a view object. For
|
|
example::
|
|
|
|
>>> q = QueryDict('a=1&a=2&a=3')
|
|
>>> list(q.values())
|
|
['3']
|
|
|
|
In addition, ``QueryDict`` has the following methods:
|
|
|
|
.. method:: QueryDict.copy()
|
|
|
|
Returns a copy of the object using :func:`copy.deepcopy`. This copy will
|
|
be mutable even if the original was not.
|
|
|
|
.. method:: QueryDict.getlist(key, default=None)
|
|
|
|
Returns a list of the data with the requested key. Returns an empty list if
|
|
the key doesn't exist and ``default`` is ``None``. It's guaranteed to
|
|
return a list unless the default value provided isn't a list.
|
|
|
|
.. method:: QueryDict.setlist(key, list_)
|
|
|
|
Sets the given key to ``list_`` (unlike :meth:`__setitem__`).
|
|
|
|
.. method:: QueryDict.appendlist(key, item)
|
|
|
|
Appends an item to the internal list associated with key.
|
|
|
|
.. method:: QueryDict.setlistdefault(key, default_list=None)
|
|
|
|
Like :meth:`setdefault`, except it takes a list of values instead of a
|
|
single value.
|
|
|
|
.. method:: QueryDict.lists()
|
|
|
|
Like :meth:`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'])]
|
|
|
|
.. method:: QueryDict.pop(key)
|
|
|
|
Returns a list of values for the given key and removes them from the
|
|
dictionary. Raises ``KeyError`` if the key does not exist. For example::
|
|
|
|
>>> q = QueryDict('a=1&a=2&a=3', mutable=True)
|
|
>>> q.pop('a')
|
|
['1', '2', '3']
|
|
|
|
.. method:: QueryDict.popitem()
|
|
|
|
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 ``KeyError`` when called on an empty
|
|
dictionary. For example::
|
|
|
|
>>> q = QueryDict('a=1&a=2&a=3', mutable=True)
|
|
>>> q.popitem()
|
|
('a', ['1', '2', '3'])
|
|
|
|
.. method:: QueryDict.dict()
|
|
|
|
Returns a ``dict`` representation of ``QueryDict``. For every (key, list)
|
|
pair in ``QueryDict``, ``dict`` will have (key, item), where item is one
|
|
element of the list, using the same logic as :meth:`QueryDict.__getitem__`::
|
|
|
|
>>> q = QueryDict('a=1&a=3&a=5')
|
|
>>> q.dict()
|
|
{'a': '5'}
|
|
|
|
.. method:: QueryDict.urlencode(safe=None)
|
|
|
|
Returns a string of the data in query string format. For example::
|
|
|
|
>>> q = QueryDict('a=2&b=3&b=5')
|
|
>>> q.urlencode()
|
|
'a=2&b=3&b=5'
|
|
|
|
Use the ``safe`` parameter to pass characters which don't require encoding.
|
|
For example::
|
|
|
|
>>> q = QueryDict(mutable=True)
|
|
>>> q['next'] = '/a&b/'
|
|
>>> q.urlencode(safe='/')
|
|
'next=/a%26b/'
|
|
|
|
``HttpResponse`` objects
|
|
========================
|
|
|
|
.. class:: HttpResponse
|
|
|
|
In contrast to :class:`HttpRequest` objects, which are created automatically by
|
|
Django, :class:`HttpResponse` objects are your responsibility. Each view you
|
|
write is responsible for instantiating, populating, and returning an
|
|
:class:`HttpResponse`.
|
|
|
|
The :class:`HttpResponse` class lives in the :mod:`django.http` module.
|
|
|
|
Usage
|
|
-----
|
|
|
|
Passing strings
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Typical usage is to pass the contents of the page, as a string, bytestring,
|
|
or :class:`memoryview`, to the :class:`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")
|
|
>>> response = HttpResponse(b'Bytestrings are also accepted.')
|
|
>>> response = HttpResponse(memoryview(b'Memoryview as well.'))
|
|
|
|
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 iterators
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
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. Objects with a ``close()`` method such as files and
|
|
generators are immediately closed.
|
|
|
|
If you need the response to be streamed from the iterator to the client, you
|
|
must use the :class:`StreamingHttpResponse` class instead.
|
|
|
|
.. _setting-header-fields:
|
|
|
|
Setting header fields
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To set or remove a header field in your response, use
|
|
:attr:`HttpResponse.headers`::
|
|
|
|
>>> response = HttpResponse()
|
|
>>> response.headers['Age'] = 120
|
|
>>> del response.headers['Age']
|
|
|
|
You can also manipulate headers by treating your response like a dictionary::
|
|
|
|
>>> response = HttpResponse()
|
|
>>> response['Age'] = 120
|
|
>>> del response['Age']
|
|
|
|
This proxies to ``HttpResponse.headers``, and is the original interface offered
|
|
by ``HttpResponse``.
|
|
|
|
When using this interface, unlike a dictionary, ``del`` doesn't raise
|
|
``KeyError`` if the header field doesn't exist.
|
|
|
|
You can also set headers on instantiation::
|
|
|
|
>>> response = HttpResponse(headers={'Age': 120})
|
|
|
|
For setting the ``Cache-Control`` and ``Vary`` header fields, it is recommended
|
|
to use the :func:`~django.utils.cache.patch_cache_control` and
|
|
:func:`~django.utils.cache.patch_vary_headers` methods from
|
|
:mod:`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 attachment
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To tell the browser to treat the response as a file attachment, set the
|
|
``Content-Type`` and ``Content-Disposition`` headers. For example, this is how
|
|
you might return a Microsoft Excel spreadsheet::
|
|
|
|
>>> response = HttpResponse(my_data, headers={
|
|
... 'Content-Type': 'application/vnd.ms-excel',
|
|
... '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.
|
|
|
|
Attributes
|
|
----------
|
|
|
|
.. attribute:: HttpResponse.content
|
|
|
|
A bytestring representing the content, encoded from a string if necessary.
|
|
|
|
.. attribute:: HttpResponse.headers
|
|
|
|
A case insensitive, dict-like object that provides an interface to all
|
|
HTTP headers on the response. See :ref:`setting-header-fields`.
|
|
|
|
.. attribute:: HttpResponse.charset
|
|
|
|
A string denoting the charset in which the response will be encoded. If not
|
|
given at ``HttpResponse`` instantiation time, it will be extracted from
|
|
``content_type`` and if that is unsuccessful, the
|
|
:setting:`DEFAULT_CHARSET` setting will be used.
|
|
|
|
.. attribute:: HttpResponse.status_code
|
|
|
|
The :rfc:`HTTP status code <7231#section-6>` for the response.
|
|
|
|
Unless :attr:`reason_phrase` is explicitly set, modifying the value of
|
|
``status_code`` outside the constructor will also modify the value of
|
|
``reason_phrase``.
|
|
|
|
.. attribute:: HttpResponse.reason_phrase
|
|
|
|
The HTTP reason phrase for the response. It uses the :rfc:`HTTP standard's
|
|
<7231#section-6.1>` default reason phrases.
|
|
|
|
Unless explicitly set, ``reason_phrase`` is determined by the value of
|
|
:attr:`status_code`.
|
|
|
|
.. attribute:: HttpResponse.streaming
|
|
|
|
This is always ``False``.
|
|
|
|
This attribute exists so middleware can treat streaming responses
|
|
differently from regular responses.
|
|
|
|
.. attribute:: HttpResponse.closed
|
|
|
|
``True`` if the response has been closed.
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. method:: HttpResponse.__init__(content=b'', content_type=None, status=200, reason=None, charset=None, headers=None)
|
|
|
|
Instantiates an ``HttpResponse`` object with the given page content,
|
|
content type, and headers.
|
|
|
|
``content`` is most commonly an iterator, bytestring, :class:`memoryview`,
|
|
or string. Other types will be converted to a bytestring by encoding their
|
|
string representation. Iterators should return strings or bytestrings and
|
|
those will be joined together to form the content of the response.
|
|
|
|
``content_type`` is the MIME type optionally completed by a character set
|
|
encoding and is used to fill the HTTP ``Content-Type`` header. If not
|
|
specified, it is formed by ``'text/html'`` and the
|
|
:setting:`DEFAULT_CHARSET` settings, by default:
|
|
``"text/html; charset=utf-8"``.
|
|
|
|
``status`` is the :rfc:`HTTP status code <7231#section-6>` for the response.
|
|
You can use Python's :py:class:`http.HTTPStatus` for meaningful aliases,
|
|
such as ``HTTPStatus.NO_CONTENT``.
|
|
|
|
``reason`` is the HTTP response phrase. If not provided, a default phrase
|
|
will be used.
|
|
|
|
``charset`` is the charset in which the response will be encoded. If not
|
|
given it will be extracted from ``content_type``, and if that
|
|
is unsuccessful, the :setting:`DEFAULT_CHARSET` setting will be used.
|
|
|
|
``headers`` is a :class:`dict` of HTTP headers for the response.
|
|
|
|
.. method:: HttpResponse.__setitem__(header, value)
|
|
|
|
Sets the given header name to the given value. Both ``header`` and
|
|
``value`` should be strings.
|
|
|
|
.. method:: HttpResponse.__delitem__(header)
|
|
|
|
Deletes the header with the given name. Fails silently if the header
|
|
doesn't exist. Case-insensitive.
|
|
|
|
.. method:: HttpResponse.__getitem__(header)
|
|
|
|
Returns the value for the given header name. Case-insensitive.
|
|
|
|
.. method:: HttpResponse.get(header, alternate=None)
|
|
|
|
Returns the value for the given header, or an ``alternate`` if the header
|
|
doesn't exist.
|
|
|
|
.. method:: HttpResponse.has_header(header)
|
|
|
|
Returns ``True`` or ``False`` based on a case-insensitive check for a
|
|
header with the given name.
|
|
|
|
.. method:: HttpResponse.items()
|
|
|
|
Acts like :meth:`dict.items` for HTTP headers on the response.
|
|
|
|
.. method:: HttpResponse.setdefault(header, value)
|
|
|
|
Sets a header unless it has already been set.
|
|
|
|
.. method:: HttpResponse.set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)
|
|
|
|
Sets a cookie. The parameters are the same as in the
|
|
:class:`~http.cookies.Morsel` cookie object in the Python standard library.
|
|
|
|
* ``max_age`` should be a :class:`~datetime.timedelta` object, an integer
|
|
number of seconds, or ``None`` (default) if the cookie should last only
|
|
as long as the client's browser session. If ``expires`` is not specified,
|
|
it will be calculated.
|
|
|
|
.. versionchanged:: 4.1
|
|
|
|
Support for ``timedelta`` objects was added.
|
|
|
|
* ``expires`` should either be a string in the format
|
|
``"Wdy, DD-Mon-YY HH:MM:SS GMT"`` or a ``datetime.datetime`` object
|
|
in UTC. If ``expires`` is a ``datetime`` object, the ``max_age``
|
|
will be calculated.
|
|
* Use ``domain`` if you want to set a cross-domain cookie. For example,
|
|
``domain="example.com"`` will set a cookie that is readable by the
|
|
domains www.example.com, blog.example.com, etc. Otherwise, a cookie will
|
|
only be readable by the domain that set it.
|
|
* Use ``secure=True`` if you want the cookie to be only sent to the server
|
|
when a request is made with the ``https`` scheme.
|
|
* Use ``httponly=True`` if 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's
|
|
part of the :rfc:`RFC 6265 <6265#section-4.1.2.6>` standard for cookies
|
|
and can be a useful way to mitigate the risk of a client-side script
|
|
accessing the protected cookie data.
|
|
* Use ``samesite='Strict'`` or ``samesite='Lax'`` to tell the browser not
|
|
to send this cookie when performing a cross-origin request. `SameSite`_
|
|
isn't supported by all browsers, so it's not a replacement for Django's
|
|
CSRF protection, but rather a defense in depth measure.
|
|
|
|
Use ``samesite='None'`` (string) to explicitly state that this cookie is
|
|
sent with all same-site and cross-site requests.
|
|
|
|
.. _HttpOnly: https://owasp.org/www-community/HttpOnly
|
|
.. _SameSite: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite
|
|
|
|
.. warning::
|
|
|
|
:rfc:`RFC 6265 <6265#section-6.1>` states that user agents should
|
|
support cookies of at least 4096 bytes. For many browsers this is also
|
|
the maximum size. Django will not raise an exception if there's an
|
|
attempt to store a cookie of more than 4096 bytes, but many browsers
|
|
will not set the cookie correctly.
|
|
|
|
.. method:: HttpResponse.set_signed_cookie(key, value, salt='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)
|
|
|
|
Like :meth:`~HttpResponse.set_cookie()`, but
|
|
:doc:`cryptographic signing </topics/signing>` the cookie before setting
|
|
it. Use in conjunction with :meth:`HttpRequest.get_signed_cookie`.
|
|
You can use the optional ``salt`` argument for added key strength, but
|
|
you will need to remember to pass it to the corresponding
|
|
:meth:`HttpRequest.get_signed_cookie` call.
|
|
|
|
.. method:: HttpResponse.delete_cookie(key, path='/', domain=None, samesite=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.
|
|
|
|
.. method:: HttpResponse.close()
|
|
|
|
This method is called at the end of the request directly by the WSGI
|
|
server.
|
|
|
|
.. method:: HttpResponse.write(content)
|
|
|
|
This method makes an :class:`HttpResponse` instance a file-like object.
|
|
|
|
.. method:: HttpResponse.flush()
|
|
|
|
This method makes an :class:`HttpResponse` instance a file-like object.
|
|
|
|
.. method:: HttpResponse.tell()
|
|
|
|
This method makes an :class:`HttpResponse` instance a file-like object.
|
|
|
|
.. method:: HttpResponse.getvalue()
|
|
|
|
Returns the value of :attr:`HttpResponse.content`. This method makes
|
|
an :class:`HttpResponse` instance a stream-like object.
|
|
|
|
.. method:: HttpResponse.readable()
|
|
|
|
Always ``False``. This method makes an :class:`HttpResponse` instance a
|
|
stream-like object.
|
|
|
|
.. method:: HttpResponse.seekable()
|
|
|
|
Always ``False``. This method makes an :class:`HttpResponse` instance a
|
|
stream-like object.
|
|
|
|
.. method:: HttpResponse.writable()
|
|
|
|
Always ``True``. This method makes an :class:`HttpResponse` instance a
|
|
stream-like object.
|
|
|
|
.. method:: HttpResponse.writelines(lines)
|
|
|
|
Writes a list of lines to the response. Line separators are not added. This
|
|
method makes an :class:`HttpResponse` instance a stream-like object.
|
|
|
|
.. _ref-httpresponse-subclasses:
|
|
|
|
``HttpResponse`` subclasses
|
|
---------------------------
|
|
|
|
Django includes a number of ``HttpResponse`` subclasses that handle different
|
|
types of HTTP responses. Like ``HttpResponse``, these subclasses live in
|
|
:mod:`django.http`.
|
|
|
|
.. class:: HttpResponseRedirect
|
|
|
|
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. See :class:`HttpResponse` for other optional
|
|
constructor arguments. Note that this returns an HTTP status code 302.
|
|
|
|
.. attribute:: HttpResponseRedirect.url
|
|
|
|
This read-only attribute represents the URL the response will redirect
|
|
to (equivalent to the ``Location`` response header).
|
|
|
|
.. class:: HttpResponsePermanentRedirect
|
|
|
|
Like :class:`HttpResponseRedirect`, but it returns a permanent redirect
|
|
(HTTP status code 301) instead of a "found" redirect (status code 302).
|
|
|
|
.. class:: HttpResponseNotModified
|
|
|
|
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:: HttpResponseBadRequest
|
|
|
|
Acts just like :class:`HttpResponse` but uses a 400 status code.
|
|
|
|
.. class:: HttpResponseNotFound
|
|
|
|
Acts just like :class:`HttpResponse` but uses a 404 status code.
|
|
|
|
.. class:: HttpResponseForbidden
|
|
|
|
Acts just like :class:`HttpResponse` but uses a 403 status code.
|
|
|
|
.. class:: HttpResponseNotAllowed
|
|
|
|
Like :class:`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:: HttpResponseGone
|
|
|
|
Acts just like :class:`HttpResponse` but uses a 410 status code.
|
|
|
|
.. class:: HttpResponseServerError
|
|
|
|
Acts just like :class:`HttpResponse` but uses a 500 status code.
|
|
|
|
.. note::
|
|
|
|
If a custom subclass of :class:`HttpResponse` implements a ``render``
|
|
method, Django will treat it as emulating a
|
|
:class:`~django.template.response.SimpleTemplateResponse`, and the
|
|
``render`` method must itself return a valid response object.
|
|
|
|
Custom response classes
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you find yourself needing a response class that Django doesn't provide, you
|
|
can create it with the help of :py:class:`http.HTTPStatus`. For example::
|
|
|
|
from http import HTTPStatus
|
|
from django.http import HttpResponse
|
|
|
|
class HttpResponseNoContent(HttpResponse):
|
|
status_code = HTTPStatus.NO_CONTENT
|
|
|
|
``JsonResponse`` objects
|
|
========================
|
|
|
|
.. class:: JsonResponse(data, encoder=DjangoJSONEncoder, safe=True, json_dumps_params=None, **kwargs)
|
|
|
|
An :class:`HttpResponse` subclass that helps to create a JSON-encoded
|
|
response. It inherits most behavior from its superclass with a couple
|
|
differences:
|
|
|
|
Its default ``Content-Type`` header is set to :mimetype:`application/json`.
|
|
|
|
The first parameter, ``data``, should be a ``dict`` instance. If the
|
|
``safe`` parameter is set to ``False`` (see below) it can be any
|
|
JSON-serializable object.
|
|
|
|
The ``encoder``, which defaults to
|
|
:class:`django.core.serializers.json.DjangoJSONEncoder`, will be used to
|
|
serialize the data. See :ref:`JSON serialization
|
|
<serialization-formats-json>` for more details about this serializer.
|
|
|
|
The ``safe`` boolean parameter defaults to ``True``. If it's set to
|
|
``False``, any object can be passed for serialization (otherwise only
|
|
``dict`` instances are allowed). If ``safe`` is ``True`` and a non-``dict``
|
|
object is passed as the first argument, a :exc:`TypeError` will be raised.
|
|
|
|
The ``json_dumps_params`` parameter is a dictionary of keyword arguments
|
|
to pass to the ``json.dumps()`` call used to generate the response.
|
|
|
|
Usage
|
|
-----
|
|
|
|
Typical usage could look like::
|
|
|
|
>>> from django.http import JsonResponse
|
|
>>> response = JsonResponse({'foo': 'bar'})
|
|
>>> response.content
|
|
b'{"foo": "bar"}'
|
|
|
|
Serializing non-dictionary objects
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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 :exc:`TypeError` will be raised.
|
|
|
|
Note that an API based on ``dict`` objects is more extensible, flexible, and
|
|
makes it easier to maintain forwards compatibility. Therefore, you should avoid
|
|
using non-dict objects in JSON-encoded response.
|
|
|
|
.. warning::
|
|
|
|
Before the `5th edition of ECMAScript
|
|
<https://262.ecma-international.org/5.1/#sec-11.1.4>`_ it was possible to
|
|
poison the JavaScript ``Array`` constructor. For this reason, Django does
|
|
not allow passing non-dict objects to the
|
|
:class:`~django.http.JsonResponse` constructor by default. However, most
|
|
modern browsers implement ECMAScript 5 which removes this attack vector.
|
|
Therefore it is possible to disable this security precaution.
|
|
|
|
Changing the default JSON encoder
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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)
|
|
|
|
.. _httpresponse-streaming:
|
|
|
|
``StreamingHttpResponse`` objects
|
|
=================================
|
|
|
|
.. class:: StreamingHttpResponse
|
|
|
|
The :class:`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
|
|
:ref:`generating large CSV files <streaming-csv-files>`.
|
|
|
|
.. admonition:: Performance considerations
|
|
|
|
Django is designed for short-lived requests. Streaming responses will tie
|
|
a worker process for the entire duration of the response. This may result
|
|
in poor performance.
|
|
|
|
Generally speaking, you should perform expensive tasks outside of the
|
|
request-response cycle, rather than resorting to a streamed response.
|
|
|
|
The :class:`StreamingHttpResponse` is not a subclass of :class:`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 bytestrings 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 ``content`` attribute. Instead, it has a
|
|
:attr:`~StreamingHttpResponse.streaming_content` attribute.
|
|
|
|
* You cannot use the file-like object ``tell()`` or ``write()`` methods.
|
|
Doing so will raise an exception.
|
|
|
|
:class:`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
|
|
middleware can't function normally. For example the ``ETag`` and
|
|
``Content-Length`` headers can't be generated for streaming responses.
|
|
|
|
The :class:`HttpResponseBase` base class is common between
|
|
:class:`HttpResponse` and :class:`StreamingHttpResponse`.
|
|
|
|
Attributes
|
|
----------
|
|
|
|
.. attribute:: StreamingHttpResponse.streaming_content
|
|
|
|
An iterator of the response content, bytestring encoded according to
|
|
:attr:`HttpResponse.charset`.
|
|
|
|
.. attribute:: StreamingHttpResponse.status_code
|
|
|
|
The :rfc:`HTTP status code <7231#section-6>` for the response.
|
|
|
|
Unless :attr:`reason_phrase` is explicitly set, modifying the value of
|
|
``status_code`` outside the constructor will also modify the value of
|
|
``reason_phrase``.
|
|
|
|
.. attribute:: StreamingHttpResponse.reason_phrase
|
|
|
|
The HTTP reason phrase for the response. It uses the :rfc:`HTTP standard's
|
|
<7231#section-6.1>` default reason phrases.
|
|
|
|
Unless explicitly set, ``reason_phrase`` is determined by the value of
|
|
:attr:`status_code`.
|
|
|
|
.. attribute:: StreamingHttpResponse.streaming
|
|
|
|
This is always ``True``.
|
|
|
|
``FileResponse`` objects
|
|
========================
|
|
|
|
.. class:: FileResponse(open_file, as_attachment=False, filename='', **kwargs)
|
|
|
|
:class:`FileResponse` is a subclass of :class:`StreamingHttpResponse`
|
|
optimized for binary files. It uses :pep:`wsgi.file_wrapper
|
|
<3333#optional-platform-specific-file-handling>` if provided by the wsgi
|
|
server, otherwise it streams the file out in small chunks.
|
|
|
|
If ``as_attachment=True``, the ``Content-Disposition`` header is set to
|
|
``attachment``, which asks the browser to offer the file to the user as a
|
|
download. Otherwise, a ``Content-Disposition`` header with a value of
|
|
``inline`` (the browser default) will be set only if a filename is
|
|
available.
|
|
|
|
If ``open_file`` doesn't have a name or if the name of ``open_file`` isn't
|
|
appropriate, provide a custom file name using the ``filename`` parameter.
|
|
Note that if you pass a file-like object like ``io.BytesIO``, it's your
|
|
task to ``seek()`` it before passing it to ``FileResponse``.
|
|
|
|
The ``Content-Length`` and ``Content-Type`` headers are automatically set
|
|
when they can be guessed from contents of ``open_file``.
|
|
|
|
``FileResponse`` accepts any file-like object with binary content, for example
|
|
a file open in binary mode like so::
|
|
|
|
>>> from django.http import FileResponse
|
|
>>> response = FileResponse(open('myfile.png', 'rb'))
|
|
|
|
The file will be closed automatically, so don't open it with a context manager.
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. method:: FileResponse.set_headers(open_file)
|
|
|
|
This method is automatically called during the response initialization and
|
|
set various headers (``Content-Length``, ``Content-Type``, and
|
|
``Content-Disposition``) depending on ``open_file``.
|
|
|
|
``HttpResponseBase`` class
|
|
==========================
|
|
|
|
.. class:: HttpResponseBase
|
|
|
|
The :class:`HttpResponseBase` class is common to all Django responses.
|
|
It should not be used to create responses directly, but it can be
|
|
useful for type-checking.
|